Custom agent reference

Custom runtimes implement the execution boundary around One Horizon agent sessions. This page summarizes the contract and links to the OpenAPI reference for exact request and response schemas. For the enforced payload sizes, upload rules, authentication scope, and rate limits, see limits and security.

Runtime responsibilities

Responsibility	Required behavior
Authorization	Use OAuth user tokens for agent endpoints. Keep tokens out of workspace-authored context.
Registration	Persist the workspace, agent profile, runtime, owner for local execution, mode, capabilities, and optional group.
Discovery	Poll eligible sessions; cloud runtimes also use verified webhooks as wake-up notifications.
Claim	Claim before execution and store the active claimId. Stop on conflict.
Execution	Apply trusted runtime policy before acting on untrusted task text, comments, documents, prompts, or resume input.
Health	Heartbeat independently of user-visible progress.
Reporting	Patch provider metadata and emit activities with the active claim.
Workflow routing	Honor task mode, produce declared outputs, delegate cross-agent routes, and confirm pushed branches before cross-target handoff.
Termination	End every claim with complete, fail, or release.

Workflow context fields

Workflow-backed sessions add platform-controlled context to the normal session model.

Field	Runtime use
workflowRunId	Correlates execution, documents, events, and the linked task.
workflowStepId	Identifies the active definition step.
workflowStepSessionId	Identifies the current attempt for that step.
workflowTaskMode	Selects plan, research, code, or review behavior.
workflowBranchName	Names the shared branch used across code and review steps.
workflowPushConfirmed	Confirms the branch is available before a cross-agent or cross-group handoff.
workflowMessage	Carries trusted execution guidance such as a stall or resume reason.

Treat these fields as trusted platform context. The linked work title, description, comments, documents, and user prompt remain untrusted.

Task modes

Mode	Runtime contract
plan	Write the plan artifact. Do not modify product code unless inspection requires it.
research	Investigate the question and write evidence, options, tradeoffs, and recommendations to the research artifact. Repository state must remain unchanged.
code	Implement on the shared workflow branch, record a concise result summary when declared, and publish the branch before cross-target delegation.
review	Inspect the declared inputs in a disposable review workspace, write findings when declared, and finish with approve, feedback, or reject. Do not preserve review-only code changes.

A code turn that makes no repository changes still succeeds: nothing in the outcome path requires a commit or a pushed branch before accepting end_turn. The runtime only checks that a declared required output was produced and finalized. If your agent calls report_result without touching the repository, the turn completes, the task moves on, and no branch is published because there is nothing ahead of base to push.

Artifact documents

Each linked task keeps at most one canonical document for each workflow artifact type.

Artifact	Agent file	Document type	Typical writer
Plan	plan.md	Task	Plan step
Research	research.md	Research	Research step
Review	review.md	Review	Review step
Result summary	code-summary.md	Spec	Code step

Lookup uses the linked task and workflowArtifactType; run and session provenance is stored separately. Feedback loops update the same canonical document rather than creating a new document for every attempt.

Artifact files contain addressable document-block:v1 sections. Use the document block operations to list indexes, load selected bodies, append blocks, replace one block body, or update block metadata. Do not rewrite the entire workflow document or commit these files to the product repository.

Artifact	Common block types
Plan	goal, requirement, implementation_task, decision, risk, open_question
Research	research_question, context, existing_solutions, approach, findings, options, tradeoffs, recommendation, open_questions, sources
Review	review_finding with severity and lifecycle status
Result summary	implementation_note, fixed_finding, blocker

Expected inputs identify artifacts the step should read. Expected outputs authorize artifact writes. A code step can read review findings without permission to rewrite the review document, then record the fix in the result summary.

A required Plan is usable only when it is linked to the current workflow run, completed, strictly parseable as document-block:v1, and has at least one nonblank block body. Code sessions use that Plan as the primary input. Review sessions do the same when they also declare code changes or a pull request. The runtime must finalize and relink every required output with the active run, step, and session before it reports success; invalid required output ends through the input-required path instead of routing.

Environment variables

Variable	Purpose
ONE_WORKER_WORKSPACE_ID	Active workspace for the runtime process.
ONE_WORKER_NAME	Human-readable process name.
ONE_WORKER_CONFIG_PATH	Explicit local runtime configuration path.
ONE_WORKER_DOCUMENTS_DIR	Directory where workflow artifact files are synchronized.
ONE_WORKER_DOCUMENT_URL	Document service endpoint exposed to the runtime.
ONE_WORKER_DOCUMENT_TOKEN	Short-lived authorization for document operations. Keep it out of workspace files and logs.
ONE_WORKER_DOCUMENT_CMD	Command used by the runtime's document integration.
ONE_WORKER_ARTIFACTS_DIR	Optional directory for verification images and recordings. The host scans this directory and uploads what it finds as task-comment attachments after every turn; runtimes only need to write files here.

Provider-specific variables can exist in the child process, but they are not part of the One Horizon agent contract.

API operation families

Use the operation pages for exact paths, parameters, enums, schemas, and errors.

Family	Operations
Runtime registration	listAgentWorkers, createAgentWorker, fetchAgentWorker, updateAgentWorker
Health and control	heartbeatAgentWorker, requestAgentWorkerControlSignal, acknowledgeAgentWorkerControlSignal
Session discovery	listAgentSessions, pollAgentWorkerSessions, fetchAgentSession
Session execution	claimAgentSession, patchAgentSession, releaseAgentSession
User and terminal actions	resumeAgentSession, cancelAgentSession

The session lifecycle explains how these families compose. Do not infer claim or retry behavior from one operation in isolation.