Skip to content

api-reference.md

Latest commit

 

History

History
645 lines (507 loc) · 34.1 KB

api-reference.md

File metadata and controls

645 lines (507 loc) · 34.1 KB
Raw
slug /api-reference

API Reference

The controller exposes a REST API for programmatic access. All /api/v1/* endpoints require authentication. By default Orka accepts Kubernetes ServiceAccount bearer tokens; when configured, external callers can use a valid OIDC JWT or generic context token instead.

Authentication

Send Kubernetes ServiceAccount and OIDC credentials with the standard bearer token header:

Authorization: Bearer <token>

Authentication modes:

  • Kubernetes ServiceAccount token — default mode. Tokens are validated with the Kubernetes TokenReview API.
  • OIDC JWT — enabled when the controller is configured with --oidc-issuer and --oidc-audience (or ORKA_OIDC_ISSUER / ORKA_OIDC_AUDIENCE). Tokens are validated against the issuer, audience, expiration, and RS256 signature. If --oidc-jwks-url is omitted, Orka discovers the JWKS URL from the issuer metadata.
  • Context token / kontxt TxToken — enabled with --context-token-profile=kontxt, --context-token-issuer, and --context-token-audience (or the matching ORKA_CONTEXT_TOKEN_* env vars). The built-in profile validates RS256 TxTokens with typ: txntoken+jwt, issuer/audience/time claims, kid, and required iat, txn, scope, and req_wl claims. By default tokens are read from the raw Txn-Token header; Authorization: Bearer support is opt-in with --context-token-headers=Txn-Token,Authorization:Bearer.
Txn-Token: <txntoken+jwt>

When a Task is created through OIDC or context-token authentication, Orka stamps the verified caller identity into immutable spec.requestedBy (subject, issuer, username, email, groups, and roles when present). Context-token Task creation also stamps immutable spec.transaction plus transaction labels/annotations for audit correlation. Clients cannot provide or override requestedBy or transaction; requests containing top-level or nested spec.requestedBy/spec.transaction are rejected with 400. See Kontxt TxToken integration for scope/tctx authorization, TTS exchange, delegation, and audit behavior.

Webhooks

GitHub webhooks use HMAC verification instead of bearer-token authentication.

Endpoint Method Description
/webhooks/github POST Accept GitHub issues / pull_request label triggers and pull request events for exact-head repository monitor runs

The controller requires ORKA_GITHUB_WEBHOOK_SECRET and verifies the X-Hub-Signature-256 header. Label trigger events can create agent Tasks for labels such as agent:implement. Pull request events can also queue exact-head RepositoryMonitor runs when a matching monitor has spec.review.exactEventEnabled: true. See GitHub Label Triggers for configuration and webhook behavior.

Tasks

Endpoint Method Description
/api/v1/tasks POST Create a task
/api/v1/tasks GET List tasks (paginated)
/api/v1/tasks/:id GET Get task details
/api/v1/tasks/:id DELETE Cancel/delete task
/api/v1/tasks/:id/logs GET Stream task logs
/api/v1/tasks/:id/result GET Get task result
/api/v1/tasks/:id/artifacts GET List task artifacts
/api/v1/tasks/:id/artifacts/:filename GET Download a task artifact
/api/v1/tasks/:id/plan GET Get task plan
/api/v1/tasks/:id/children GET Get child tasks

Task Execution Workspace Schema

POST /api/v1/tasks accepts the Task CRD shape. Agent Tasks may include spec.execution.workspace to request experimental workspace-backed execution through an upstream agent-sandbox or Agent Substrate installation. The controller validates the request, resolves/defaults the effective workspace settings, and injects them into the outer Kubernetes worker Job. The agent worker wrapper then claims and executes inside the upstream workspace.

Path Type Values/default Notes
spec.execution.workspace.enabled boolean default false Enables workspace-backed execution for an agent Task. The controller rejects enabled requests unless the selected provider is enabled.
spec.execution.workspace.provider string controller default provider; built-in default agent-sandbox Workspace backend: agent-sandbox or substrate.
spec.execution.workspace.templateRef.name string controller default template, if configured Workspace template name. Required when enabled: true and no controller default template is configured.
spec.execution.workspace.templateRef.namespace string Task namespace, or provider-specific default namespace when configured Namespace containing the workspace template.
spec.execution.workspace.reusePolicy string none; allowed none, session session derives the reuse key from spec.sessionRef.name and requires that field to be set.
spec.execution.workspace.cleanupPolicy string controller default cleanup policy; allowed delete, retain Cleanup behavior after the sandbox command exits.
spec.execution.workspace.boot boolean default false Substrate only. Boots the actor from scratch on first resume.
spec.execution.workspace.poolRef.name string empty Substrate only. Places the Task on a SubstrateActorPool; pooled workspaces currently require cleanupPolicy: delete.
spec.execution.workspace.poolRef.namespace string Task namespace Substrate only. Namespace containing the referenced pool.
spec.execution.workspace.snapshot object empty Substrate only, reserved. Non-empty restore/checkpoint settings are currently rejected.
spec.execution.workspace.hibernation object empty Substrate only, reserved. processMode: resident is currently rejected.

Workspace requests are only valid on spec.type: agent Tasks. See Agent Sandbox Workspaces and Substrate Execution Workspaces for configuration, validation rules, live smoke-test steps, and current limitations.

Get Task Plan

Retrieve the autonomous plan state for a task.

Endpoint: GET /api/v1/tasks/{id}/plan

Response (200):

{
  "TaskName": "build-feature",
  "Namespace": "default",
  "Iteration": 3,
  "Summary": "Completed auth module, working on CRUD endpoints",
  "ProgressPct": 40,
  "GoalComplete": false,
  "PlanDocument": "# Plan\n- [x] Auth\n- [ ] CRUD\n...",
  "CreatedAt": "2024-01-15T10:00:00Z",
  "UpdatedAt": "2024-01-15T12:30:00Z"
}

Errors:

  • 404 — No plan found for this task
  • 501 — Plan store not configured

Sessions

Endpoint Method Description
/api/v1/sessions GET List sessions
/api/v1/sessions/:id GET Get session transcript
/api/v1/sessions/:id DELETE Delete session

Memory

Memory endpoints manage namespace-scoped durable memories and reviewable memory proposals. See Memory for the full lifecycle, worker behavior, and examples.

Durable Memories

Endpoint Method Description
/api/v1/memories GET List durable memories
/api/v1/memories POST Create durable memory
/api/v1/memories/:id GET Get durable memory
/api/v1/memories/:id PUT Update durable memory
/api/v1/memories/:id DELETE Soft-delete durable memory
/api/v1/memories/:id/disable POST Disable memory for normal recall
/api/v1/memories/:id/enable POST Re-enable memory for normal recall

Common list query parameters: namespace, query/q, sessionName, agentName, taskName, parentTask, source, tags, ids, includeDisabled, includeDeleted, and limit.

Memory Proposals

Endpoint Method Description
/api/v1/memory-proposals GET List memory proposals
/api/v1/memory-proposals POST Create a memory proposal
/api/v1/memory-proposals/:id GET Get a memory proposal
/api/v1/memory-proposals/:id/review POST Record a review decision without applying it
/api/v1/memory-proposals/:id/apply POST Apply an accepted memory proposal into durable memory
/api/v1/memory-proposals/:id/archive POST Archive a proposal without applying it

Common list query parameters: namespace, taskName, agentName, type, status, query/q, and limit. Review and archive return 204 No Content. Apply accepts optional appliedBy and returns the linked durable memory JSON; repeated apply requests return the same memory.

Agents

Endpoint Method Description
/api/v1/agents POST Create an agent
/api/v1/agents GET List agents
/api/v1/agents/:name GET Get agent details
/api/v1/agents/:name PUT Update an agent
/api/v1/agents/:name DELETE Delete an agent

Skills

Endpoint Method Description
/api/v1/skills POST Create a skill
/api/v1/skills GET List skills
/api/v1/skills/:name GET Get skill details
/api/v1/skills/:name/content GET Get raw spec.content.inline markdown
/api/v1/skills/:name PUT Update a skill
/api/v1/skills/:name DELETE Delete a skill

Tools

Endpoint Method Description
/api/v1/tools GET List tools (built-in + CRDs)
/api/v1/tools/:name GET Get tool details

Tool CRD Schema

GET /api/v1/tools/:name returns built-in tool metadata or the full Tool CRD. Custom Tool CRDs can call plain HTTP endpoints or MCP servers hosted in durable Substrate actors.

Plain HTTP tools set spec.http.url and may inject authentication from a Kubernetes Secret into either the Authorization: Bearer header or the JSON request body:

apiVersion: core.orka.ai/v1alpha1
kind: Tool
metadata:
  name: tavily-search
spec:
  description: "Search the web for current information"
  parameters:
    type: object
    properties:
      query:
        type: string
    required:
      - query
  http:
    url: "https://api.tavily.com/search"
    method: POST
    authSecretRef:
      name: tavily-secret
      key: api-key
    authInject: body
    authBodyKey: api_key

MCP actor-backed tools set spec.mcp.substrateActor and may omit spec.http entirely. Orka creates or reuses the Substrate actor, waits for the MCP endpoint, stores the resolved endpoint in status.endpoint, and workers call the MCP tool through JSON-RPC tools/call using the Tool name as the MCP tool name.

apiVersion: core.orka.ai/v1alpha1
kind: Tool
metadata:
  name: repo-inspector
spec:
  description: "Inspect repository metadata through an MCP server"
  parameters:
    type: object
    properties:
      message:
        type: string
    required:
      - message
  mcp:
    path: /mcp
    substrateActor:
      templateRef:
        name: orka-mcp
        namespace: ate-demo
      poolRef:
        name: mcp-substrate-pool
      boot: true
Path Type Values/default Notes
spec.description string required Description shown to the LLM.
spec.parameters JSON Schema empty Tool argument schema in function-calling format.
spec.http.url string required for plain HTTP tools Endpoint called by workers. MCP actor-backed tools may omit it because Orka uses status.endpoint.
spec.http.method string default POST; allowed GET, POST, PUT, PATCH, DELETE HTTP method for plain HTTP tools. MCP actor-backed tools use POST.
spec.http.headers map empty Static headers sent with the request. Reserved token propagation headers cannot be overridden when outbound TxToken propagation is enabled.
spec.http.timeout duration default 30s Per-call request timeout.
spec.http.authSecretRef Secret key selector empty Secret value used as the auth token.
spec.http.authInject string default header; allowed header, body header sends Authorization: Bearer <token>. body injects the token into the JSON request body and is invalid for MCP actor-backed tools.
spec.http.authBodyKey string empty JSON key used when authInject: body.
spec.mcp.path string /mcp HTTP path exposed by the MCP server inside the actor.
spec.mcp.substrateActor.templateRef.name string required Substrate ActorTemplate hosting the MCP server.
spec.mcp.substrateActor.templateRef.namespace string Tool namespace or configured default Namespace containing the actor template.
spec.mcp.substrateActor.poolRef.name string empty Optional SubstrateActorPool for actor placement and reuse. The pool template must match the MCP actor template.
spec.mcp.substrateActor.poolRef.namespace string Tool namespace Namespace containing the referenced actor pool.
spec.mcp.substrateActor.boot boolean false Boots the actor from scratch on first resume; later reconciles reuse an already booted actor.
status.available boolean false Whether the controller can reach the resolved endpoint.
status.endpoint string empty Resolved non-secret endpoint used by workers. For MCP actor-backed tools this is the Substrate router endpoint.
status.actor object empty Safe actor metadata, including provider, actor ID, route host, resolved template, and pool reference.

MCP actor-backed tools require Substrate support to be enabled on the controller. If transport auth is needed for an MCP endpoint, set spec.http.authSecretRef, keep authInject as header or omit it, and omit spec.http.url.

Security

Repository security endpoints manage RepositoryScan configurations and their generated threat models, scan runs, findings, patch proposals, and remediation pull requests. Like other /api/v1/* endpoints, they require ServiceAccount bearer token authentication.

Endpoint Method Description
/api/v1/security/repositories POST Create a repository scan
/api/v1/security/repositories GET List repository scans
/api/v1/security/repositories/:name GET Get repository scan details
/api/v1/security/repositories/:name PUT Update repository scan spec
/api/v1/security/repositories/:name DELETE Delete repository scan
/api/v1/security/repositories/:name/threat-model GET Get latest threat model
/api/v1/security/repositories/:name/threat-model PUT Update threat model
/api/v1/security/repositories/:name/scans GET List scan runs
/api/v1/security/repositories/:name/scans POST Trigger manual scan
/api/v1/security/repositories/:name/slices GET List deterministic review slices
/api/v1/security/repositories/:name/slices/:sliceID GET Get review slice details
/api/v1/security/repositories/:name/dropped-findings GET List v2 dropped-finding diagnostics
/api/v1/security/repositories/:name/findings GET List findings
/api/v1/security/findings/:id GET Get finding details
/api/v1/security/findings/:id/dismiss POST Dismiss finding
/api/v1/security/findings/:id/reopen POST Reopen finding
/api/v1/security/findings/:id/validate POST Trigger validation
/api/v1/security/findings/:id/patch POST Generate patch proposal
/api/v1/security/findings/:id/patches GET List patch proposals
/api/v1/security/findings/:id/pull-request POST Create remediation PR

Common query parameters:

  • namespace — Kubernetes namespace to operate in.
  • limit — page size for list endpoints that support pagination.
  • continue — Kubernetes continue token for GET /api/v1/security/repositories.
  • cursor — store cursor for GET /api/v1/security/repositories/:name/scans, GET /api/v1/security/repositories/:name/slices, GET /api/v1/security/repositories/:name/dropped-findings, and GET /api/v1/security/repositories/:name/findings.
  • severity, validationStatus, state, sliceID, category — filters for GET /api/v1/security/repositories/:name/findings.
  • status — filter for GET /api/v1/security/repositories/:name/slices.
  • scanRunID, sliceID — filters for GET /api/v1/security/repositories/:name/dropped-findings.
  • recommended=true — filters findings to recommended remediation candidates.

Create Repository Scan

Endpoint: POST /api/v1/security/repositories

Request Body:

{
  "name": "example-repo",
  "namespace": "default",
  "spec": {
    "provider": "github",
    "repoURL": "https://github.com/example/app",
    "branch": "main",
    "ref": "v1.2.3",
    "schedule": "0 2 * * *",
    "validationMode": "light",
    "analysisAgentRef": {"name": "security-reviewer"}
  }
}

Response (201): The created RepositoryScan resource.

Required fields are name, spec.repoURL, and spec.analysisAgentRef.name. The API defaults or infers provider, owner, repository, branch, and validation mode where possible. Set spec.ref to pin scan tasks to a specific tag, branch, or commit SHA; when ref is set without branch, scan workspaces check out that ref directly instead of forcing the default main branch.

Security Findings Workflow

A typical remediation workflow is:

  1. List findings with GET /api/v1/security/repositories/:name/findings?namespace=default&recommended=true.
  2. Inspect evidence with GET /api/v1/security/findings/:id.
  3. Optionally validate with POST /api/v1/security/findings/:id/validate.
  4. Generate a patch with POST /api/v1/security/findings/:id/patch.
  5. Review patch proposals with GET /api/v1/security/findings/:id/patches. A proposal is successful only after patch summary and diff verification passes.
  6. Create a remediation pull request with POST /api/v1/security/findings/:id/pull-request.

Review slice and dropped-output inspection:

  1. List slices with GET /api/v1/security/repositories/:name/slices?namespace=default.
  2. Inspect one slice with GET /api/v1/security/repositories/:name/slices/:sliceID?namespace=default.
  3. List rejected v2 model output with GET /api/v1/security/repositories/:name/dropped-findings?namespace=default&scanRunID=scan_....

Repository Monitors

Repository monitor endpoints manage RepositoryMonitor configurations and their durable monitor runs, PR queue items, review state, and audit events. The current implementation supports GitHub pull request monitoring and read-only review task creation.

Endpoint Method Description
/api/v1/monitors/repositories POST Create a repository monitor
/api/v1/monitors/repositories GET List repository monitors
/api/v1/monitors/repositories/:name GET Get repository monitor details
/api/v1/monitors/repositories/:name PUT Update repository monitor spec
/api/v1/monitors/repositories/:name DELETE Delete repository monitor
/api/v1/monitors/repositories/:name/runs POST Trigger a manual monitor run
/api/v1/monitors/repositories/:name/runs GET List monitor runs
/api/v1/monitors/repositories/:name/items GET List current monitor items
/api/v1/monitors/events GET List monitor audit events

Common query parameters:

  • namespace - Kubernetes namespace to operate in.
  • limit - page size for list endpoints.
  • continue or cursor - pagination cursor for store-backed list endpoints.
  • kind, state, verdict, repairState, and automergeState - filters for GET /api/v1/monitors/repositories/:name/items.
  • name, runID, itemKind, itemNumber, and eventType - filters for GET /api/v1/monitors/events; name is required.

Context-token authorization scopes are orka:monitors:read for list/get endpoints, orka:monitors:write for create/update/delete, and orka:monitors:operate for manual run creation.

Create Repository Monitor

Endpoint: POST /api/v1/monitors/repositories

Request Body:

{
  "name": "example-app",
  "namespace": "default",
  "spec": {
    "provider": "github",
    "repoURL": "https://github.com/example/app",
    "branch": "main",
    "gitSecretRef": {"name": "repo-monitor-github"},
    "schedule": "*/30 * * * *",
    "targets": {
      "pullRequests": {
        "enabled": true,
        "includeDrafts": false,
        "maxPerRun": 10
      }
    },
    "agents": {
      "reviewer": {"name": "repo-reviewer"}
    },
    "review": {
      "event": "COMMENT",
      "staleReviewTTL": "24h",
      "exactEventEnabled": true
    },
    "policy": {
      "protectedLabels": ["security-sensitive"],
      "pauseLabels": ["orka:pause"]
    },
    "validation": {
      "mode": "changed",
      "commands": ["make test"]
    }
  }
}

