ghola
Operates a ghola factory: submits a spec as a job, watches the stage graph, reads the audit log and the ladder, and keeps every change a pull request. A spec goes in, a pull request comes out, nothing merges itself.
- Model
- Inherited
- Effort
- high
- Extends
- iiibuilt-in
- Icon
- agent
- Color
- teal
- Visibility
- Listed
harness::
sendharnessv1.9.14Schema Entry point: ensure the session, persist the incoming message, and kick off a turn; returns fast (or merges into a running turn).
request - idempotency_keystring
Webhook dedupe: a repeated key returns the original `{session_id, turn_id}` and appends nothing.
- messagestringrequired
The incoming user message text.
- modelstring
Required on a new session unless `options.agent` supplies a model; an existing session inherits its last turn's model when omitted.
- optionsany ofany of (2)Variant 1
- agentstring
Directory agent profile id (`directory::agents::*`) replacing the built-in identity; new sessions only, refused with a prompt field.
- continuation_entry_idstring
Explicit continuation of a user entry on this session's active path. Resolved and bounded by Harness; never inferred from message text.
- functionsany of
Fail-closed dispatch policy; omitted means deny all on a new session and inherit on an existing one (`{ allow: [] }` strips explicitly).
Show 2 nestedHide nested
any of (2)Variant 1- allowstring[]
- denystring[]
- exposeall of
Show 1 nestedHide nested
all of (1)Variant 1valuestringenum agent_call, native
Variant 2valuenull - max_cost_usdnumber· double
Hard USD budget for the complete root-and-subagent session tree. Every model used by the tree must advertise catalog pricing.
- max_output_tokensinteger· uint64min 0
Per-generation output-token ceiling forwarded to the router.
- max_total_tokensinteger· uint64min 0
Hard input-plus-output token budget for the complete root-and-subagent session tree.
- max_turnsinteger· uint32min 0
- max_validation_retriesinteger· uint32min 0
Per-turn override of the validation-retry budget.
- metadataunknown
Tracing passthrough.
- outputany of
The turn's deliverable; default `{ type: "text" }`.
Show 2 nestedHide nested
any of (2)Variant 1one of (2)Variant 1- typestringrequiredenum text
Variant 2- schemaunknown
- typestringrequiredenum json
Variant 2valuenull - provider_optionsobject
Provider-native per-call options, namespaced by provider id.
- reasoningany of
Ask the harness to pick the effort from the model's catalog row instead of naming one: `lowest` is the model's lowest reasoning effort (never `off`), or the provider default when the model offers no effort choices. Exclusive with `thinking_level` and `provider_options`; the choice is returned as `reasoning` on the send response.
Show 2 nestedHide nested
any of (2)Variant 1valuestringenum lowestVariant 2valuenull - skillsstring[]
Exact skill ids advertised to the model; omitted or empty means all on a new session (existing: omitted inherits, empty resets).
- system_promptstring
- system_prompt_strategyany of
How `system_prompt` combines with the built-in prompt; omitting both prompt fields on an existing session inherits the prior prompt.
Show 2 nestedHide nested
any of (2)Variant 1one of (3)Variant 1valuestringenum overrideVariant 2valuestringenum enrichVariant 3valuestringenum disabledVariant 2valuenull - thinking_levelany of
Omitting both reasoning fields on an existing session inherits the prior turn's; naming either resolves fresh (`provider_options: {}` resets to the provider default).
Show 2 nestedHide nested
any of (2)Variant 1one of (2)Variant 1valuestringenum minimal, low, medium, high, xhighVariant 2valuestringenum offVariant 2valuenull
Variant 2valuenull - providerstring
- sessionany of
Applied when this send creates/ensures the session.
any of (2)Variant 1- kindstring
Session kind stored on creation: `user` (default), `automation` or `e2e`. Opaque to the harness; validated by session-manager.
- metadataunknown
- titlestring
Variant 2valuenull - session_idstring
Omit to create a new session.
response - acceptedbooleanrequired
- compactionany of
Set when the message was the `/compact` command: nothing was appended and no turn ran. The compaction runs in the background; its start and outcome reach every client through the transcript and `harness::on-compaction`.
any of (2)Variant 1- compaction_idstringrequired
- entry_idstringrequired
The transcript row its start notice takes (the `idempotency_key`'s `e_idem_` id when the send carried one).
Variant 2valuenull - deduplicatedboolean
True when `idempotency_key` matched an earlier send.
- mergedboolean
True when folded into an in-flight turn (steering).
- queuedboolean
True when the message was queued while a step was streaming; it lands in the transcript when the stream ends.
- reasoningany of
What `options.reasoning` resolved to; absent when the send named none.
any of (2)Variant 1- reasoning_effortstring
- thinking_levelany of
Show 2 nestedHide nested
any of (2)Variant 1one of (2)Variant 1valuestringenum minimal, low, medium, high, xhighVariant 2valuestringenum offVariant 2valuenull
Variant 2valuenull - session_idstringrequired
- turn_idstringrequired
harness::
statusharnessv1.9.14Schema Read a session's current turn. Returns a lean summary by default; pass verbose: true for the full runtime report and untruncated result.
request - session_idstringrequired
- verboseboolean
Include the full runtime report and unmodified result.
response any of (2)Variant 1- armed_wakesobject[]
WHAT the session is parked on, when `expects_wake`: each armed wake's watch and deadline, so "parked 12m on state operation_meta/status — never written" is readable from the outside instead of the session just looking quietly done.
- argsunknown
- created_atinteger· int64required
- expires_atinteger· int64
- filtersunknown
- function_idstring
The observed function and the observer's args and filters. Absent on records without a source.
- observer_idstringrequired
- childrenobject[]required
- function_call_idstringrequired
- session_idstringrequired
- turn_idstringrequired
- contextany of
The last generate step's context accounting (budget, categories, provider-exact usage once it lands) — what a UI meter should show instead of re-estimating the transcript. Verbose only; absent before the first generate.
any of (2)Variant 1- categoriesobjectrequired
Where the request's tokens sit. Categories are assembly-time estimates; `hook_guidance` is the measured growth after assembly (pre-generate hook appends and orphan-repair patches), 0 when the request left assembly unchanged.
Show 6 nestedHide nested
- hook_guidanceinteger· uint64min 0
- messagesobjectrequired
Estimated tokens of the assembled window's messages, by role.
Show 4 nestedHide nested
- assistantinteger· uint64requiredmin 0
- custominteger· uint64requiredmin 0
- function_resultinteger· uint64requiredmin 0
- userinteger· uint64requiredmin 0
- overheadinteger· uint64requiredmin 0
Provider framing plus response_format / provider_options fields.
- skillsinteger· uint64min 0
Selected skill bodies contained in the system prompt.
- system_promptinteger· uint64requiredmin 0
Final assembled system prompt excluding tokens attributed to `skills`: identity, per-step aids, and any compaction summary section.
- toolsinteger· uint64requiredmin 0
Function schemas exposed to the model.
- compactedbooleanrequired
The context carries a conversation summary: compacted on this step, or anchored on an earlier compaction entry (a previous step, the console's `/compact`). The summary's tokens count in `system_prompt`.
- effective_max_output_tokensinteger· uint64requiredmin 0
Output allocation `usable` was derived against.
- estimatorstring
Which estimator produced the numbers (`heuristic` until the context-manager resolves a real tokenizer). Absent when the context-manager predates the breakdown response.
- freeinteger· uint64requiredmin 0
- modelstringrequired
- prefix_divergencesobject[]
Already-sent rows this session's requests rewrote, newest last (at most [`MAX_PREFIX_DIVERGENCES`]), carried from step to step.
Show 9 nestedHide nested
- cache_readinteger· uint64min 0
`usage.cache_read` of the rewriting request: what the provider still reused.
- call_idstring
- causestring
What rewrote the row, as far as the harness can tell: `prune` (context-manager pruned or reduced function results to fit the budget that step) or `system_prompt` (row 0: a compaction summary or a prompt change).
- indexinteger· uint64min 0
First row (0 = system prompt, then one per message) that differs from the session's previous request. Absent when only the provider's wire mapping changed.
- prev_leninteger· uint64min 0
Rows the previous request carried.
- provider_notestring
The provider's own wire-level finding, cause included, when it reported one (a final-message warning starting with [`PROVIDER_PREFIX_NOTE`]).
- rolestring
- stepinteger· uint64requiredmin 0
- turn_idstringrequired
- prompt_sections_fallbackstring
Why no shared prefix went out: `disabled` (config), `no_stable_prefix` (empty identity prompt) or `prefix_rewritten` (a pre_generate hook replaced the prompt head; its prompt still wins, it just shares nothing).
- prompt_surface_digeststring
Identity of the shared prompt prefix this generation went out with (`sha256:` of the stable section) — present only when the request carried `system_sections`. A local identity, never a provider hit; `usage.cache_read` is the reuse signal.
- providerstring
- session_cost_usdnumber· double
Running cost of the whole session in USD, accumulated across every generation step. `usage.cost_usd` is one step's bill — on providers with steep cache discounts the per-step number swings two orders of magnitude, so a chip showing it alone reads as a bouncing total.
- session_idstringrequired
- stepinteger· uint64requiredmin 0
- summarized_head_tokensinteger· uint64min 0
Size of the history that summary replaced.
- timestampinteger· int64required
- totalinteger· uint64requiredmin 0
Final request estimate: categories plus post-assembly growth.
- turn_idstringrequired
- usableinteger· uint64requiredmin 0
The input budget the window was fit into.
- usageany of
Actual provider usage for this generation, stamped after the terminal frame; absent when the provider returned none (or the generation never completed).
Show 2 nestedHide nested
any of (2)Variant 1- cache_readinteger· uint64min 0
- cache_writeinteger· uint64min 0
- cost_usdnumber· double
- inputinteger· uint64min 0
- outputinteger· uint64min 0
- reasoninginteger· uint64min 0
Variant 2valuenull
Variant 2valuenull - depthinteger· uint32min 0
- expects_wakeboolean
The session owns an armed wake (a one-shot notify subscription, claimed or not, until its delivery has seeded the woken turn), or its finished turn drained a queued message and is about to be reseeded: a completed turn here is NOT the run's outcome — a later turn in this session carries it. Mirrors the `terminal` flag on `harness::on-turn-completed` (`expects_wake == !terminal`). Pollers (e.g. workflow reconcile) must treat `completed && expects_wake` as still running.
- failureany of
Why a `failed` turn failed: `code`, and `retryable` when the failure is temporary, so a later send into this session may succeed. Present in the lean report too, only on a failed turn.
any of (2)Variant 1- codestringrequired
The failure code, e.g. `router/provider_transient` or `harness.turn_internal`.
- retryablebooleanrequired
The failure is temporary, so a later send into the session may succeed: a provider outage, rate limit or cut stream that outlasted the turn's `max_transient_resumes` recovery generations, or a turn the harness could not schedule.
Variant 2valuenull - max_transient_resumesinteger· uint32min 0
- max_turnsinteger· uint32min 0
- max_validation_retriesinteger· uint32min 0
- partial_result_availableboolean
- pending_function_callsstring[]
- queuedobject[]
Messages queued while a step streams, in arrival order; they land in the transcript when the stream ends.
- channelany of
How the message reached the session: `direct` is a person (or a client acting as one), `notification` an observer or system notice, `invoked-agent` a sub-agent's opening task. Absent on rows parked by a harness that predates the field. The console hides every row that is not `direct` from the person's queued-messages strip.
Show 2 nestedHide nested
any of (2)Variant 1valuestringenum direct, invoked-agent, notificationVariant 2valuenull - entry_idstringrequired
Deterministic transcript entry id the drain appends under, so a redelivered drain is a no-op.
- idstringrequired
- messageany ofrequired
The canonical transcript message union. Untagged: the single-variant role tags disambiguate deserialization (assistant/function_result/custom are tried before user so their required fields gate the match).
Show 4 nestedHide nested
any of (4)Variant 1- contentone of[]required
Show 7 nestedHide nested
one of (7)Variant 1- textstringrequired
- typestringrequiredenum text
Variant 2- attachment_idstring
Optional link to the stored original of this inline image (`session::put-attachment`, resolvable with `session::get-attachment`). Lets readers ask `session::messages { include_image_data: false }` and fetch the bytes lazily instead of receiving them inline. Persisted verbatim on the transcript; model-bound consumers never see it (see [`ContentBlock::strip_files`]). Omitted on the wire when absent so legacy transcripts stay byte-identical.
- datastringrequired
- mimestringrequired
- typestringrequiredenum image
Variant 3- attachment_idstringrequired
- mimestringrequired
- namestringrequired
- sizeinteger· uint64requiredmin 0
- typestringrequiredenum file
Variant 4- signaturestring
- textstringrequired
- typestringrequiredenum thinking
Variant 5- datastringrequired
- typestringrequiredenum redacted_thinking
Variant 6- argumentsunknownrequired
- function_idstringrequired
- idstringrequired
- typestringrequiredenum function_call
Variant 7- contentunknown[]required
- function_call_idstringrequired
- is_errorboolean
- typestringrequiredenum function_result
- error_kindany of
Show 2 nestedHide nested
any of (2)Variant 1valuestringenum auth_expired, rate_limited, context_overflow, transient, permanentVariant 2valuenull - error_messagestring
- modelstringrequired
- native_stop_reasonstring
- providerstringrequired
- rolestringrequiredenum assistant
- stop_reasonstringrequiredenum end, length, function_call, aborted, error
- timestampinteger· int64required
- usageany of
Show 2 nestedHide nested
any of (2)Variant 1- cache_readinteger· uint64min 0
- cache_writeinteger· uint64min 0
- cost_usdnumber· double
- inputinteger· uint64min 0
- outputinteger· uint64min 0
- reasoninginteger· uint64min 0
Variant 2valuenull - warningsstring[]
Variant 2- contentone of[]required
Show 7 nestedHide nested
one of (7)Variant 1- textstringrequired
- typestringrequiredenum text
Variant 2- attachment_idstring
Optional link to the stored original of this inline image (`session::put-attachment`, resolvable with `session::get-attachment`). Lets readers ask `session::messages { include_image_data: false }` and fetch the bytes lazily instead of receiving them inline. Persisted verbatim on the transcript; model-bound consumers never see it (see [`ContentBlock::strip_files`]). Omitted on the wire when absent so legacy transcripts stay byte-identical.
- datastringrequired
- mimestringrequired
- typestringrequiredenum image
Variant 3- attachment_idstringrequired
- mimestringrequired
- namestringrequired
- sizeinteger· uint64requiredmin 0
- typestringrequiredenum file
Variant 4- signaturestring
- textstringrequired
- typestringrequiredenum thinking
Variant 5- datastringrequired
- typestringrequiredenum redacted_thinking
Variant 6- argumentsunknownrequired
- function_idstringrequired
- idstringrequired
- typestringrequiredenum function_call
Variant 7- contentunknown[]required
- function_call_idstringrequired
- is_errorboolean
- typestringrequiredenum function_result
- detailsunknownrequired
- function_call_idstringrequired
- function_idstringrequired
- is_errorbooleanrequired
- rolestringrequiredenum function_result
- timestampinteger· int64required
Variant 3- contentone of[]required
Show 7 nestedHide nested
one of (7)Variant 1- textstringrequired
- typestringrequiredenum text
Variant 2- attachment_idstring
Optional link to the stored original of this inline image (`session::put-attachment`, resolvable with `session::get-attachment`). Lets readers ask `session::messages { include_image_data: false }` and fetch the bytes lazily instead of receiving them inline. Persisted verbatim on the transcript; model-bound consumers never see it (see [`ContentBlock::strip_files`]). Omitted on the wire when absent so legacy transcripts stay byte-identical.
- datastringrequired
- mimestringrequired
- typestringrequiredenum image
Variant 3- attachment_idstringrequired
- mimestringrequired
- namestringrequired
- sizeinteger· uint64requiredmin 0
- typestringrequiredenum file
Variant 4- signaturestring
- textstringrequired
- typestringrequiredenum thinking
Variant 5- datastringrequired
- typestringrequiredenum redacted_thinking
Variant 6- argumentsunknownrequired
- function_idstringrequired
- idstringrequired
- typestringrequiredenum function_call
Variant 7- contentunknown[]required
- function_call_idstringrequired
- is_errorboolean
- typestringrequiredenum function_result
- custom_typestringrequired
- detailsunknown
- displaystring
- rolestringrequiredenum custom
- timestampinteger· int64required
Variant 4- contentone of[]required
Show 7 nestedHide nested
one of (7)Variant 1- textstringrequired
- typestringrequiredenum text
Variant 2- attachment_idstring
Optional link to the stored original of this inline image (`session::put-attachment`, resolvable with `session::get-attachment`). Lets readers ask `session::messages { include_image_data: false }` and fetch the bytes lazily instead of receiving them inline. Persisted verbatim on the transcript; model-bound consumers never see it (see [`ContentBlock::strip_files`]). Omitted on the wire when absent so legacy transcripts stay byte-identical.
- datastringrequired
- mimestringrequired
- typestringrequiredenum image
Variant 3- attachment_idstringrequired
- mimestringrequired
- namestringrequired
- sizeinteger· uint64requiredmin 0
- typestringrequiredenum file
Variant 4- signaturestring
- textstringrequired
- typestringrequiredenum thinking
Variant 5- datastringrequired
- typestringrequiredenum redacted_thinking
Variant 6- argumentsunknownrequired
- function_idstringrequired
- idstringrequired
- typestringrequiredenum function_call
Variant 7- contentunknown[]required
- function_call_idstringrequired
- is_errorboolean
- typestringrequiredenum function_result
- rolestringrequiredenum user
- timestampinteger· int64required
- originunknown
- queued_atinteger· int64required
- session_idstringrequired
- resultunknown
- result_errorstring
- session_idstringrequired
- statusstringrequiredenum running, awaiting_functions, completed, cancelled, failed
The coarse, harness-internal turn lifecycle (harness.md § API Reference). Finer-grained than the session's `status`, which the loop derives from it.
- stepinteger· uint64requiredmin 0
- stop_reasonstring
Why a `completed` turn stopped when the model did not end it itself (`max_turns`). Present in the lean report too: a poller that reads `completed` with no error must still be able to tell an exhausted budget from a finished task.
- transient_resumesinteger· uint32min 0
- turn_countinteger· uint32requiredmin 0
- turn_idstring
- validation_retriesinteger· uint32min 0
Variant 2valuenullshell::
execidev0.13.7Schema Run a command in the foreground and return its full output. Put the program in `command` (string) and arguments in `args` (string[]), never argv in `command`. Host-only cwd/env/stdin reject S210 on a sandbox target. Errors return { code, message }; common: S216 host exec error, S300 VM boot failed, S200 in-VM failure.
request - argsstring[]
Arguments, in order (all strings). Omit/null to tokenize `command` shell-words style; pass an array (even empty) to use it verbatim.
- commandstringrequired
Program name (PATH-resolved) or path to an executable, as a string; put arguments in `args`.
- cwdstring
Working directory (host only, S210 on sandbox); jail-confined like shell::fs::* paths (S215 on escape), must be an existing directory.
- envobject
Per-call env values (host only, S210 on sandbox); exec-hijacking keys (PATH, IFS, HOME, LD_*/DYLD_*, …) reject the whole call S210.
- stdinstring
Bytes written to the program's stdin, then EOF (host only, S210 on sandbox); omit to leave stdin at /dev/null.
- targetall of
Where to run the command. Defaults to the host worker; pass `{ kind: "sandbox", sandbox_id }` to forward the call to a microVM.
all of (1)Variant 1one of (2)Variant 1- kindstringrequiredenum host
Variant 2- kindstringrequiredenum sandbox
- sandbox_idstring· uuidrequired
- timeout_msinteger· uint64min 0
Per-call timeout in milliseconds, capped at the configured max; negative or fractional values fall back to the default.
response - duration_msinteger· uint64requiredmin 0
- exit_codeinteger· int32
- stderrstringrequired
- stderr_truncatedbooleanrequired
- stdoutstringrequired
- stdout_truncatedbooleanrequired
- timed_outbooleanrequired
shell::
statusidev0.13.7Schema Fetch the full record (status, exit_code, timing, output) of a background job by job_id. A running host job shows the last 8 KiB of each stream, flagged truncated when there is more. Errors return { code, message }; common: S211 no such job.
request - job_idstringrequired
response - jobobjectrequired
- argvstring[]required
- exit_codeinteger· int32
- finished_at_msinteger· uint64min 0
- idstringrequired
- started_at_msinteger· uint64requiredmin 0
- statusstringrequiredenum running, finished, killed, failed
- stderrstringrequired
- stderr_truncatedbooleanrequired
- stdoutstringrequired
- stdout_truncatedbooleanrequired
audit::
readaudit-logv0.1.1Schema Entries, optionally narrowed by kind or subject
request - kindstring
- limitinteger
Newest N entries. Default 200.
- subjectstring
response - entriesobject[]
- actorstringrequired
Who or what decided: a person, a worker, a rule id.
- atintegerrequired
When the entry was sealed, epoch milliseconds.
- detailobjectrequired
Whatever else the decision carries.
- hashstringrequired
SHA-256 over every field above.
- kindstringrequired
What kind of decision, in the deployment's vocabulary.
- prevstringrequired
Hash of the entry before; 64 zeros at the start.
- seqintegerrequired
Position in the chain, starting at 0.
- subjectstringrequired
What the decision was about.
- vintegerrequired
Entry format version.
- problemsstring[]
- totalinteger
Matching entries, before the limit cut.
audit::
summaryaudit-logv0.1.1Schema What the log says: whether it verifies, and what it counts
request - bystring[]
Fields to count by: top-level or detail. Defaults to kind and actor.
response - byobject
One counts object per requested field.
- entriesinteger
- filesstring[]
- first_atinteger
- last_atinteger
- problemsstring[]
- verifiedboolean
- verified_throughinteger
audit::
verifyaudit-logv0.1.1Schema Is the chain intact, and from which entry is it not
request Empty objectresponse - entriesinteger
- folderstring
- okboolean
- problemsstring[]
- verified_throughinteger
Last seq that verified. Everything after it is unproven.
ladder::
listladderv0.1.1Schema Everything on the ladder, both sides, with rungs, direction and catches
request Empty objectresponse Empty objectladder::
evaluateladderv0.1.1Schema Ask the ladder about a proposed write at a given rung, without being a turn
request Empty objectresponse Empty object