Response (201): The created RepositoryMonitor resource.

Required fields are name, spec.repoURL, and spec.agents.reviewer.name when pull request monitoring is enabled. The API defaults or infers provider, owner, repository, branch, pull request enablement, pull request maxPerRun, review.event, and validation mode where possible. spec.repoURL must be a credential-free GitHub repository root URL such as https://github.com/owner/repo, https://github.com/owner/repo.git, or git@github.com:owner/repo.git; pull request, issue, branch/tree, blob/file, commit, query-string, fragment, non-GitHub, HTTP, and embedded-credential URLs are rejected.

Only GitHub pull request monitoring is supported in this slice. Requests that enable issue or commit targets, disable pull request monitoring, use a non-GitHub provider, set review.requireGreenCI, reference a missing/non-Claude reviewer runtime, or reference a reviewer Agent without usable Claude credentials are rejected with 400. The reviewer Agent must use runtime.type: claude, must reference a Secret in the monitor namespace, and that Secret must contain a non-empty ANTHROPIC_API_KEY or ANTHROPIC_FOUNDRY_API_KEY key. When gitSecretRef is set, the Git Secret must exist in the monitor namespace and contain a non-empty token, password, or GITHUB_TOKEN key.

Trigger Manual Monitor Run

Endpoint: POST /api/v1/monitors/repositories/{name}/runs

Request Body:

{
  "targetKind": "pull_request",
  "targetNumber": 123,
  "targetSHA": "abc123"
}

The request body can be omitted to run a full pull request inventory pass. targetKind must be empty or pull_request; targetNumber and targetSHA narrow the run to one PR or exact head. When targetNumber is set, the controller fetches that pull request directly from GitHub and does not retire unrelated monitor items from the repository-wide inventory. The API returns 409 when the monitor already has a queued or running run.

See Repository Monitors for the full workflow and CRD example.

Auth

Endpoint Method Description
/api/v1/auth/validate GET Validate auth token

Secrets

Endpoint Method Description
/api/v1/secrets GET List secret names (metadata only)

Chat

Endpoint Method Description
/api/v1/chat POST Send message (SSE streaming or JSON)
/api/v1/chat/config GET Get chat configuration and available tools
/api/v1/chat/:sessionId DELETE Cancel a chat session

See Interactive Chat for full chat documentation.

OpenAI-Compatible API

Endpoint Method Description
/openai/v1/chat/completions POST Chat completions (streaming & non-streaming)
/openai/v1/models GET List available models

See OpenAI Compatibility for details.

Anthropic-Compatible API

Endpoint Method Description
/anthropic/v1/messages POST Create a message (streaming & non-streaming)
/anthropic/v1/models GET List available models

The /anthropic/v1/messages endpoint injects built-in tools and runs server-side tool execution by default. Set X-Orka-Tools: disabled header to use as a transparent proxy instead. See Anthropic Compatibility for details.

Internal API (Worker Communication)

Endpoint Method Description
/internal/v1/results/:namespace/:taskName POST Submit task result
/internal/v1/artifacts/:namespace/:taskName/:filename POST Upload task artifact
/internal/v1/sessions/:namespace/:name/transcript GET Get session transcript
/internal/v1/plans/:namespace/:taskName POST Save plan state
/internal/v1/plans/:namespace/:taskName GET Get plan state
/internal/v1/messages/:namespace POST Send inter-agent message
/internal/v1/messages/:namespace/:taskName GET Get messages for a task

Save Plan State

Workers call this to persist autonomous plan state.

Endpoint: POST /internal/v1/plans/{namespace}/{taskName}

Request Body:

{
  "summary": "Completed phase 1",
  "progress_pct": 25,
  "goal_complete": false,
  "plan_document": "# Plan\n..."
}

Response: 204 No Content

Get Plan State

Workers call this to load the current plan state at startup.

Endpoint: GET /internal/v1/plans/{namespace}/{taskName}

Response (200): Same as public plan endpoint.

Errors:

  • 404 — No plan found

Send Message

Workers call this to send messages to sibling tasks (same parent coordinator).

Endpoint: POST /internal/v1/messages/{namespace}

Request Body:

{
  "fromTask": "worker-a",
  "toTask": "worker-b",
  "parentTask": "coordinator",
  "content": "Found a bug in the auth module"
}

Use "toTask": "*" to broadcast to all siblings.

Response: 204 No Content

Get Messages

Workers call this to check for unread messages.

Endpoint: GET /internal/v1/messages/{namespace}/{taskName}?parentTask={parentTask}&markRead={true|false}

Query Parameters:

  • parentTask (required) — Parent coordinator task name (scopes messages to siblings)
  • markRead (optional, default: true) — Whether to mark returned messages as read

Response (200):

[
  {
    "id": 1,
    "namespace": "default",
    "fromTask": "worker-b",
    "toTask": "worker-a",
    "parentTask": "coordinator",
    "content": "Found a bug in the auth module",
    "read": false,
    "createdAt": "2026-01-15T10:30:00Z"
  }
]

Health

Endpoint Method Description
/healthz GET Health check
/readyz GET Readiness check

Example Usage

# Create a task
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Authorization: Bearer $(kubectl create token orka-client)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-task",
    "type": "ai",
    "agentRef": {"name": "assistant"},
    "prompt": "Explain microservices architecture"
  }'

# Get task result
curl http://localhost:8080/api/v1/tasks/my-task/result \
  -H "Authorization: Bearer $(kubectl create token orka-client)"

# List task artifacts
curl http://localhost:8080/api/v1/tasks/my-task/artifacts \
  -H "Authorization: Bearer $(kubectl create token orka-client)"

# Download an artifact
curl -L http://localhost:8080/api/v1/tasks/my-task/artifacts/output.json \
  -H "Authorization: Bearer $(kubectl create token orka-client)" \
  -o output.json

# Chat with SSE streaming
curl -N http://localhost:8080/api/v1/chat \
  -H "Authorization: Bearer $(kubectl create token orka-client)" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create an AI task that summarizes Kubernetes best practices",
    "sessionId": "my-session"
  }'

Built-in Tools

These tools are available to AI worker agents:

Tool Description Parameters
web_search Search the web via configurable API (Tavily, etc.) query (required), limit (default 5)
code_exec Execute code in a sandboxed environment language (python/javascript/bash), code, timeout (max 60s)
file_read Read files from the workspace path, offset, limit (max 1MB)
web_fetch Fetch and extract URL content url (required), max_chars (default 50000), raw
file_write Write or append files in workspace paths path (required), content (required), mode (write/append), create_dirs

Coordination Tools

These tools are injected into AI worker agents when the Agent has coordination.enabled: true. They are not returned by GET /api/v1/tools.

The following tools are auto-injected when coordination is enabled:

Tool Description Parameters
delegate_task Delegate a subtask to another agent agent, prompt (required); namespace, priority, auto_retry, max_retries
wait_for_tasks Wait for delegated tasks to complete tasks (required), timeout (default 10m)
create_container_task Create a child container task name, image, command/args, env/workspace fields
cancel_task Cancel a running child task task_name (required); namespace, reason
send_message Send a message to a sibling task to_task (required, or * to broadcast), content (required)
check_messages Check for messages from sibling tasks mark_read (boolean, default true)
recall_memory Recall durable namespace-scoped memories query, tags, task_name, agent_name, source, limit, include_disabled
remember Submit a durable memory proposal for review content (required); title, description, tags, agent_name
propose_memory Submit a memory-adjacent governance proposal title (required); type, skill_name, description, content, patch, agent_name
search_transcript Search prior session transcripts query (required); session_name, exclude_session_name, roles, limit, max_snippet_length
create_pull_request Create a GitHub pull request task_name, head_branch, base_branch, title (required); body
check_pull_request_ci Check GitHub CI status without merging pr_number (required); task_name, repo_url, wait_timeout, poll_interval
list_pull_requests List open pull requests in a repository task_name, repo_url; per_page, page
check_pr_review_marker Check for an existing Orka PR review marker on a PR head pr_number (required); task_name, repo_url, head_sha
merge_pull_request Merge a GitHub pull request task_name, pr_number (required); merge_method, commit_title, commit_message
auto_merge_pull_request Poll CI checks and merge a PR when all pass task_name, pr_number (required); merge_method, commit_title, commit_message, timeout
review_pull_request Fetch PR diff for review pr_number (required); task_name, repo_url
post_review_comment Post a review on a PR pr_number, body, event (required); task_name, repo_url, comments
create_agent Create an Agent CRD at runtime name, provider, model (required); systemPrompt, tools, coordination
delete_agent Delete an Agent CRD name (required), namespace
update_plan Update the autonomous execution plan summary, plan_document (required); progress_pct, goal_complete

The following tools require explicit spec.tools[] entries on the Agent CRD:

Tool Description Parameters
list_issues List open GitHub issues in a repository task_name, repo_url; unassigned_only (default true), per_page, page
get_issue Fetch full details of a GitHub issue issue_number (required); task_name, repo_url
comment_on_issue Post a comment on a GitHub issue issue_number, body (required); task_name, repo_url

For GitHub tools that accept repo_url, explicit repository URLs are scope-checked when task context is available. The requested repository must match the current task's workspace repository or signed transaction repository context; otherwise the tool fails closed before resolving credentials or calling GitHub.

create_pr_monitor is exposed through the chat/management tool set rather than auto-injected into every coordinator worker. Parameters are name, repo_url, schedule, and agent_ref (required), plus optional namespace, provider_ref, gitSecretRef, per_page, review_event, and prompt. repo_url must be a credential-free GitHub repository root URL such as https://github.com/owner/repo, https://github.com/owner/repo.git, or git@github.com:owner/repo.git; pull request, issue, branch/tree, blob/file, commit, query-string, fragment, non-GitHub, HTTP, and embedded-credential URLs are rejected.

create_pr_monitor is the compatibility path for prompt-orchestrated scheduled PR monitors. It creates a scheduled type: ai Task, sets spec.workspace.gitRepo to repo_url, injects only the PR review loop tools, and instructs the task to pass the same repo_url to list_pull_requests, check_pr_review_marker, check_pull_request_ci, review_pull_request, and post_review_comment. The Agent referenced by agent_ref must be an AI Agent with coordination enabled and autonomous coordination disabled. The task needs a Git credential Secret through gitSecretRef or one of the supported default Secret names in the target namespace: git-credentials, github-credentials, copilot-token, github-token, or git-token. The selected Secret must contain a non-empty token, password, or GITHUB_TOKEN key.

check_pr_review_marker returns a hidden marker that the monitor should include unchanged in the subsequent review body. The marker includes repo, pr, head_sha, and sig fields, and matching is scoped to that repository, pull request, and exact head. Marker signatures are stable across GitHub token rotation. Operators can set ORKA_PR_REVIEW_MARKER_SECRET in the worker Task environment for dedicated marker signing and ORKA_PR_REVIEW_MARKER_PREVIOUS_SECRETS for comma-separated previous keys during rotation. Legacy markers are accepted only from a trusted review author, configured with ORKA_PR_REVIEW_MARKER_TRUSTED_AUTHOR or resolved from the Task's authenticated GitHub user.