Events

Look up the complete FactoryEvent and FactoryResponseEvent corpus, stream roles, reconnect and lifecycle contracts, and static SSE examples on a stable hybrid docs route.

Event Corpus

The published corpus resolves from packaged OpenAPI at build time. It labels the three stream operations, renders the complete FactoryEvent envelope and discriminator payload catalog, and renders the FactoryResponseEvent envelope with kind, phase, provenance, and payload dimensions without claiming every Cartesian combination is valid. It also documents reconnect cursor precedence, identity handshake headers, stream-generation invalidation, retained-history and keepalive behavior, the JSON reconnect-probe alternative, and static SSE frame examples that never open a live connection.

Event stream operations

Canonical, ephemeral, and compatibility-only SSE operations from packaged OpenAPI. The global GET /events stream is never preferred.

Canonical session-scoped FactoryEvent stream
get /factory-sessions/{session_id}/events
CanonicalPreferred
Payload root
FactoryEvent
Operation
getEventsBySessionId
Schema anchor
#components-schemas-FactoryEvent
Ephemeral FactoryResponseEvent stream
get /factory-sessions/{session_id}/response-events
EphemeralNot preferredNot canonical replay
Payload root
FactoryResponseEvent
Operation
getFactoryResponseEventsBySessionId
Schema anchor
#components-schemas-FactoryResponseEvent
Ephemeral observation only — do not treat response events as canonical FactoryEvent replay state.
Compatibility-only process-global FactoryEvent stream
get /events
Compatibility-onlyNot preferredNon-canonical
Payload root
FactoryEvent
Operation
getEvents
Schema anchor
#components-schemas-FactoryEvent
Compatibility-only / non-canonical. Prefer the canonical session FactoryEvent stream for new consumers.

FactoryEvent envelope

Shared envelope fields for every canonical SSE frame. The type discriminator selects a payload schema; payload-only schemas below are not complete envelopes.

FactoryEvent

object

Versioned Agent Factory event message. This is the intended canonical schema for customer event streams, history projection, record/replay artifacts, and runtime diagnostics. New fields use camelCase even when older REST resource schemas still contain legacy snake_case fields.

additionalPropertiesfalse (closed)

Fields

schemaVersionRequiredstring
Version of the factory event envelope schema.
- enum"agent-factory.event.v1"
idRequiredstring
Stable event identifier. Record/replay artifacts must preserve this value.
typeRequiredFactoryEventType
$ref →FactoryEventType (reference link; not expanded recursively)
contextRequiredFactoryEventContext
$ref →FactoryEventContext (reference link; not expanded recursively)
payloadRequiredoneOf

FactoryEvent envelope example

Corpus-constructed examplejson

Complete FactoryEvent envelope with type RUN_REQUEST and a RunRequestEventPayload payload body. Field names and enums come from packaged OpenAPI; nested values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "schemaVersion": "agent-factory.event.v1",
  "id": "example-id",
  "type": "RUN_REQUEST",
  "context": {
    "sequence": 1,
    "tick": 0,
    "eventTime": "1970-01-01T00:00:00.000Z"
  },
  "payload": {
    "recordedAt": "1970-01-01T00:00:00.000Z",
    "factory": {
      "name": "example-factory"
    }
  }
}

Envelope components

Component schemas referenced by the FactoryEvent envelope fields. These shapes come from packaged OpenAPI — the same corpus as the envelope above.

FactoryEventType `(envelope.type)`

FactoryEventType

string

Canonical event vocabulary for customer-visible runtime changes. Work entering the factory is represented as WORK_REQUEST, including single-work submissions that are normalized into one-work requests.

enum"RUN_REQUEST" | "INITIAL_STRUCTURE_REQUEST" | "FACTORY_CHANGE" | "WORK_REQUEST" | "RELATIONSHIP_CHANGE_REQUEST" | "DISPATCH_REQUEST" | "MODEL_REQUEST" | "MODEL_RESPONSE" | "INFERENCE_REQUEST" | "INFERENCE_RESPONSE" | "SCRIPT_REQUEST" | "SCRIPT_RESPONSE" | "AGENT_RUN_RESPONSE" | "DISPATCH_RESPONSE" | "WORK_STATE_CHANGE" | "FACTORY_STATE_RESPONSE" | "RUN_RESPONSE" | "SESSION_STARTED" | "SESSION_PAUSED" | "SESSION_RESUMED" | "SESSION_RESULT_UPDATED" | "SESSION_COMPLETED" | "SESSION_LIFECYCLE_CONTROL" | "ORCHESTRATOR_PHASE_CHANGED" | "ORCHESTRATOR_CHECKPOINT_WRITTEN" | "DISPATCH_QUEUED" | "DISPATCH_INTERRUPTED" | "DISPATCH_RECONCILED" | "JAVASCRIPT_CHECKPOINT_REF" | "JAVASCRIPT_PHASE_CHANGE" | "ARTIFACT_CREATED"

FactoryEventContext `(envelope.context)`

FactoryEventContext

object

additionalPropertiesfalse (closed)

Fields

sequenceRequiredinteger
Append-only event-log sequence number.
- minimum0
tickRequiredinteger
Logical engine tick observed by the runtime.
- minimum0
eventTimeRequiredstringformat: date-time
Wall-clock event timestamp for customer explanation and diagnostics. ISO8601 timestamp.
sessionIdOptionalstring
Canonical factory session identity for session-scoped events; payloads must not restate it.
sessionSequenceOptionalinteger
Monotonic per-session ordering used for replay deduplication within one session.
- minimum0
orchestratorKindOptionalFactoryOrchestratorKind
Canonical orchestrator kind for session-scoped events; payloads must not restate it.
$ref →FactoryOrchestratorKind (reference link; not expanded recursively)
orchestratorDialectOptionalstring
Optional JavaScript workflow dialect when orchestrator.kind = JAVASCRIPT.
phaseIdOptionalstring
Canonical workflow phase identifier; payloads must not restate it.
phaseNameOptionalstring
Canonical workflow phase name for customer-visible diagnostics.
checkpointIdOptionalstring
Canonical checkpoint identifier for checkpoint-scoped events; payloads must not restate it.
requestIdOptionalstring
Canonical request identity for all request-scoped events; payload metadata must not restate it.
traceIdsOptionalarray
Canonical trace identifiers that contributed to this event; payloads must not restate them.
workIdsOptionalarray
Canonical work identities correlated to this event; payloads must not restate them.
dispatchIdOptionalstring
Canonical dispatch identity for dispatch and inference events; payloads must not restate it.
currentChainingTraceIdOptionalstring
Canonical chaining-trace identifier for the dispatch currently represented by this event context.
previousChainingTraceIdsOptionalarray
Canonical predecessor chaining traces consumed by the dispatch in deterministic order.
sourceOptionalstring
Human-readable source such as api, filewatcher, replay, cron, or worker.

FactoryEvent.type → payload map

Every current type discriminator mapping from packaged OpenAPI. Inventory count is derived live — not a frozen product quota.

FactoryEvent payload catalog

Schema-backed fields for each discriminator payload. These are payload-only schemas — the shared FactoryEvent envelope fields remain above.

Event catalog

`AGENT_RUN_RESPONSEAgentRunResponseEventPayload`

#AGENT_RUN_RESPONSE

AgentRunResponseEventPayload example

Corpus-constructed examplejson

Payload-only AgentRunResponseEventPayload body. Mapped from FactoryEvent type AGENT_RUN_RESPONSE. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "agentRunId": "example-agentRunId",
  "outcome": "ACCEPTED",
  "durationMillis": 0
}

AgentRunResponseEventPayload

object

Response details captured after an AGENT_RUN workstation completes an agent loop. Final output stays on DispatchResponse; bounded agent-run diagnostics and transcript metadata stay on this agent-boundary event instead of being copied onto provider-session inspection surfaces.

additionalPropertiesfalse (closed)

Fields

agentRunIdRequiredstring
Stable identifier for this agent-run boundary event.
outcomeRequiredWorkOutcome
$ref →WorkOutcome (reference link; not expanded recursively)
durationMillisRequiredintegerformat: int64
Agent-loop execution duration in milliseconds.
- minimum0
diagnosticsOptionalSafeWorkDiagnostics
$ref →SafeWorkDiagnostics (reference link; not expanded recursively)

Event catalog

`ARTIFACT_CREATEDArtifactCreatedEventPayload`

#ARTIFACT_CREATED

ArtifactCreatedEventPayload example

Corpus-constructed examplejson

Payload-only ArtifactCreatedEventPayload body. Mapped from FactoryEvent type ARTIFACT_CREATED. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "artifact": {
    "id": "example-id",
    "kind": "FINAL_RESULT",
    "visibility": "PUBLIC"
  }
}

ArtifactCreatedEventPayload

object

Customer-visible artifact creation recorded on the canonical factory event stream. Artifact bodies remain orchestrator-owned and are not included in this payload.

additionalPropertiesfalse (closed)

Fields

artifactRequiredFactoryArtifact
$ref →FactoryArtifact (reference link; not expanded recursively)
capturedAtOptionalstringformat: date-time
When the artifact payload was captured.

Event catalog

`DISPATCH_INTERRUPTEDDispatchInterruptedEventPayload`

#DISPATCH_INTERRUPTED

DispatchInterruptedEventPayload example

Corpus-constructed examplejson

Payload-only DispatchInterruptedEventPayload body. Mapped from FactoryEvent type DISPATCH_INTERRUPTED. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "reason": "example-reason",
  "observedStatus": "QUEUED",
  "interruptedAt": "1970-01-01T00:00:00.000Z",
  "retryPlanned": false
}

DispatchInterruptedEventPayload

object

Dispatch interruption recorded on the canonical factory event stream. Dispatch identity lives in FactoryEvent.context.

additionalPropertiesfalse (closed)

Fields

reasonRequiredstring
Customer-visible interruption reason.
observedStatusRequiredFactoryDispatchStatus
$ref →FactoryDispatchStatus (reference link; not expanded recursively)
interruptedAtRequiredstringformat: date-time
When the interruption was observed.
retryPlannedRequiredboolean
Whether a retry dispatch is planned.
providerSessionRefOptionalLoadableProviderSessionRef
Related provider-session reference when applicable.
$ref →LoadableProviderSessionRef (reference link; not expanded recursively)
checkpointRefOptionalFactorySessionJavaScriptCheckpointRef
Related checkpoint reference when applicable.
$ref →FactorySessionJavaScriptCheckpointRef (reference link; not expanded recursively)

Event catalog

`DISPATCH_QUEUEDDispatchQueuedEventPayload`

#DISPATCH_QUEUED

DispatchQueuedEventPayload example

Corpus-constructed examplejson

Payload-only DispatchQueuedEventPayload body. Mapped from FactoryEvent type DISPATCH_QUEUED. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "dispatchKind": "PETRI_TRANSITION"
}

DispatchQueuedEventPayload

object

Dispatch queued for execution on the canonical factory event stream. Dispatch identity lives in FactoryEvent.context and Petri transition fields are not required for JavaScript workflow dispatches.

additionalPropertiesfalse (closed)

Fields

dispatchKindRequiredFactoryDispatchKind
$ref →FactoryDispatchKind (reference link; not expanded recursively)
labelOptionalstring
Customer-visible dispatch label.
coordinationRefOptionalstring
Optional coordination reference for grouped child work.
runnerIdOptionalstring
Selected runner identifier when applicable.
presetIdOptionalstring
Resolved operator worker preset identifier when one was selected.
modelProviderOptionalstring
Resolved canonical model-provider identifier when applicable.
modelOptionalstring
Selected model identifier when applicable.
reasoningEffortOptionalstring
Resolved canonical reasoning effort when applicable.
providerOptionalstring
Selected provider identifier when applicable.
parentDispatchIdOptionalstring
Parent dispatch identifier when this dispatch was spawned from another dispatch.
retryOfDispatchIdOptionalstring
Prior dispatch identifier when this dispatch is a retry.
queuePositionOptionalinteger
Queue position when known.
- minimum0
promptDigestOptionalstring
Stable digest of rendered prompt material.
schemaDigestOptionalstring
Stable digest of the output schema when applicable.
inputArtifactIdsOptionalarray
Input artifact identifiers consumed by the dispatch.
inputWorkIdsOptionalarray
Input work identifiers consumed by the dispatch.

Event catalog

`DISPATCH_RECONCILEDDispatchReconciledEventPayload`

#DISPATCH_RECONCILED

DispatchReconciledEventPayload example

Corpus-constructed examplejson

Payload-only DispatchReconciledEventPayload body. Mapped from FactoryEvent type DISPATCH_RECONCILED. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "reconciledStatus": "QUEUED",
  "reconciliationSource": "STREAM_REPLAY",
  "replayed": false
}

DispatchReconciledEventPayload

object

Dispatch reconciliation recorded on the canonical factory event stream. Dispatch identity lives in FactoryEvent.context.

additionalPropertiesfalse (closed)

Fields

reconciledStatusRequiredFactoryDispatchStatus
$ref →FactoryDispatchStatus (reference link; not expanded recursively)
reconciliationSourceRequiredDispatchReconciliationSource
$ref →DispatchReconciliationSource (reference link; not expanded recursively)
replayedRequiredboolean
Whether reconciliation facts were emitted during stream replay.
usageOptionalFactoryDispatchUsage
Usage summary after reconciliation when available.
$ref →FactoryDispatchUsage (reference link; not expanded recursively)
resultArtifactRefOptionalFactoryArtifactRef
Result artifact reference without raw artifact bodies.
$ref →FactoryArtifactRef (reference link; not expanded recursively)
artifactIdsOptionalarray
Artifact identifiers produced or updated by reconciliation.
failureDetailOptionalFailureDetail
Canonical failure details when reconciliation failed.
$ref →FailureDetail (reference link; not expanded recursively)

Event catalog

`DISPATCH_REQUESTDispatchRequestEventPayload`

#DISPATCH_REQUEST

DispatchRequestEventPayload example

Corpus-constructed examplejson

Payload-only DispatchRequestEventPayload body. Mapped from FactoryEvent type DISPATCH_REQUEST. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "transitionId": "example-transitionId",
  "inputs": []
}

DispatchRequestEventPayload

object

Customer-visible dispatch start event. FactoryEvent.context owns dispatch, request, trace, and work identity. This payload keeps only non-derived dispatch facts first known when execution starts; workstation and worker topology must be reconstructed from the initial structure and the retained transition identifier. Ordered inputs carry consumed work references only; work type, trace, display, and other work facts must be rebuilt from prior work-request history.

additionalPropertiesfalse (closed)

Fields

transitionIdRequiredstring
currentChainingTraceIdOptionalstring
Deprecated compatibility copy of the dispatch chaining-trace identifier; prefer FactoryEvent.context.currentChainingTraceId.
previousChainingTraceIdsOptionalarray
Deprecated compatibility copy of predecessor chaining traces; prefer FactoryEvent.context.previousChainingTraceIds.
inputsRequiredDispatchConsumedWorkRef[]
resourcesOptionalResource[]
metadataOptionalDispatchRequestEventMetadata
$ref →DispatchRequestEventMetadata (reference link; not expanded recursively)

Event catalog

`DISPATCH_RESPONSEDispatchResponseEventPayload`

#DISPATCH_RESPONSE

DispatchResponseEventPayload example

Corpus-constructed examplejson

Payload-only DispatchResponseEventPayload body. Mapped from FactoryEvent type DISPATCH_RESPONSE. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "transitionId": "example-transitionId",
  "outcome": "ACCEPTED"
}

DispatchResponseEventPayload

object

Customer-visible dispatch completion event. Output work is represented with the same Work schema used by request submission rather than token or marking-mutation internals. FactoryEvent.context owns dispatch, trace, and work identity; workstation and worker topology must be derived from the matching dispatch-request event plus the initial structure. Provider-attempt session and safe diagnostic facts stay on inference response events instead of being copied onto dispatch completion payloads.

additionalPropertiesfalse (closed)

Fields

completionIdOptionalstring
transitionIdRequiredstring
currentChainingTraceIdOptionalstring
Deprecated compatibility copy of the dispatch chaining-trace identifier; prefer FactoryEvent.context.currentChainingTraceId.
previousChainingTraceIdsOptionalarray
Deprecated compatibility copy of predecessor chaining traces; prefer FactoryEvent.context.previousChainingTraceIds.
outcomeRequiredWorkOutcome
$ref →WorkOutcome (reference link; not expanded recursively)
outputOptionalstring
errorOptionalstring
feedbackOptionalstring
selectedClassificationLabelOptionalstring
failureDetailOptionalFailureDetail
$ref →FailureDetail (reference link; not expanded recursively)
providerFailureOptionalProviderFailureMetadata
$ref →ProviderFailureMetadata (reference link; not expanded recursively)
metricsOptionalWorkMetrics
$ref →WorkMetrics (reference link; not expanded recursively)
durationMillisOptionalintegerformat: int64
outputWorkOptionalWork[]
outputResourcesOptionalResource[]
metadataOptionalStringMap
$ref →StringMap (reference link; not expanded recursively)

Event catalog

`FACTORY_CHANGEFactoryChangeEventPayload`

#FACTORY_CHANGE

FactoryChangeEventPayload example

Corpus-constructed examplejson

Payload-only FactoryChangeEventPayload body. Mapped from FactoryEvent type FACTORY_CHANGE. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "factory": {
    "name": "example-factory"
  }
}

FactoryChangeEventPayload

object

Runtime topology snapshot after a live factory definition change replaces the running factory.

additionalPropertiesfalse (closed)

Fields

factoryRequiredFactory
$ref →Factory (reference link; not expanded recursively)
sourceDirectoryOptionalstring
metadataOptionalStringMap
$ref →StringMap (reference link; not expanded recursively)

Event catalog

`FACTORY_STATE_RESPONSEFactoryStateResponseEventPayload`

#FACTORY_STATE_RESPONSE

FactoryStateResponseEventPayload example

Corpus-constructed examplejson

Payload-only FactoryStateResponseEventPayload body. Mapped from FactoryEvent type FACTORY_STATE_RESPONSE. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "state": "IDLE"
}

FactoryStateResponseEventPayload

object

additionalPropertiesfalse (closed)

Fields

previousStateOptionalFactoryState
$ref →FactoryState (reference link; not expanded recursively)
stateRequiredFactoryState
$ref →FactoryState (reference link; not expanded recursively)
reasonOptionalstring

Event catalog

`INFERENCE_REQUESTInferenceRequestEventPayload`

#INFERENCE_REQUEST

InferenceRequestEventPayload example

Corpus-constructed examplejson

Payload-only InferenceRequestEventPayload body. Mapped from FactoryEvent type INFERENCE_REQUEST. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "inferenceRequestId": "example-inferenceRequestId",
  "attempt": 1,
  "workingDirectory": "example-workingDirectory",
  "worktree": "example-worktree",
  "prompt": "example-prompt"
}

InferenceRequestEventPayload

object

Request details captured immediately before a model-worker provider attempt is invoked. FactoryEvent.context owns dispatch, request, trace, and work identity, and the matching dispatch-request event owns the transition identifier. Prompt content is intentionally present and should be treated as sensitive in recordings and diagnostics.

additionalPropertiesfalse (closed)

Fields

inferenceRequestIdRequiredstring
Stable identifier correlating this provider request with its response.
attemptRequiredinteger
One-based provider attempt number for this dispatch.
- minimum1
workingDirectoryRequiredstring
Working directory resolved for the provider attempt.
worktreeRequiredstring
Worktree path resolved for the provider attempt.
promptRequiredstring
Rendered prompt sent to the provider.

Event catalog

`INFERENCE_RESPONSEInferenceResponseEventPayload`

#INFERENCE_RESPONSE

InferenceResponseEventPayload example

Corpus-constructed examplejson

Payload-only InferenceResponseEventPayload body. Mapped from FactoryEvent type INFERENCE_RESPONSE. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "inferenceRequestId": "example-inferenceRequestId",
  "attempt": 1,
  "outcome": "SUCCEEDED",
  "durationMillis": 0
}

InferenceResponseEventPayload

object

Response details captured after a model-worker provider attempt returns, including success and failure outcomes correlated to the request event. FactoryEvent.context owns dispatch identity, and the matching dispatch request owns the transition identifier for this provider attempt. Safe provider diagnostics and provider-session identifiers stay on this provider-boundary event instead of being copied onto DispatchResponse.

additionalPropertiesfalse (closed)

Fields

inferenceRequestIdRequiredstring
Identifier from the matching inference request event.
attemptRequiredinteger
One-based provider attempt number for this dispatch.
- minimum1
outcomeRequiredInferenceOutcome
$ref →InferenceOutcome (reference link; not expanded recursively)
responseOptionalstring
Provider response text when present.
durationMillisRequiredintegerformat: int64
Provider call duration in milliseconds.
- minimum0
providerSessionOptionalProviderSessionMetadata
$ref →ProviderSessionMetadata (reference link; not expanded recursively)
diagnosticsOptionalSafeWorkDiagnostics
$ref →SafeWorkDiagnostics (reference link; not expanded recursively)
exitCodeOptionalinteger
Process exit code when the provider failure exposes one.
failureDetailOptionalFailureDetail
$ref →FailureDetail (reference link; not expanded recursively)

Event catalog

`INITIAL_STRUCTURE_REQUESTInitialStructureRequestEventPayload`

#INITIAL_STRUCTURE_REQUEST

InitialStructureRequestEventPayload example

Corpus-constructed examplejson

Payload-only InitialStructureRequestEventPayload body. Mapped from FactoryEvent type INITIAL_STRUCTURE_REQUEST. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "factory": {
    "name": "example-factory"
  }
}

InitialStructureRequestEventPayload

object

Runtime topology snapshot before work moves.

additionalPropertiesfalse (closed)

Fields

factoryRequiredFactory
$ref →Factory (reference link; not expanded recursively)
sourceDirectoryOptionalstring
metadataOptionalStringMap
$ref →StringMap (reference link; not expanded recursively)

Event catalog

`JAVASCRIPT_CHECKPOINT_REFJavaScriptCheckpointRefEventPayload`

#JAVASCRIPT_CHECKPOINT_REF

JavaScriptCheckpointRefEventPayload example

Corpus-constructed examplejson

Payload-only JavaScriptCheckpointRefEventPayload body. Mapped from FactoryEvent type JAVASCRIPT_CHECKPOINT_REF. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "checkpointId": "example-checkpointId",
  "artifactRef": {
    "id": "example-id",
    "kind": "FINAL_RESULT",
    "visibility": "PUBLIC"
  }
}

JavaScriptCheckpointRefEventPayload

object

Customer-visible JavaScript checkpoint reference recorded on the canonical factory event stream. Raw VM checkpoint bodies remain orchestrator-owned and are not included in this payload.

additionalPropertiesfalse (closed)

Fields

checkpointIdRequiredstring
Stable checkpoint identifier referenced by the session runtime.
labelOptionalstring
Customer-visible checkpoint label.
timestampOptionalstringformat: date-time
When the checkpoint was recorded.
summaryOptionalstring
Short customer-visible checkpoint summary without raw VM state.
artifactRefRequiredFactoryArtifactRef
$ref →FactoryArtifactRef (reference link; not expanded recursively)

Event catalog

`JAVASCRIPT_PHASE_CHANGEJavaScriptPhaseChangeEventPayload`

#JAVASCRIPT_PHASE_CHANGE

JavaScriptPhaseChangeEventPayload example

Corpus-constructed examplejson

Payload-only JavaScriptPhaseChangeEventPayload body. Mapped from FactoryEvent type JAVASCRIPT_PHASE_CHANGE. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "phase": "example-phase",
  "phases": [],
  "scriptStatus": "IDLE",
  "childDispatchCounts": {
    "queued": 0,
    "running": 0,
    "completed": 0
  }
}

JavaScriptPhaseChangeEventPayload

object

JavaScript workflow phase transition recorded on the canonical factory event stream. JavaScript workflow progress is represented through phase changes, not Petri WORK_STATE_CHANGE marking events.

additionalPropertiesfalse (closed)

Fields

phaseRequiredstring
Current JavaScript workflow phase name after this event.
phasesRequiredarray
Ordered phase names visible in the session runtime.
argsDigestOptionalstring
Stable digest of the effective workflow arguments.
scriptStatusRequiredFactorySessionJavaScriptScriptStatus
$ref →FactorySessionJavaScriptScriptStatus (reference link; not expanded recursively)
childDispatchCountsRequiredFactorySessionJavaScriptChildDispatchCounts
$ref →FactorySessionJavaScriptChildDispatchCounts (reference link; not expanded recursively)

Event catalog

`MODEL_REQUESTModelRequestEventPayload`

#MODEL_REQUEST

ModelRequestEventPayload example

Corpus-constructed examplejson

Payload-only ModelRequestEventPayload body. Mapped from FactoryEvent type MODEL_REQUEST. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "modelRequestId": "example-modelRequestId",
  "attempt": 1,
  "operation": "example-operation",
  "worker": "example-worker",
  "model": "example-model",
  "providerLocality": "example-providerLocality"
}

ModelRequestEventPayload

object

Request details captured immediately before a model-backed worker invocation enters resource, load, and execution boundaries. FactoryEvent.context owns dispatch, request, trace, and work identity, and the matching dispatch-request event owns the transition identifier.

additionalPropertiesfalse (closed)

Fields

modelRequestIdRequiredstring
Stable identifier correlating this model execution request with its response.
attemptRequiredinteger
One-based model execution attempt number for this dispatch.
- minimum1
operationRequiredstring
Uppercase model operation requested by the workstation, such as TTS.
workerRequiredstring
Runtime worker name selected for the invocation.
modelRequiredstring
Concrete model identity resolved for this invocation.
providerLocalityRequiredstring
Worker-declared model locality, such as LOCAL or CLOUD.
resourcesOptionalModelResourceSummary[]
Concrete resources attached to the model worker execution path.
bindingsOptionalResolvedModelOperationBinding[]
Deterministically resolved operation-slot bindings used for invocation.
workingDirectoryOptionalstring
Working directory resolved for the model execution when present.
worktreeOptionalstring
Worktree path resolved for the model execution when present.

Event catalog

`MODEL_RESPONSEModelResponseEventPayload`

#MODEL_RESPONSE

ModelResponseEventPayload example

Corpus-constructed examplejson

Payload-only ModelResponseEventPayload body. Mapped from FactoryEvent type MODEL_RESPONSE. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "modelRequestId": "example-modelRequestId",
  "attempt": 1,
  "operation": "example-operation",
  "worker": "example-worker",
  "model": "example-model",
  "providerLocality": "example-providerLocality",
  "outcome": "SUCCEEDED",
  "durationMillis": 0
}

ModelResponseEventPayload

object

Response details captured after a model-backed worker invocation returns, including resource wait, local load, binding-resolution, output, and failure evidence correlated to the matching model request event. Large binary audio must remain represented through content references or bounded previews instead of unbounded inline payloads.

additionalPropertiesfalse (closed)

Fields

modelRequestIdRequiredstring
Identifier from the matching model request event.
attemptRequiredinteger
One-based model execution attempt number for this dispatch.
- minimum1
operationRequiredstring
Uppercase model operation requested by the workstation, such as TTS.
workerRequiredstring
Runtime worker name selected for the invocation.
modelRequiredstring
Concrete model identity resolved for this invocation.
providerLocalityRequiredstring
Worker-declared model locality, such as LOCAL or CLOUD.
outcomeRequiredInferenceOutcome
$ref →InferenceOutcome (reference link; not expanded recursively)
durationMillisRequiredintegerformat: int64
End-to-end model invocation duration in milliseconds.
- minimum0
resourcesOptionalModelResourceSummary[]
Concrete resources attached to the model worker execution path.
bindingsOptionalResolvedModelOperationBinding[]
Deterministically resolved operation-slot bindings used for invocation.
resourceWaitMillisOptionalintegerformat: int64
Time spent waiting for local model resources before acquisition.
- minimum0
resourceAcquiredOptionalboolean
Whether the invocation acquired the required local model resources.
loadRequestedOptionalboolean
Whether this invocation asked the managed local-model runtime to load a handle.
loadReusedOptionalboolean
Whether an already-loaded local model handle was reused instead of loading again.
loadDurationMillisOptionalintegerformat: int64
Duration of the managed local-model load call when one occurred.
- minimum0
outputPreviewOptionalstring
Bounded output preview for non-binary model responses when present.
outputContentOptionalWorkContent
$ref →WorkContent (reference link; not expanded recursively)
diagnosticsOptionalSafeWorkDiagnostics
$ref →SafeWorkDiagnostics (reference link; not expanded recursively)
failureDetailOptionalFailureDetail
$ref →FailureDetail (reference link; not expanded recursively)

Event catalog

`ORCHESTRATOR_CHECKPOINT_WRITTENOrchestratorCheckpointWrittenEventPayload`

#ORCHESTRATOR_CHECKPOINT_WRITTEN

OrchestratorCheckpointWrittenEventPayload example

Corpus-constructed examplejson

Payload-only OrchestratorCheckpointWrittenEventPayload body. Mapped from FactoryEvent type ORCHESTRATOR_CHECKPOINT_WRITTEN. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "label": "example-label",
  "resumabilityStatus": "RESUMABLE"
}

OrchestratorCheckpointWrittenEventPayload

object

Orchestrator checkpoint reference recorded on the canonical factory event stream. Checkpoint identity lives in FactoryEvent.context and raw VM bodies remain orchestrator-owned.

additionalPropertiesfalse (closed)

Fields

labelRequiredstring
Customer-visible checkpoint label.
timestampOptionalstringformat: date-time
When the checkpoint was recorded.
sourceHashOptionalstring
Stable hash of the authored workflow source at checkpoint time.
runtimeSnapshotDigestOptionalstring
Stable digest of replay-safe runtime snapshot metadata.
artifactRefOptionalFactoryArtifactRef
Checkpoint artifact reference without raw VM checkpoint bodies.
$ref →FactoryArtifactRef (reference link; not expanded recursively)
resumabilityStatusRequiredCheckpointResumabilityStatus
$ref →CheckpointResumabilityStatus (reference link; not expanded recursively)
warningsOptionalFactoryDispatchWarning[]
Customer-visible checkpoint warnings.

Event catalog

`ORCHESTRATOR_PHASE_CHANGEDOrchestratorPhaseChangedEventPayload`

#ORCHESTRATOR_PHASE_CHANGED

OrchestratorPhaseChangedEventPayload example

Corpus-constructed examplejson

Payload-only OrchestratorPhaseChangedEventPayload body. Mapped from FactoryEvent type ORCHESTRATOR_PHASE_CHANGED. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "phaseStatus": "ACTIVE"
}

OrchestratorPhaseChangedEventPayload

object

Orchestrator workflow phase transition recorded on the canonical factory event stream. Current phase identity lives in FactoryEvent.context.

additionalPropertiesfalse (closed)

Fields

previousPhaseIdOptionalstring
Previous workflow phase identifier when available.
previousPhaseNameOptionalstring
Previous workflow phase name when available.
phaseStatusRequiredOrchestratorPhaseStatus
$ref →OrchestratorPhaseStatus (reference link; not expanded recursively)
startedAtOptionalstringformat: date-time
When the current phase started, when applicable.
completedAtOptionalstringformat: date-time
When the previous phase completed, when applicable.
progressSummaryOptionalstring
Bounded customer-visible phase progress summary.

Event catalog

`RELATIONSHIP_CHANGE_REQUESTRelationshipChangeRequestEventPayload`

#RELATIONSHIP_CHANGE_REQUEST

RelationshipChangeRequestEventPayload example

Corpus-constructed examplejson

Payload-only RelationshipChangeRequestEventPayload body. Mapped from FactoryEvent type RELATIONSHIP_CHANGE_REQUEST. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "relation": {
    "type": "DEPENDS_ON",
    "sourceWorkName": "example-sourceWorkName",
    "targetWorkName": "example-targetWorkName"
  }
}

RelationshipChangeRequestEventPayload

object

additionalPropertiesfalse (closed)

Fields

relationRequiredRelation
$ref →Relation (reference link; not expanded recursively)

Event catalog

`RUN_REQUESTRunRequestEventPayload`

#RUN_REQUEST

RunRequestEventPayload example

Corpus-constructed examplejson

Payload-only RunRequestEventPayload body. Mapped from FactoryEvent type RUN_REQUEST. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "recordedAt": "1970-01-01T00:00:00.000Z",
  "factory": {
    "name": "example-factory"
  }
}

RunRequestEventPayload

object

additionalPropertiesfalse (closed)

Fields

recordedAtRequiredstringformat: date-time
factoryRequiredFactory
$ref →Factory (reference link; not expanded recursively)
wallClockOptionalWallClock
$ref →WallClock (reference link; not expanded recursively)
diagnosticsOptionalDiagnostics
$ref →Diagnostics (reference link; not expanded recursively)

Event catalog

`RUN_RESPONSERunResponseEventPayload`

#RUN_RESPONSE

RunResponseEventPayload example

Corpus-constructed examplejson

Payload-only RunResponseEventPayload body. Mapped from FactoryEvent type RUN_RESPONSE. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{}

RunResponseEventPayload

object

additionalPropertiesfalse (closed)

Fields

stateOptionalFactoryState
$ref →FactoryState (reference link; not expanded recursively)
reasonOptionalstring
wallClockOptionalWallClock
$ref →WallClock (reference link; not expanded recursively)
diagnosticsOptionalDiagnostics
$ref →Diagnostics (reference link; not expanded recursively)

Event catalog

`SCRIPT_REQUESTScriptRequestEventPayload`

#SCRIPT_REQUEST

ScriptRequestEventPayload example

Corpus-constructed examplejson

Payload-only ScriptRequestEventPayload body. Mapped from FactoryEvent type SCRIPT_REQUEST. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "scriptRequestId": "example-scriptRequestId",
  "dispatchId": "example-dispatchId",
  "transitionId": "example-transitionId",
  "attempt": 1,
  "command": "example-command",
  "args": []
}

ScriptRequestEventPayload

object

Request details captured immediately before a script-backed worker invokes a concrete command. Raw environment values and raw stdin content are intentionally excluded from the public script event contract.

additionalPropertiesfalse (closed)

Fields

scriptRequestIdRequiredstring
Stable identifier correlating this script request with its response.
dispatchIdRequiredstring
transitionIdRequiredstring
attemptRequiredinteger
One-based script attempt number for this dispatch.
- minimum1
commandRequiredstring
Concrete command name executed for this script attempt.
argsRequiredarray
Fully resolved command arguments passed to the script command runner.

Event catalog

`SCRIPT_RESPONSEScriptResponseEventPayload`

#SCRIPT_RESPONSE

ScriptResponseEventPayload example

Corpus-constructed examplejson

Payload-only ScriptResponseEventPayload body. Mapped from FactoryEvent type SCRIPT_RESPONSE. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "scriptRequestId": "example-scriptRequestId",
  "dispatchId": "example-dispatchId",
  "transitionId": "example-transitionId",
  "attempt": 1,
  "outcome": "SUCCEEDED",
  "stdout": "example-stdout",
  "stderr": "example-stderr",
  "durationMillis": 0
}

ScriptResponseEventPayload

object

Response details captured after a script-backed worker command returns or fails before a normal exit code. Raw environment values and raw stdin content are intentionally excluded from the public script event contract.

additionalPropertiesfalse (closed)

Fields

scriptRequestIdRequiredstring
Identifier from the matching script request event.
dispatchIdRequiredstring
transitionIdRequiredstring
attemptRequiredinteger
One-based script attempt number for this dispatch.
- minimum1
outcomeRequiredScriptExecutionOutcome
$ref →ScriptExecutionOutcome (reference link; not expanded recursively)
stdoutRequiredstring
Captured stdout text from the script execution boundary.
stderrRequiredstring
Captured stderr text from the script execution boundary.
durationMillisRequiredintegerformat: int64
Script execution duration in milliseconds.
- minimum0
exitCodeOptionalinteger
Process exit code when the command returned one.
failureTypeOptionalScriptFailureType
$ref →ScriptFailureType (reference link; not expanded recursively)

Event catalog

`SESSION_COMPLETEDSessionCompletedEventPayload`

#SESSION_COMPLETED

SessionCompletedEventPayload example

Corpus-constructed examplejson

Payload-only SessionCompletedEventPayload body. Mapped from FactoryEvent type SESSION_COMPLETED. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "finalStatus": "QUEUED",
  "completedAt": "1970-01-01T00:00:00.000Z"
}

SessionCompletedEventPayload

object

Authoritative terminal session lifecycle marker on the canonical factory event stream. Session identity lives in FactoryEvent.context.

additionalPropertiesfalse (closed)

Fields

finalStatusRequiredFactorySessionDurableLifecycleStatus
$ref →FactorySessionDurableLifecycleStatus (reference link; not expanded recursively)
completedAtRequiredstringformat: date-time
When durable session execution reached a terminal state.
durationMillisOptionalintegerformat: int64
Total session execution duration in milliseconds.
resultStatusOptionalFactoryEventSessionResultStatus
$ref →FactoryEventSessionResultStatus (reference link; not expanded recursively)
artifactIdsOptionalarray
Artifact identifiers associated with the terminal session outcome.
dispatchCountsOptionalFactorySessionJavaScriptChildDispatchCounts
Dispatch queue, running, and completed counts at terminal completion.
$ref →FactorySessionJavaScriptChildDispatchCounts (reference link; not expanded recursively)
failureDetailOptionalFailureDetail
Canonical failure details when the session completed unsuccessfully.
$ref →FailureDetail (reference link; not expanded recursively)

Event catalog

`SESSION_LIFECYCLE_CONTROLSessionLifecycleControlEventPayload`

#SESSION_LIFECYCLE_CONTROL

SessionLifecycleControlEventPayload example

Corpus-constructed examplejson

Payload-only SessionLifecycleControlEventPayload body. Mapped from FactoryEvent type SESSION_LIFECYCLE_CONTROL. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "operation": "APPROVE",
  "outcome": "ACCEPTED",
  "previousStatus": "QUEUED",
  "newStatus": "QUEUED",
  "occurredAt": "1970-01-01T00:00:00.000Z"
}

SessionLifecycleControlEventPayload

object

Durable Factory Session lifecycle control recorded on the canonical factory event stream. Session identity lives in FactoryEvent.context; this payload carries replay-safe control facts only.

additionalPropertiesfalse (closed)

Fields

operationRequiredFactorySessionLifecycleControlKind
$ref →FactorySessionLifecycleControlKind (reference link; not expanded recursively)
outcomeRequiredFactorySessionLifecycleControlOutcome
$ref →FactorySessionLifecycleControlOutcome (reference link; not expanded recursively)
previousStatusRequiredFactorySessionDurableLifecycleStatus
$ref →FactorySessionDurableLifecycleStatus (reference link; not expanded recursively)
newStatusRequiredFactorySessionDurableLifecycleStatus
$ref →FactorySessionDurableLifecycleStatus (reference link; not expanded recursively)
occurredAtRequiredstringformat: date-time
When the lifecycle control took effect.
reasonOptionalstring
Optional operator-provided reason for the control request.

Event catalog

`SESSION_PAUSEDSessionPausedEventPayload`

#SESSION_PAUSED

SessionPausedEventPayload example

Corpus-constructed examplejson

Payload-only SessionPausedEventPayload body. Mapped from FactoryEvent type SESSION_PAUSED. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "status": "QUEUED",
  "pausedAt": "1970-01-01T00:00:00.000Z"
}

SessionPausedEventPayload

object

Factory Session lifecycle pause recorded on the canonical factory event stream. Session identity lives in FactoryEvent.context; this payload carries replay-safe control-transition facts only.

additionalPropertiesfalse (closed)

Fields

statusRequiredFactorySessionDurableLifecycleStatus
Lifecycle status after a successful pause control.
$ref →FactorySessionDurableLifecycleStatus (reference link; not expanded recursively)
pausedAtRequiredstringformat: date-time
When the Factory Session entered PAUSED.

Event catalog

`SESSION_RESULT_UPDATEDSessionResultUpdatedEventPayload`

#SESSION_RESULT_UPDATED

SessionResultUpdatedEventPayload example

Corpus-constructed examplejson

Payload-only SessionResultUpdatedEventPayload body. Mapped from FactoryEvent type SESSION_RESULT_UPDATED. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "resultStatus": "NOT_READY"
}

SessionResultUpdatedEventPayload

object

Partial or final session result availability on the canonical factory event stream. Identity and ordering live in FactoryEvent.context.

additionalPropertiesfalse (closed)

Fields

resultStatusRequiredFactoryEventSessionResultStatus
$ref →FactoryEventSessionResultStatus (reference link; not expanded recursively)
artifactIdsOptionalarray
Artifact identifiers associated with this result update.
resultSummaryOptionalWorkContent
Bounded customer-visible result summary without raw prompts or secrets.
$ref →WorkContent (reference link; not expanded recursively)

Event catalog

`SESSION_RESUMEDSessionResumedEventPayload`

#SESSION_RESUMED

SessionResumedEventPayload example

Corpus-constructed examplejson

Payload-only SessionResumedEventPayload body. Mapped from FactoryEvent type SESSION_RESUMED. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "status": "QUEUED",
  "resumedAt": "1970-01-01T00:00:00.000Z"
}

SessionResumedEventPayload

object

Factory Session lifecycle resume recorded on the canonical factory event stream. Session identity lives in FactoryEvent.context; this payload carries replay-safe control-transition facts only.

additionalPropertiesfalse (closed)

Fields

statusRequiredFactorySessionDurableLifecycleStatus
Lifecycle status after a successful resume control.
$ref →FactorySessionDurableLifecycleStatus (reference link; not expanded recursively)
resumedAtRequiredstringformat: date-time
When the Factory Session returned to RUNNING.

Event catalog

`SESSION_STARTEDSessionStartedEventPayload`

#SESSION_STARTED

SessionStartedEventPayload example

Corpus-constructed examplejson

Payload-only SessionStartedEventPayload body. Mapped from FactoryEvent type SESSION_STARTED. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "startedAt": "1970-01-01T00:00:00.000Z"
}

SessionStartedEventPayload

object

Session execution start recorded on the canonical factory event stream. Session and orchestrator identity live in FactoryEvent.context; this payload carries replay-safe factory and source facts only.

additionalPropertiesfalse (closed)

Fields

factoryIdOptionalstring
Stable factory identifier for the session runtime.
sourceRefOptionalstring
Authored workflow or factory source reference when applicable.
sourceHashOptionalstring
Stable hash of the authored source material.
policyHashOptionalstring
Stable hash of the effective orchestrator policy.
argsDigestOptionalstring
Stable digest of effective session arguments.
startedAtRequiredstringformat: date-time
When durable session execution started.

Event catalog

`WORK_REQUESTWorkRequestEventPayload`

#WORK_REQUEST

WorkRequestEventPayload example

Corpus-constructed examplejson

Payload-only WorkRequestEventPayload body. Mapped from FactoryEvent type WORK_REQUEST. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "type": "FACTORY_REQUEST_BATCH"
}

WorkRequestEventPayload

object

Normalized work request entering the factory. Single-work submissions accepted by POST /work are converted into this one-work request shape before an event is emitted.

additionalPropertiesfalse (closed)

Fields

typeRequiredWorkRequestType
$ref →WorkRequestType (reference link; not expanded recursively)
worksOptionalWork[]
relationsOptionalRelation[]
sourceOptionalstring
parentLineageOptionalarray

Event catalog

`WORK_STATE_CHANGEWorkStateChangeEventPayload`

#WORK_STATE_CHANGE

WorkStateChangeEventPayload example

Corpus-constructed examplejson

Payload-only WorkStateChangeEventPayload body. Mapped from FactoryEvent type WORK_STATE_CHANGE. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "workId": "example-workId",
  "workTypeName": "example-workTypeName",
  "fromState": "example-fromState",
  "toState": "example-toState",
  "fromPlaceId": "example-fromPlaceId",
  "toPlaceId": "example-toPlaceId",
  "source": "api"
}

WorkStateChangeEventPayload

object

Canonical Petri marking position change for work items in Petri-backed factories. JavaScript workflow progress is represented by JAVASCRIPT_PHASE_CHANGE events instead of WORK_STATE_CHANGE. Operator moves use source api or cli; automatic cascade propagation uses cascading-failure. FactoryEvent.context carries workIds and optional requestId for operator idempotency.

additionalPropertiesfalse (closed)

Fields

workIdRequiredstring
workTypeNameRequiredstring
fromStateRequiredstring
Authored state name before the move.
toStateRequiredstring
Authored state name after the move.
fromPlaceIdRequiredstring
Marking place identifier before the move.
toPlaceIdRequiredstring
Marking place identifier after the move.
sourceRequiredWorkStateChangeSource
$ref →WorkStateChangeSource (reference link; not expanded recursively)
triggerWorkIdOptionalstring
Optional work identifier that triggered a cascade move.
reasonOptionalstring
Optional human-readable reason for the move.

Ephemeral observation — not canonical FactoryEvent replay state

FactoryResponseEvent envelope

Shared envelope fields for every ephemeral response-event frame, including schemaVersion, eventId/sequence, kind, phase, provenance, payload, and optional correlation identifiers. Payload-only shapes below are not complete envelopes.

FactoryResponseEvent

object

Provider-neutral envelope for transient agent activity observed during one Factory Session run. Unlike canonical factory events, these records are ephemeral observation records and must not derive canonical work state after replay.

additionalPropertiesfalse (closed)

Fields

schemaVersionRequiredstring
Version of the FactoryResponseEvent envelope schema.
- enum"agent-factory.response-event.v1"
eventIdRequiredstring
Stable identifier for this response event within the session stream.
sequenceRequiredintegerformat: int64
Monotonic session-scoped cursor for published events. Sequence zero is reserved for synthetic out-of-band read markers such as retention gaps; those markers do not consume or reuse a published sequence.
- minimum0
recordedAtRequiredstringformat: date-time
Wall-clock timestamp when the response event was recorded.
factorySessionIdRequiredstring
Factory Session identity that owns this response-event stream.
runIdRequiredstring
Run identity within the Factory Session that produced this event.
kindRequiredFactoryResponseEventKind
$ref →FactoryResponseEventKind (reference link; not expanded recursively)
phaseRequiredFactoryResponseEventPhase
$ref →FactoryResponseEventPhase (reference link; not expanded recursively)
provenanceRequiredFactoryResponseEventProvenance
$ref →FactoryResponseEventProvenance (reference link; not expanded recursively)
payloadRequiredFactoryResponseEventPayload
$ref →FactoryResponseEventPayload (reference link; not expanded recursively)
dispatchIdOptionalstring
Optional dispatch correlation identifier.
turnIdOptionalstring
Optional turn correlation identifier.
itemIdOptionalstring
Optional stable item correlation identifier.
parentItemIdOptionalstring
Optional parent item correlation identifier.
providerSessionRefOptionalstring
Optional provider session reference for diagnostics.

FactoryResponseEvent envelope example

Corpus-constructed examplejson

Complete FactoryResponseEvent envelope with kind SESSION and a FactoryResponseEventSessionPayload payload body. Field names and enums come from packaged OpenAPI; nested values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "schemaVersion": "agent-factory.response-event.v1",
  "eventId": "example-eventId",
  "sequence": 1,
  "recordedAt": "1970-01-01T00:00:00.000Z",
  "factorySessionId": "example-factorySessionId",
  "runId": "example-runId",
  "kind": "SESSION",
  "phase": "STARTED",
  "provenance": {
    "provider": "example-provider",
    "nativeEventType": "example-nativeEventType",
    "delivery": "NATIVE_STREAM",
    "representation": "DELTA",
    "fidelity": "LOSSLESS"
  },
  "payload": {}
}

Response event dimensions

Kind, phase, provenance, and payload are independent dimensions. Consumers select a payload variant using envelope kind and phase together with structural decoding. Not every kind × phase × payload combination is valid — allowed combinations are validated before publication.

This matrix does not claim a full Cartesian product of dimensions.

Kind `(FactoryResponseEventKind)`

ERROR
FILE_CHANGE
MESSAGE
PLAN
PROGRESS
REASONING
RUN
SESSION
STREAM_GAP
TOOL
TURN
USAGE

FactoryResponseEventKind

string

Semantic category of one FactoryResponseEvent. Response events are ephemeral observation records and must not derive canonical factory replay state.

enum"SESSION" | "RUN" | "TURN" | "MESSAGE" | "REASONING" | "TOOL" | "FILE_CHANGE" | "PLAN" | "PROGRESS" | "USAGE" | "ERROR" | "STREAM_GAP"

Phase `(FactoryResponseEventPhase)`

CANCELED
COMPLETED
DELTA
FAILED
STARTED
UPDATED

FactoryResponseEventPhase

string

Lifecycle position of one FactoryResponseEvent within its kind. Allowed phase/kind combinations are validated before publication.

enum"STARTED" | "DELTA" | "UPDATED" | "COMPLETED" | "FAILED" | "CANCELED"

Provenance `(FactoryResponseEventProvenance)`

Provider-neutral fidelity metadata. Diagnostic identity only — does not promote provider-native schemas into the public vocabulary.

FactoryResponseEventProvenance

object

Provider-neutral fidelity metadata for one response event. Exposes diagnostic identity without promoting provider-native schemas into the public vocabulary.

additionalPropertiesfalse (closed)

Fields

providerRequiredstring
Provider identifier for the originating adapter session.
nativeEventTypeRequiredstring
Provider-native event type label retained for diagnostics only.
nativeEventSubtypeOptionalstring
Optional provider-native event subtype label retained for diagnostics only.
deliveryRequiredFactoryResponseEventProvenanceDelivery
$ref →FactoryResponseEventProvenanceDelivery (reference link; not expanded recursively)
representationRequiredFactoryResponseEventProvenanceRepresentation
$ref →FactoryResponseEventProvenanceRepresentation (reference link; not expanded recursively)
fidelityRequiredFactoryResponseEventProvenanceFidelity
$ref →FactoryResponseEventProvenanceFidelity (reference link; not expanded recursively)

Payload `(FactoryResponseEventPayload)`

Typed oneOf union with 14 addressable shapes. Full schema-backed fields are listed in the payload catalog below.

FactoryResponseEventPayload

Public typed payload union for FactoryResponseEvent. Variants align with envelope kind and phase semantics from the Story 01 vocabulary. MESSAGE and TOOL kinds use distinct snapshot and delta payload shapes; consumers select the variant using envelope kind and phase together with structural decoding.

oneOf

FactoryResponseEvent payload catalog

Schema-backed fields for each payload oneOf shape. These are payload-only schemas on an ephemeral stream — the shared FactoryResponseEvent envelope fields remain above, and none of these are canonical FactoryEvent replay state.

Event catalog

`FactoryResponseEventErrorPayload`

#FactoryResponseEventErrorPayload

FactoryResponseEventErrorPayload example

Corpus-constructed examplejson

Payload-only FactoryResponseEventErrorPayload body. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "code": "example-code",
  "message": "example-message"
}

FactoryResponseEventErrorPayload

object

Provider-neutral error payload with optional retry metadata.

additionalPropertiesfalse (closed)

Fields

codeRequiredstring
Stable provider-neutral error code.
messageRequiredstring
Human-readable error message.
retryableOptionalboolean
Whether the error may be retried.
retryAfterSecondsOptionalintegerformat: int64
Suggested retry delay in seconds when retryable.
- minimum0
retryAttemptOptionalintegerformat: int32
Retry attempt count when applicable.
- minimum0

Event catalog

`FactoryResponseEventFileChangePayload`

#FactoryResponseEventFileChangePayload

FactoryResponseEventFileChangePayload example

Corpus-constructed examplejson

Payload-only FactoryResponseEventFileChangePayload body. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "path": "example-path",
  "operation": "example-operation"
}

FactoryResponseEventFileChangePayload

object

Observed file mutation payload.

additionalPropertiesfalse (closed)

Fields

pathRequiredstring
Observed file path relative to the workspace or artifact root.
operationRequiredstring
Observed file operation such as create, update, or delete.
summaryOptionalstring
Optional human-readable summary of the mutation.

Event catalog

`FactoryResponseEventMessageDeltaPayload`

#FactoryResponseEventMessageDeltaPayload

FactoryResponseEventMessageDeltaPayload example

Corpus-constructed examplejson

Payload-only FactoryResponseEventMessageDeltaPayload body. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "contentBlockIndex": 0,
  "contentBlockKind": "TEXT"
}

FactoryResponseEventMessageDeltaPayload

object

Incremental message content delta for one content block.

additionalPropertiesfalse (closed)

Fields

contentBlockIndexRequiredintegerformat: int32
Zero-based index of the content block receiving the delta.
- minimum0
contentBlockKindRequiredFactoryResponseEventContentBlockKind
$ref →FactoryResponseEventContentBlockKind (reference link; not expanded recursively)
textDeltaOptionalstring
Incremental text appended to the targeted content block.

Event catalog

`FactoryResponseEventMessagePayload`

#FactoryResponseEventMessagePayload

FactoryResponseEventMessagePayload example

Corpus-constructed examplejson

Payload-only FactoryResponseEventMessagePayload body. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "role": "example-role",
  "contentBlocks": []
}

FactoryResponseEventMessagePayload

object

Message snapshot payload with typed content blocks.

additionalPropertiesfalse (closed)

Fields

roleRequiredstring
Message role such as assistant or user.
contentBlocksRequiredFactoryResponseEventContentBlock[]
Ordered typed content blocks for the message snapshot.
- minItems1
partialOptionalboolean
When true, the snapshot carries bounded timeout or cancellation capture and must not be treated as an authoritative final response.

Event catalog

`FactoryResponseEventPlanPayload`

#FactoryResponseEventPlanPayload

FactoryResponseEventPlanPayload example

Corpus-constructed examplejson

Payload-only FactoryResponseEventPlanPayload body. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{}

FactoryResponseEventPlanPayload

object

Published plan update payload.

additionalPropertiesfalse (closed)

Fields

stepsOptionalFactoryResponseEventPlanStep[]
Ordered plan steps when emitting a plan snapshot.
summaryOptionalstring
Optional plan summary text.

Event catalog

`FactoryResponseEventProgressPayload`

#FactoryResponseEventProgressPayload

FactoryResponseEventProgressPayload example

Corpus-constructed examplejson

Payload-only FactoryResponseEventProgressPayload body. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "label": "example-label"
}

FactoryResponseEventProgressPayload

object

Coarse progress notification payload.

additionalPropertiesfalse (closed)

Fields

labelRequiredstring
Short progress label for UI or CLI consumers.
messageOptionalstring
Optional longer progress message.
percentCompleteOptionalnumberformat: double
Optional completion percentage when known.
- minimum0
- maximum100

Event catalog

`FactoryResponseEventReasoningPayload`

#FactoryResponseEventReasoningPayload

FactoryResponseEventReasoningPayload example

Corpus-constructed examplejson

Payload-only FactoryResponseEventReasoningPayload body. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{}

FactoryResponseEventReasoningPayload

object

Reasoning summary snapshot or delta payload.

additionalPropertiesfalse (closed)

Fields

summaryOptionalstring
Full reasoning summary text when emitting a snapshot.
summaryDeltaOptionalstring
Incremental reasoning summary text when emitting a delta.

Event catalog

`FactoryResponseEventRunPayload`

#FactoryResponseEventRunPayload

FactoryResponseEventRunPayload example

Corpus-constructed examplejson

Payload-only FactoryResponseEventRunPayload body. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{}

FactoryResponseEventRunPayload

object

Run-scoped lifecycle metadata payload.

additionalPropertiesfalse (closed)

Fields

statusOptionalstring
Run lifecycle status when applicable.

Event catalog

`FactoryResponseEventSessionPayload`

#FactoryResponseEventSessionPayload

FactoryResponseEventSessionPayload example

Corpus-constructed examplejson

Payload-only FactoryResponseEventSessionPayload body. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{}

FactoryResponseEventSessionPayload

object

Session-scoped lifecycle and capability metadata payload.

additionalPropertiesfalse (closed)

Fields

statusOptionalstring
Session lifecycle status when applicable.
capabilitiesOptionalFactoryResponseEventCapabilities
$ref →FactoryResponseEventCapabilities (reference link; not expanded recursively)

Event catalog

`FactoryResponseEventStreamGapPayload`

#FactoryResponseEventStreamGapPayload

FactoryResponseEventStreamGapPayload example

Corpus-constructed examplejson

Payload-only FactoryResponseEventStreamGapPayload body. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "fromSequence": 0,
  "toSequence": 0,
  "firstAvailableSequence": 1
}

FactoryResponseEventStreamGapPayload

Discontinuity marker for either unavailable retained response-event sequences or an affected provider item whose lifecycle could not be fully observed. Retention gaps include fromSequence, toSequence, and firstAvailableSequence; item-scoped gaps include affectedItemId and reason. The alternatives are exclusive so empty, partial, and mixed payloads are rejected.

Event catalog

`FactoryResponseEventToolDeltaPayload`

#FactoryResponseEventToolDeltaPayload

FactoryResponseEventToolDeltaPayload example

Corpus-constructed examplejson

Payload-only FactoryResponseEventToolDeltaPayload body. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "toolCallId": "example-toolCallId",
  "outputDelta": "example-outputDelta"
}

FactoryResponseEventToolDeltaPayload

object

Incremental tool output delta payload.

additionalPropertiesfalse (closed)

Fields

toolCallIdRequiredstring
Stable tool call identifier receiving output.
outputDeltaRequiredstring
Incremental tool output text.

Event catalog

`FactoryResponseEventToolPayload`

#FactoryResponseEventToolPayload

FactoryResponseEventToolPayload example

Corpus-constructed examplejson

Payload-only FactoryResponseEventToolPayload body. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{
  "toolCallId": "example-toolCallId",
  "toolName": "example-toolName"
}

FactoryResponseEventToolPayload

object

Tool lifecycle metadata with bounded argument and result summaries.

additionalPropertiesfalse (closed)

Fields

toolCallIdRequiredstring
Stable tool call identifier within the run.
toolNameRequiredstring
Declared tool name for the invocation.
statusOptionalstring
Tool lifecycle status when applicable.
argumentsSummaryOptionalobject
Bounded summary of tool arguments. Not a raw provider protocol payload.
- additionalPropertiestrue (open)
resultSummaryOptionalobject
Bounded summary of tool results. Not a raw provider protocol payload.
- additionalPropertiestrue (open)

Event catalog

`FactoryResponseEventTurnPayload`

#FactoryResponseEventTurnPayload

FactoryResponseEventTurnPayload example

Corpus-constructed examplejson

Payload-only FactoryResponseEventTurnPayload body. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{}

FactoryResponseEventTurnPayload

object

Turn-scoped lifecycle metadata payload.

additionalPropertiesfalse (closed)

Fields

turnIndexOptionalintegerformat: int32
Zero-based turn index within the run when applicable.
- minimum0
statusOptionalstring
Turn lifecycle status when applicable.

Event catalog

`FactoryResponseEventUsagePayload`

#FactoryResponseEventUsagePayload

FactoryResponseEventUsagePayload example

Corpus-constructed examplejson

Payload-only FactoryResponseEventUsagePayload body. Field names and enums come from packaged OpenAPI; values are minimal corpus-constructed placeholders when OpenAPI omits an authored example.

{}

FactoryResponseEventUsagePayload

object

Token or model usage accounting payload.

additionalPropertiesfalse (closed)

Fields

inputTokensOptionalintegerformat: int64
Reported input token count when available.
- minimum0
outputTokensOptionalintegerformat: int64
Reported output token count when available.
- minimum0
totalTokensOptionalintegerformat: int64
Reported total token count when available.
- minimum0
modelOptionalstring
Model identifier associated with the usage report.

Linked component schemas

Nested component schemas referenced from the FactoryEvent and FactoryResponseEvent catalogs above. These shapes come from packaged OpenAPI so deep links and SchemaRefLinks resolve on this page.

`AgentRunToolDiagnosticEntry`

AgentRunToolDiagnosticEntry

object

Bounded summary for one agent tool lifecycle event.

additionalPropertiesfalse (closed)

Fields

toolNameOptionalstring
Tool name invoked by the agent loop.
phaseOptionalstring
Tool lifecycle phase such as start, success, failure, or denied.
detailOptionalstring
Safe diagnostic detail without raw process output or secrets.

`AgentRunTranscriptEntry`

AgentRunTranscriptEntry

object

Bounded transcript metadata for one agent-loop message without exposing full prompt bodies.

additionalPropertiesfalse (closed)

Fields

roleOptionalstring
Message role such as system, user, assistant, or tool.
summaryOptionalstring
Bounded summary of the message content for inspection.

`AgentWorkerToolPolicy`

AgentWorkerToolPolicy

string

Explicit tool execution policy for AGENT_WORKER agent loops. DISABLED runs the harness in no-tools mode. READ_ONLY exposes bounded filesystem read tools. ENABLED adds bounded filesystem write capability for the first supported tool set.

enum"DISABLED" | "READ_ONLY" | "ENABLED"

`AgentWorkerToolsConfig`

AgentWorkerToolsConfig

object

Explicit agent-loop tool policy for AGENT_WORKER definitions. Tool execution stays disabled unless this block is present with a non-DISABLED policy.

additionalPropertiesfalse (closed)

Fields

policyRequiredallOf
Required executor policy for agent-loop tool use on this worker.
$ref →AgentWorkerToolPolicy (reference link; not expanded recursively)

`BundledFile`

BundledFile

object

One explicit portable bundled file entry carried by the factory portability manifest. SCRIPT files target factory/scripts/..., DOC files target factory/docs/..., INPUT files target factory/inputs/<work-type>/<channel>/..., and ROOT_HELPER files target supported project-root helper paths such as Makefile only when declared explicitly in bundledFiles. Export and flatten do not auto-discover project-root helpers. In v1 shared-factory exports, INPUT entries encode a share-time snapshot of starter work that is copied into the recipient factory as detached seeded work.

additionalPropertiesfalse (closed)

Fields

idOptionalstring
Durable bundled-file identifier used by portable layout and graph editor references. When omitted on input, the canonical targetPath is materialized as the stable identifier.
typeRequiredstring
Portable file class. SCRIPT entries target factory/scripts/..., DOC entries target factory/docs/..., INPUT entries target factory/inputs/<work-type>/<channel>/..., and ROOT_HELPER entries target supported project-root helper files such as Makefile only when explicitly declared in bundledFiles. Shared-factory INPUT entries snapshot current source inputs at share time instead of creating a live link.
- enum"SCRIPT" | "DOC" | "INPUT" | "ROOT_HELPER"
targetPathRequiredstring
Canonical factory-relative restoration target for the bundled file. Absolute paths, backslash-separated paths, and paths that require dot-segment normalization are rejected.
contentRequiredBundledFileContent
$ref →BundledFileContent (reference link; not expanded recursively)

`BundledFileContent`

BundledFileContent

object

Inline content payload for a portable bundled file.

additionalPropertiesfalse (closed)

Fields

encodingRequiredstring
Declared content encoding for the inline payload. V1 bundled files use UTF-8 text content.
- enum"utf-8"
inlineRequiredstring
Inline bundled file content carried in the manifest. SCRIPT and DOC files under factory/scripts/ and factory/docs/ may be discovered during flatten, but supported root helper paths such as Makefile are bundled only when they appear as explicit ROOT_HELPER entries in bundledFiles.

`CheckpointResumabilityStatus`

CheckpointResumabilityStatus

string

Whether a recorded checkpoint can be used to resume session execution.

enum"RESUMABLE" | "NOT_RESUMABLE" | "UNKNOWN"

`ClassificationRoute`

ClassificationRoute

object

additionalPropertiesfalse (closed)

Fields

labelRequiredstring
Case-sensitive classifier label that must match the trimmed classifier output exactly.
outputsRequiredWorkstationIO[]
One or more authored destinations emitted when this classifier label is selected.

`Diagnostics`

Diagnostics

object

additionalPropertiesfalse (closed)

Fields

notesOptionalarray
workersOptionalobject
- additionalProperties/components/schemas/SafeWorkDiagnostics

`DispatchConsumedWorkRef`

DispatchConsumedWorkRef

object

Ordered reference to one consumed work item on a dispatch boundary. Dispatch-request payloads keep only the consumed work identity here; work type, trace, display, and other work facts must be derived from prior WORK_REQUEST events plus FactoryEvent.context.

additionalPropertiesfalse (closed)

Fields

workIdRequiredstring
Canonical work identity for one consumed dispatch input.

`DispatchReconciliationSource`

DispatchReconciliationSource

string

Source that produced a dispatch reconciliation fact.

enum"STREAM_REPLAY" | "PROVIDER_SESSION" | "DURABLE_STATE" | "RUNTIME_RECONCILER"

`DispatchRequestEventMetadata`

DispatchRequestEventMetadata

object

Optional non-identity dispatch metadata retained on dispatch-request events. Request, trace, work, and dispatch identity must remain on FactoryEvent.context rather than reappearing here.

additionalPropertiesfalse (closed)

Fields

replayKeyOptionalstring
Stable replay correlation key for recorded dispatch reconstruction.
runnerIdOptionalRunnerID
$ref →RunnerID (reference link; not expanded recursively)
runnerSelectionSourceOptionalRunnerSelectionSource
$ref →RunnerSelectionSource (reference link; not expanded recursively)

`Factory`

Factory

object

Top-level factory.json contract. Declare the work types, resources, portability resources, workers, and workstations that make up one authored factory here. Guarded loop breakers should be authored as guarded LOGICAL_MOVE workstations using VISIT_COUNT guards instead of a top-level exhaustion-rules field.

additionalPropertiesfalse (closed)

Fields

nameRequiredFactoryName
$ref →FactoryName (reference link; not expanded recursively)
idOptionalstring
Factory identifier used as the factory-level template context fallback.
runnerOptionalallOf
Default runner selection for the factory when a workstation does not declare its own runner override.
$ref →RunnerID (reference link; not expanded recursively)
factoryDirectoryOptionalstring
Directory that contained the factory.json used for this serialized runtime config.
sourceDirectoryOptionalstring
Original source directory for record/replay and drift diagnostics.
versionOptionalallOf
Server-managed current-factory version metadata. Clients should echo this value on complete replacement saves when they want stale-write detection, but durable factory configuration does not treat it as customer-authored topology.
$ref →HybridLogicalTimestamp (reference link; not expanded recursively)
metadataOptionalallOf
Free-form factory-level metadata carried through runtime serialization and replay diagnostics.
$ref →StringMap (reference link; not expanded recursively)
orchestratorOptionalallOf
Authored orchestrator identity for this factory. When omitted, existing Petri factories load through compatibility defaulting to orchestrator.kind = PETRI.
$ref →FactoryOrchestrator (reference link; not expanded recursively)
inputTypesOptionalInputType[]
Named input kinds accepted by the factory. The default input type is implicit and must not be declared.
invocationReturnOptionalallOf
Optional factory-authored invocation primary-result policy shared by CLI and API entrypoints. When omitted, runtimes use the SUBMITTED_WORK_TERMINAL fallback and return the first terminal content for the work item originally submitted by the invocation.
$ref →InvocationReturn (reference link; not expanded recursively)
invocationSignatureOptionalallOf
Optional canonical callable argument contract shared by CLI, API, dashboard, docs, and packaged factories. When omitted, callers use the factory's compatibility invocation behavior.
$ref →FactoryInvocationSignature (reference link; not expanded recursively)
guardsOptionalFactoryGuard[]
Root-level guards that apply across the factory instead of one specific workstation or input.
workTypesOptionalWorkType[]
Customer-authored work item categories and the lifecycle states each one can occupy.
resourcesOptionalResource[]
Shared capacity pools that workers or workstations can consume while work is executing.
supportingFilesOptionalallOf
Optional portability manifest for validation-only external tools and portable bundled files. During v1 factory sharing, bundled INPUT files represent a share-time snapshot of the source factory's current inputs work so recipients restore detached starter-work copies that no longer sync back to the original factory. This contract is distinct from runtime-capacity resources.
$ref →ResourceManifest (reference link; not expanded recursively)
layoutOptionalallOf
Optional non-executable graph editor layout metadata keyed by canonical graph node and edge ids.
$ref →FactoryLayout (reference link; not expanded recursively)
workersOptionalWorker[]
Reusable worker definitions that workstations reference by name when dispatching work.
workstationsOptionalWorkstation[]
Processing steps that consume work, invoke workers, and emit the next work states.

`FactoryArtifact`

FactoryArtifact

object

additionalPropertiesfalse (closed)

Fields

idRequiredstring
Stable artifact identifier referenced by session projections.
kindRequiredFactoryArtifactKind
$ref →FactoryArtifactKind (reference link; not expanded recursively)
visibilityRequiredFactoryArtifactVisibility
$ref →FactoryArtifactVisibility (reference link; not expanded recursively)
labelOptionalstring
Customer-visible artifact label.
summaryOptionalstring
Customer-visible artifact summary.
auditModeOptionalFactoryArtifactAuditMode
$ref →FactoryArtifactAuditMode (reference link; not expanded recursively)
redactionCountsOptionalFactoryArtifactRedactionCounts
$ref →FactoryArtifactRedactionCounts (reference link; not expanded recursively)
captureMetadataOptionalFactoryArtifactCaptureMetadata
$ref →FactoryArtifactCaptureMetadata (reference link; not expanded recursively)
contentHashOptionalstring
Stable hash of the stored artifact payload.
sizeBytesOptionalintegerformat: int64
Stored artifact payload size in bytes.

`FactoryArtifactAuditMode`

FactoryArtifactAuditMode

string

Audit mode applied when one factory artifact was captured.

enum"NONE" | "REDACTED" | "FULL"

`FactoryArtifactCaptureMetadata`

FactoryArtifactCaptureMetadata

object

additionalPropertiesfalse (closed)

Fields

capturedAtOptionalstringformat: date-time
Timestamp when the artifact payload was captured.
sourceDispatchIdOptionalstring
Dispatch identifier that produced the artifact when applicable.
mimeTypeOptionalstring
MIME type of the stored artifact payload when known.

`FactoryArtifactKind`

FactoryArtifactKind

string

Canonical factory artifact kind for session-owned outputs.

enum"FINAL_RESULT" | "CHILD_RESULT" | "FINDING" | "PATCH" | "LOG" | "DATASET" | "CHECKPOINT" | "WORKTREE_SUMMARY"

`FactoryArtifactRedactionCounts`

FactoryArtifactRedactionCounts

object

additionalPropertiesfalse (closed)

Fields

secretsOptionalintegerformat: int32
- minimum0
pathsOptionalintegerformat: int32
- minimum0
tokensOptionalintegerformat: int32
- minimum0

`FactoryArtifactRef`

FactoryArtifactRef

object

additionalPropertiesfalse (closed)

Fields

idRequiredstring
Stable artifact identifier referenced by session projections.
kindRequiredFactoryArtifactKind
$ref →FactoryArtifactKind (reference link; not expanded recursively)
visibilityRequiredFactoryArtifactVisibility
$ref →FactoryArtifactVisibility (reference link; not expanded recursively)
contentHashOptionalstring
Stable hash of the stored artifact payload.
sizeBytesOptionalintegerformat: int64
Stored artifact payload size in bytes.

`FactoryArtifactVisibility`

FactoryArtifactVisibility

string

Visibility boundary for one factory artifact projection.

enum"PUBLIC" | "INTERNAL_CHECKPOINT"

`FactoryDispatchKind`

FactoryDispatchKind

string

Canonical dispatch kind shared across Petri transitions and JavaScript workflow tasks.

enum"PETRI_TRANSITION" | "JAVASCRIPT_AGENT" | "JAVASCRIPT_VERIFY" | "JAVASCRIPT_SYNTHESIZE" | "JAVASCRIPT_TOOL" | "JAVASCRIPT_SCRIPT" | "JAVASCRIPT_SYSTEM"

`FactoryDispatchStatus`

FactoryDispatchStatus

string

Canonical dispatch lifecycle status shared across orchestrators.

enum"QUEUED" | "RUNNING" | "COMPLETED" | "FAILED" | "INTERRUPTED"

`FactoryDispatchUsage`

FactoryDispatchUsage

object

additionalPropertiesfalse (closed)

Fields

inputTokensOptionalintegerformat: int64
- minimum0
outputTokensOptionalintegerformat: int64
- minimum0
totalTokensOptionalintegerformat: int64
- minimum0
costUsdOptionalnumberformat: double
- minimum0
durationMillisOptionalintegerformat: int64
- minimum0
retryCountOptionalintegerformat: int32
- minimum0

`FactoryDispatchWarning`

FactoryDispatchWarning

object

additionalPropertiesfalse (closed)

Fields

codeRequiredstring
Stable warning code for the dispatch projection.
messageRequiredstring
Customer-visible warning message.

`FactoryEventSessionResultStatus`

FactoryEventSessionResultStatus

string

Customer-visible session result availability for result update events.

enum"NOT_READY" | "PARTIAL" | "FINAL" | "FAILED_WITH_PARTIAL" | "UNAVAILABLE"

`FactoryGuard`

FactoryGuard

object

Factory-level guard attached at the root factory definition.

additionalPropertiesfalse (closed)

Fields

typeRequiredallOf
Factory-level guard condition to evaluate before dispatch-ready transitions can proceed.
$ref →FactoryGuardType (reference link; not expanded recursively)
modelProviderRequiredallOf
Provider whose inference-throttle history controls this factory-level guard.
$ref →WorkerModelProvider (reference link; not expanded recursively)
modelOptionalstring
Optional model name to scope throttling more narrowly than the provider-level window.
refreshWindowRequiredstring
Duration string that controls how long the factory should keep re-checking throttle history before allowing the lane again.

`FactoryGuardType`

FactoryGuardType

string

Factory-level guard condition attached at the root factory definition.

enum"INFERENCE_THROTTLE_GUARD"

`FactoryInvocationExample`

FactoryInvocationExample

object

One example invocation for docs, help, and packaged-factory inspection.

additionalPropertiesfalse (closed)

Fields

nameRequiredstring
Stable example name.
descriptionOptionalstring
Customer-facing explanation of what the example does.
argvOptionalarray
CLI-style argument vector rendered after factory selection.
stdinOptionalstring
Example stdin payload when the signature routes stdin into one parameter.

`FactoryInvocationOutputContract`

FactoryInvocationOutputContract

object

Customer-facing output hint for a factory invocation signature.

additionalPropertiesfalse (closed)

Fields

modeOptionalallOf
High-level output contract mode exposed to callers.
$ref →FactoryInvocationOutputContractMode (reference link; not expanded recursively)
pathParameterOptionalstring
Parameter name that controls the destination path when the factory writes output to disk.
contentTypeOptionalstring
Output media type hint for docs, API consumers, and dashboard affordances.
fileExtensionOptionalstring
Suggested file extension when the output mode writes a file.
descriptionOptionalstring
Human-readable summary of the primary output contract.

`FactoryInvocationOutputContractMode`

FactoryInvocationOutputContractMode

string

High-level output shape hint exposed by a factory invocation signature.

enum"INLINE" | "FILE" | "JSON"

`FactoryInvocationParameter`

FactoryInvocationParameter

object

One canonical invocation parameter declared on a factory.

additionalPropertiesfalse (closed)

Fields

nameRequiredstring
Internal canonical parameter name used for normalized argument maps and interpolation.
descriptionOptionalstring
Customer-facing description rendered in help, docs, and form controls.
externalNameOptionalstring
Preferred named-argument key shown to callers, such as `output`.
aliasesOptionalarray
Additional accepted named-argument keys that normalize to this parameter.
typeHintOptionalallOf
String-first hint that guides parsing, docs, and dashboard form selection.
$ref →FactoryInvocationParameterTypeHint (reference link; not expanded recursively)
valueModeOptionalallOf
Declares whether the parameter consumes one value, repeated values, variadic values, or file contents.
$ref →FactoryInvocationParameterValueMode (reference link; not expanded recursively)
requiredOptionalboolean
When true, invocation normalization must reject requests that omit this parameter.
sensitiveOptionalboolean
When true, diagnostics must preserve names and source metadata but redact concrete values.
choicesOptionalarray
Optional allowed string values for this parameter.
defaultValueOptionalstring
Default string value used when an omitted parameter resolves to one effective value.
defaultValuesOptionalarray
Default string values used when an omitted parameter resolves to multiple effective values.
bindingsOptionalFactoryInvocationParameterBinding[]
Accepted invocation bindings for this parameter across positional, named, and stdin sources.

`FactoryInvocationParameterBinding`

FactoryInvocationParameterBinding

object

One public binding that exposes a parameter to callers.

additionalPropertiesfalse (closed)

Fields

kindRequiredallOf
Binding kind used to route invocation input into the parameter.
$ref →FactoryInvocationParameterBindingKind (reference link; not expanded recursively)
positionOptionalinteger
1-based positional slot used when kind is POSITIONAL.
- minimum1

`FactoryInvocationParameterBindingKind`

FactoryInvocationParameterBindingKind

string

Public invocation binding kinds supported by factory signatures.

enum"POSITIONAL" | "NAMED" | "STDIN" | "NAMED_REST"

`FactoryInvocationParameterTypeHint`

FactoryInvocationParameterTypeHint

string

String-first parsing and UI hint for one factory invocation parameter.

enum"STRING" | "PATH" | "FILE_PATH" | "DIRECTORY_PATH" | "NUMBER_STRING" | "BOOLEAN_STRING"

`FactoryInvocationParameterValueMode`

FactoryInvocationParameterValueMode

string

Declares how one invocation parameter consumes one or more string values.

enum"EXACT" | "REPEATED" | "VARIADIC" | "FILE_CONTENTS"

`FactoryInvocationSignature`

FactoryInvocationSignature

object

Canonical callable argument contract for invoking one factory. When present, CLI, API, dashboard, docs, and packaged-factory surfaces should discover and normalize invocation inputs from this shared schema instead of transport- or factory-specific argument definitions.

additionalPropertiesfalse (closed)

Fields

parametersOptionalFactoryInvocationParameter[]
Declared invocation parameters keyed by canonical parameter name.
unknownNamedArgumentPolicyOptionalallOf
Policy for named inputs that do not match any declared parameter binding.
$ref →FactoryInvocationUnknownNamedArgumentPolicy (reference link; not expanded recursively)
outputContractOptionalallOf
Optional customer-facing hint for the factory's primary output shape.
$ref →FactoryInvocationOutputContract (reference link; not expanded recursively)
examplesOptionalFactoryInvocationExample[]
Example invocations rendered in docs, help, and inspection surfaces.

`FactoryInvocationUnknownNamedArgumentPolicy`

FactoryInvocationUnknownNamedArgumentPolicy

string

Policy for named inputs that do not match any declared parameter binding.

enum"REJECT" | "ALLOW" | "COLLECT"

`FactoryLayout`

FactoryLayout

object

Non-executable portable graph editor layout metadata keyed by canonical graph ids.

additionalPropertiesfalse (closed)

Fields

schemaVersionRequiredintegerformat: int32
Portable layout contract schema version. Version 1 is the initial public layout contract.
- minimum1
nodesOptionalFactoryLayoutNode[]
Optional authored graph node geometry keyed by canonical graph node id.
edgesOptionalFactoryLayoutEdge[]
Optional authored graph edge geometry keyed by canonical graph edge id.
groupsOptionalFactoryLayoutGroup[]
Optional flat background groups keyed independently from topology.
viewportOptionalFactoryLayoutViewport
$ref →FactoryLayoutViewport (reference link; not expanded recursively)
preferencesOptionalFactoryLayoutPreferences
$ref →FactoryLayoutPreferences (reference link; not expanded recursively)

`FactoryLayoutBounds`

FactoryLayoutBounds

object

Authored rectangular bounds in graph canvas units.

additionalPropertiesfalse (closed)

Fields

xRequirednumber
Left graph layout coordinate.
yRequirednumber
Top graph layout coordinate.
widthRequirednumber
Authored group width.
heightRequirednumber
Authored group height.

`FactoryLayoutEdge`

FactoryLayoutEdge

object

Portable graph edge layout keyed by canonical graph edge id.

additionalPropertiesfalse (closed)

Fields

idRequiredstring
Canonical graph edge id such as workstation-output:workstation:review->work-state:task:done.
waypointsOptionalFactoryLayoutPoint[]
Optional authored intermediate edge points in graph canvas space.
labelPositionOptionalFactoryLayoutPoint
$ref →FactoryLayoutPoint (reference link; not expanded recursively)

`FactoryLayoutGroup`

FactoryLayoutGroup

object

Portable background grouping metadata for graph canvas presentation.

additionalPropertiesfalse (closed)

Fields

idRequiredstring
Stable authored group id for future layout editing.
labelOptionalstring
Optional visible group label.
boundsRequiredFactoryLayoutBounds
$ref →FactoryLayoutBounds (reference link; not expanded recursively)
nodeIdsRequiredarray
Canonical graph node ids visually contained by this group.
parentGroupIdOptionalstringnullable
Reserved for future nested groups. Omit or set null for flat groups.
colorOptionalstring
Optional authored group accent or fill color.
lockedOptionalboolean
Optional authored group lock flag for future editor affordances.

`FactoryLayoutNode`

FactoryLayoutNode

object

Portable graph node layout keyed by canonical graph node id.

additionalPropertiesfalse (closed)

Fields

idRequiredstring
Canonical graph node id such as workstation:<workstationId>.
positionRequiredFactoryLayoutPoint
$ref →FactoryLayoutPoint (reference link; not expanded recursively)
sizeOptionalFactoryLayoutSize
$ref →FactoryLayoutSize (reference link; not expanded recursively)
lockedOptionalboolean
Optional authored node lock flag for future editor affordances.

`FactoryLayoutPoint`

FactoryLayoutPoint

object

Two-dimensional authored graph layout coordinate.

additionalPropertiesfalse (closed)

Fields

xRequirednumber
Horizontal graph layout coordinate in authored canvas space.
yRequirednumber
Vertical graph layout coordinate in authored canvas space.

`FactoryLayoutPreferences`

FactoryLayoutPreferences

object

Portable graph display defaults that do not alter factory topology.

additionalPropertiesfalse (closed)

Fields

directionOptionalstring
Preferred authored graph direction for portable layout rendering.
- enum"UP" | "DOWN" | "LEFT" | "RIGHT"

`FactoryLayoutSize`

FactoryLayoutSize

object

Authored node size in graph canvas units.

additionalPropertiesfalse (closed)

Fields

widthRequirednumber
Authored node width.
heightRequirednumber
Authored node height.

`FactoryLayoutViewport`

FactoryLayoutViewport

object

Shared authored graph camera position.

additionalPropertiesfalse (closed)

Fields

xRequirednumber
Authored viewport horizontal offset.
yRequirednumber
Authored viewport vertical offset.
zoomRequirednumber
Authored viewport zoom factor.

`FactoryName`

FactoryName

string

Customer-facing identifier for one stored named factory. `GET /factory-sessions/~default/factory` may also return the reserved `UNDEFINED` identifier when the active runtime is still the default root factory and no durable current-factory pointer exists. Semantic validation failures return `INVALID_FACTORY_NAME`, including attempts to activate a named factory with the reserved identifier.

pattern^(UNDEFINED|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$
minLength1

`FactoryOrchestrator`

FactoryOrchestrator

object

Authored orchestrator identity for one factory. When omitted, existing Petri factories load through compatibility defaulting to orchestrator.kind = PETRI.

additionalPropertiesfalse (closed)

Fields

kindRequiredFactoryOrchestratorKind
$ref →FactoryOrchestratorKind (reference link; not expanded recursively)
petriOptionalallOf
Petri-specific orchestrator configuration. Required only when kind = PETRI and additional Petri options are authored.
$ref →FactoryOrchestratorPetriConfig (reference link; not expanded recursively)
javascriptOptionalallOf
JavaScript-specific orchestrator configuration. Required when kind = JAVASCRIPT.
$ref →FactoryOrchestratorJavaScriptConfig (reference link; not expanded recursively)

`FactoryOrchestratorJavaScriptAgent`

FactoryOrchestratorJavaScriptAgent

object

Default worker selection for one named JavaScript child-agent role.

additionalPropertiesfalse (closed)

Fields

presetRequiredstring
Operator worker preset inherited by child calls using this agent id.
- minLength1

`FactoryOrchestratorJavaScriptConfig`

FactoryOrchestratorJavaScriptConfig

object

JavaScript-specific orchestrator configuration. JavaScript factories do not require Petri graph fields and instead declare workflow source identity, metadata, args schema, and default policy here.

additionalPropertiesfalse (closed)

Fields

dialectOptionalstring
Optional JavaScript dialect label for the authored workflow source.
sourceRefOptionalstring
Factory-relative or authored reference to the workflow source file.
inlineSourceOptionalallOf
Inline workflow source when the factory carries source text directly.
$ref →FactoryOrchestratorJavaScriptInlineSource (reference link; not expanded recursively)
sourceHashOptionalstring
Optional content hash for the resolved workflow source.
entrypointOptionalstring
Optional exported entrypoint or phase name used to start the workflow.
metadataOptionalallOf
Free-form JavaScript orchestrator metadata for authoring and diagnostics.
$ref →StringMap (reference link; not expanded recursively)
argsSchemaOptionalobject
JSON Schema object describing workflow invocation arguments.
- additionalPropertiestrue (open)
defaultPolicyOptionalobject
Default JavaScript workflow policy object applied when no runtime override exists.
- additionalPropertiestrue (open)
agentsOptionalobject
Named child-agent roles and their operator worker preset defaults.
- additionalProperties/components/schemas/FactoryOrchestratorJavaScriptAgent

`FactoryOrchestratorJavaScriptInlineSource`

FactoryOrchestratorJavaScriptInlineSource

object

Inline JavaScript workflow source carried directly in the factory definition.

additionalPropertiesfalse (closed)

Fields

encodingRequiredstring
Declared content encoding for the inline workflow source.
- enum"utf-8"
inlineRequiredstring
Inline JavaScript workflow source text.

`FactoryOrchestratorKind`

FactoryOrchestratorKind

string

Authored orchestration engine for one factory. PETRI factories use the existing Petri graph semantics. JAVASCRIPT factories use workflow source identity and policy instead of Petri graph fields.

enum"PETRI" | "JAVASCRIPT"

`FactoryOrchestratorPetriConfig`

FactoryOrchestratorPetriConfig

object

Petri-specific orchestrator configuration. Existing Petri factories may omit this block and rely on compatibility defaulting to orchestrator.kind = PETRI.

additionalPropertiesfalse (closed)

`FactoryResponseEventCapabilities`

FactoryResponseEventCapabilities

object

Declares which response-event features a provider session supports. Adapters publish capability flags so consumers can interpret fidelity and phase availability without depending on provider-native schemas.

additionalPropertiesfalse (closed)

Fields

nativeStreamingRequiredboolean
Provider session exposes native streaming observation.
messageDeltasRequiredboolean
Provider session can emit incremental message deltas.
messageSnapshotsRequiredboolean
Provider session can emit message snapshots.
reasoningSummariesRequiredboolean
Provider session can emit reasoning summaries or deltas.
toolLifecycleRequiredboolean
Provider session can emit tool lifecycle metadata.
toolOutputDeltasRequiredboolean
Provider session can emit incremental tool output deltas.
fileChangesRequiredboolean
Provider session can emit observed file changes.
plansRequiredboolean
Provider session can emit plan updates.
usageRequiredboolean
Provider session can emit usage accounting.
stableItemIdsRequiredboolean
Provider session assigns stable item identifiers across events.
providerReconnectRequiredboolean
Provider session supports reconnect after stream interruption.

`FactoryResponseEventContentBlock`

FactoryResponseEventContentBlock

One typed slice of assistant-visible message content. Discriminated by the content block kind field.

oneOf

Discriminator: `kind`

TEXT/components/schemas/FactoryResponseEventTextContentBlock
REASONING_SUMMARY/components/schemas/FactoryResponseEventReasoningSummaryContentBlock
TOOL_REQUEST/components/schemas/FactoryResponseEventToolRequestContentBlock
IMAGE_REF/components/schemas/FactoryResponseEventImageRefContentBlock
RESOURCE_REF/components/schemas/FactoryResponseEventResourceRefContentBlock
STRUCTURED_OUTPUT/components/schemas/FactoryResponseEventStructuredOutputContentBlock

`FactoryResponseEventContentBlockKind`

FactoryResponseEventContentBlockKind

string

Identifies one provider-neutral message content block kind.

enum"TEXT" | "REASONING_SUMMARY" | "TOOL_REQUEST" | "IMAGE_REF" | "RESOURCE_REF" | "STRUCTURED_OUTPUT"

`FactoryResponseEventImageRefContentBlock`

FactoryResponseEventImageRefContentBlock

object

Image reference content block.

additionalPropertiesfalse (closed)

Fields

kindRequiredallOf
- enum"IMAGE_REF"
$ref →FactoryResponseEventContentBlockKind (reference link; not expanded recursively)
imageRefRequiredstring
Reference to an image artifact or URL.

`FactoryResponseEventPlanStep`

FactoryResponseEventPlanStep

object

One step in a published plan snapshot.

additionalPropertiesfalse (closed)

Fields

idRequiredstring
Stable plan step identifier.
descriptionRequiredstring
Human-readable step description.
statusOptionalstring
Plan step status when applicable.

`FactoryResponseEventProvenanceDelivery`

FactoryResponseEventProvenanceDelivery

string

How the response event entered the Factory vocabulary.

enum"NATIVE_STREAM" | "NATIVE_FINAL" | "SYNTHESIZED" | "REPLAY"

`FactoryResponseEventProvenanceFidelity`

FactoryResponseEventProvenanceFidelity

string

How closely the public payload preserves provider detail.

enum"LOSSLESS" | "NORMALIZED" | "LOSSY" | "FINAL_ONLY" | "LIFECYCLE_ONLY"

`FactoryResponseEventProvenanceRepresentation`

FactoryResponseEventProvenanceRepresentation

string

Shape fidelity model used for the public payload.

enum"DELTA" | "SNAPSHOT" | "NOTIFICATION"

`FactoryResponseEventReasoningSummaryContentBlock`

FactoryResponseEventReasoningSummaryContentBlock

object

Reasoning summary text content block.

additionalPropertiesfalse (closed)

Fields

kindRequiredallOf
- enum"REASONING_SUMMARY"
$ref →FactoryResponseEventContentBlockKind (reference link; not expanded recursively)
textRequiredstring
Reasoning summary text.

`FactoryResponseEventResourceRefContentBlock`

FactoryResponseEventResourceRefContentBlock

object

Factory resource reference content block.

additionalPropertiesfalse (closed)

Fields

kindRequiredallOf
- enum"RESOURCE_REF"
$ref →FactoryResponseEventContentBlockKind (reference link; not expanded recursively)
resourceRefRequiredstring
Reference to a factory resource or artifact.

`FactoryResponseEventStructuredOutputContentBlock`

FactoryResponseEventStructuredOutputContentBlock

object

Structured JSON output content block.

additionalPropertiesfalse (closed)

Fields

kindRequiredallOf
- enum"STRUCTURED_OUTPUT"
$ref →FactoryResponseEventContentBlockKind (reference link; not expanded recursively)
structuredOutputRequiredobject
Structured JSON output value.
- additionalPropertiestrue (open)

`FactoryResponseEventTextContentBlock`

FactoryResponseEventTextContentBlock

object

Inline text content block.

additionalPropertiesfalse (closed)

Fields

kindRequiredallOf
- enum"TEXT"
$ref →FactoryResponseEventContentBlockKind (reference link; not expanded recursively)
textRequiredstring
Inline text content.

`FactoryResponseEventToolRequestContentBlock`

FactoryResponseEventToolRequestContentBlock

object

Tool invocation request content block with bounded argument summary.

additionalPropertiesfalse (closed)

Fields

kindRequiredallOf
- enum"TOOL_REQUEST"
$ref →FactoryResponseEventContentBlockKind (reference link; not expanded recursively)
toolCallIdRequiredstring
Stable tool call identifier within the message.
toolNameRequiredstring
Declared tool name for the invocation request.
argumentsSummaryOptionalobject
Bounded summary of tool arguments. Not a raw provider protocol payload.
- additionalPropertiestrue (open)

`FactorySessionDurableLifecycleStatus`

FactorySessionDurableLifecycleStatus

string

Durable factory-session lifecycle status returned by execution start routes and later session read models. Live-session runtime statuses remain separate on the existing FactorySessionStatus schema.

enum"QUEUED" | "AWAITING_APPROVAL" | "RUNNING" | "PAUSED" | "RESUMING" | "SUCCEEDED" | "FAILED" | "CANCELING" | "CANCELED" | "TIMED_OUT" | "INTERRUPTED" | "TERMINATED"

`FactorySessionJavaScriptCheckpointRef`

FactorySessionJavaScriptCheckpointRef

object

additionalPropertiesfalse (closed)

Fields

idRequiredstring
Stable checkpoint identifier referenced by the session runtime.
labelOptionalstring
Customer-visible checkpoint label.
timestampOptionalstringformat: date-time
When the checkpoint was recorded.
summaryOptionalstring
Short customer-visible checkpoint summary without raw VM state.
artifactRefOptionalFactoryArtifactRef
Orchestrator-owned checkpoint artifact metadata without raw VM state.
$ref →FactoryArtifactRef (reference link; not expanded recursively)

`FactorySessionJavaScriptChildDispatchCounts`

FactorySessionJavaScriptChildDispatchCounts

object

additionalPropertiesfalse (closed)

Fields

queuedRequiredinteger
Child dispatches waiting to start.
- minimum0
runningRequiredinteger
Child dispatches currently executing.
- minimum0
completedRequiredinteger
Child dispatches that have completed.
- minimum0

`FactorySessionJavaScriptScriptStatus`

FactorySessionJavaScriptScriptStatus

string

JavaScript workflow script runtime status for one factory session.

enum"IDLE" | "RUNNING" | "PAUSED" | "FINISHED" | "FAILED"

`FactorySessionLifecycleControlKind`

FactorySessionLifecycleControlKind

string

Durable factory-session lifecycle control operation requested by the client.

enum"APPROVE" | "PAUSE" | "RESUME" | "CANCEL" | "TERMINATE" | "RETRY_DISPATCH" | "INTERRUPT_DISPATCH"

`FactorySessionLifecycleControlOutcome`

FactorySessionLifecycleControlOutcome

string

Typed lifecycle-control outcome. ACCEPTED means the control request was accepted and may complete asynchronously. NO_OP means the session was already in the requested end state. INVALID_STATE means the current session state does not allow the requested control. TERMINAL_SESSION means the session is already terminal and cannot accept the requested control. CONFLICT means another in-flight or incompatible control prevents the request.

enum"ACCEPTED" | "NO_OP" | "INVALID_STATE" | "TERMINAL_SESSION" | "CONFLICT"

`FactoryState`

FactoryState

string

Lifecycle state of the running factory.

enum"IDLE" | "RUNNING" | "PAUSED" | "COMPLETED" | "FAILED"

`FactoryStopDispatchSummary`

FactoryStopDispatchSummary

object

additionalPropertiesfalse (closed)

Fields

dispatchIdRequiredstring
Stable dispatch identifier that most directly explains the stopped state.
statusRequiredFactoryDispatchStatus
$ref →FactoryDispatchStatus (reference link; not expanded recursively)
dispatchKindRequiredFactoryDispatchKind
$ref →FactoryDispatchKind (reference link; not expanded recursively)
workstationNameOptionalstring
Customer-authored workstation name when one existing workstation run explains the stop.
failureDetailOptionalFailureDetail
Failure or interruption detail from the latest relevant dispatch when available.
$ref →FailureDetail (reference link; not expanded recursively)

`FactoryStopKind`

FactoryStopKind

string

Canonical inspect classification for stopped automation on existing Factory Session and Work surfaces.

enum"PAUSED" | "BLOCKED" | "NEEDS_HUMAN" | "INTERRUPTED"

`FactoryStopSummary`

FactoryStopSummary

object

additionalPropertiesfalse (closed)

Fields

stopKindRequiredFactoryStopKind
$ref →FactoryStopKind (reference link; not expanded recursively)
sessionIdRequiredstring
Stable Factory Session identifier that owns the stopped work.
workIdOptionalstring
Relevant work identifier when one work item best explains the stop.
workNameOptionalstring
Relevant work name when one work item best explains the stop.
workTypeNameOptionalstring
Relevant work type name when one work item best explains the stop.
workStateOptionalstring
Current authored work state label such as `goal:blocked` when one work item best explains the stop.
sessionLifecycleStatusOptionalFactorySessionDurableLifecycleStatus
Session lifecycle-control status when the stop is explained by pause or another session-level lifecycle condition.
$ref →FactorySessionDurableLifecycleStatus (reference link; not expanded recursively)
latestDispatchOptionalFactoryStopDispatchSummary
$ref →FactoryStopDispatchSummary (reference link; not expanded recursively)
latestResultSummaryOptionalstring
Short operator-readable summary of the latest relevant result when one explains the stop better than a dispatch identifier alone.
suggestedRecoverySurfaceOptionalstring
Existing operator surface to use next, expressed with current Factory Session and Work vocabulary rather than a goal-specific control route.
suggestedRecoveryActionOptionalstring
Human-readable next step that names the existing work or session action the operator should take to recover or continue automation.

`FailureDetail`

FailureDetail

object

additionalPropertiesfalse (closed)

Fields

reasonRequiredWorkFailureType
$ref →WorkFailureType (reference link; not expanded recursively)
messageRequiredstring
Customer-safe, actionable explanation of the failure.
- minLength1

`GuardMatchConfig`

GuardMatchConfig

object

additionalPropertiesfalse (closed)

Fields

inputKeyRequiredstring
Field selector resolved against each candidate input, such as `.Name` or `.Tags["_last_output"]`.
- minLength1

`HostedLinearWorkerClaim`

HostedLinearWorkerClaim

object

Optional claim-related configuration that v1 hosted Linear workers explicitly allow.

additionalPropertiesfalse (closed)

Fields

assigneeFieldOptionalstring
Linear issue field name to use when deriving optional assignee claim metadata.

`HostedLinearWorkerConfig`

HostedLinearWorkerConfig

object

Provider-specific poller configuration for the built-in hosted Linear worker.

additionalPropertiesfalse (closed)

Fields

pollIntervalOptionalstring
Optional Go duration that controls how often the hosted Linear worker polls for updates.
teamIdsOptionalarray
Optional Linear team identifiers that bound the poll source.
stateIdsOptionalarray
Optional Linear issue-state identifiers that bound the poll source.
mappingOptionalallOf
Deterministic mapping fields for canonical work submission generation.
$ref →HostedLinearWorkerMapping (reference link; not expanded recursively)
claimOptionalallOf
Optional claim-related configuration that v1 hosted Linear polling allows.
$ref →HostedLinearWorkerClaim (reference link; not expanded recursively)

`HostedLinearWorkerMapping`

HostedLinearWorkerMapping

object

Deterministic issue-to-work mapping fields owned by a hosted Linear worker.

additionalPropertiesfalse (closed)

Fields

workTypeOptionalstring
Canonical submitted work type emitted for matched Linear issues.
stateOptionalstring
Canonical submitted work state emitted for matched Linear issues.

`HostedWorkerAuth`

HostedWorkerAuth

object

Hosted-worker authentication contract. V1 hosted workers accept only secret references rather than inline credentials or OAuth-style fields.

additionalPropertiesfalse (closed)

Fields

secretRefOptionalstring
Referenced secret name that resolves the hosted provider API key at runtime.

`HostedWorkerProvider`

HostedWorkerProvider

string

Built-in repository-owned hosted worker providers supported by the public factory-config contract.

enum"LINEAR"

`HybridLogicalTimestamp`

HybridLogicalTimestamp

object

additionalPropertiesfalse (closed)

Fields

logicalRequiredstringformat: int64
Monotonic Lamport-style logical component derived from the persisted factory definition version. Serialized as a decimal string so JavaScript clients can round-trip the 64-bit value without precision loss.
- pattern^[0-9]+$
physicalRequiredstringformat: date-time
UTC physical timestamp component for the persisted factory definition version.

`InferenceOutcome`

InferenceOutcome

string

Result category returned by a provider inference attempt.

enum"SUCCEEDED" | "FAILED"

`InputGuard`

InputGuard

object

Guard attached to one specific workstation input.

additionalPropertiesfalse (closed)

Fields

typeRequiredallOf
Guard condition to evaluate for this input-level attachment.
$ref →InputGuardType (reference link; not expanded recursively)
workstationOptionalstring
For `VISIT_COUNT` guards, the workstation whose visits are counted.
maxVisitsOptionalinteger
For `VISIT_COUNT` guards, the visit threshold.
- minimum1
matchConfigOptionalallOf
For `MATCHES_FIELDS` guards, the field-selector configuration used to compare candidate inputs.
$ref →GuardMatchConfig (reference link; not expanded recursively)
parentInputOptionalstring
For parent-aware input guards, the parent workType name from another input in the same workstation.
matchInputOptionalstring
For `SAME_NAME` and `SAME_TRACE_ID` input guards, the peer input workType name from another input in the same workstation.
spawnedByOptionalstring
For dynamic fanout input guards, the workstation that spawns the children for count tracking.

`InputGuardType`

InputGuardType

string

Guard condition attached to one specific workstation input.

enum"VISIT_COUNT" | "ALL_CHILDREN_COMPLETE" | "ANY_CHILD_FAILED" | "SAME_NAME" | "SAME_TRACE_ID"

`InputKind`

InputKind

string

Kinds of input. `DEFAULT` passes opaque input through to workstations as-is.

enum"DEFAULT"

`InputType`

InputType

object

Declared types of inputs. Used to force the inputs of a certain work type to be of a certain shape, like a specific JSON structure.

additionalPropertiesfalse (closed)

Fields

nameRequiredstring
Input type name. The reserved name "default" is implicit.
typeRequiredInputKind
$ref →InputKind (reference link; not expanded recursively)

`InvocationDiagnostic`

InvocationDiagnostic

object

additionalPropertiesfalse (closed)

Fields

signatureHashOptionalstring
parametersOptionalInvocationParameterDiagnostic[]

`InvocationParameterDiagnostic`

InvocationParameterDiagnostic

object

additionalPropertiesfalse (closed)

Fields

nameOptionalstring
sourceKindsOptionalarray
valueCountOptionalintegerformat: int64
- minimum0
redactedOptionalboolean

`InvocationReturn`

InvocationReturn

object

Factory-authored policy for selecting the primary result returned by CLI and API invocations. When omitted from a Factory, runtimes use the documented SUBMITTED_WORK_TERMINAL fallback.

additionalPropertiesfalse (closed)

Fields

policyRequiredallOf
Return selection policy for this factory.
$ref →InvocationReturnPolicy (reference link; not expanded recursively)
workTypeNameOptionalstring
Work type name used by EXPLICIT policy selection.
terminalStateOptionalstring
Authored terminal state name used by EXPLICIT policy selection.
workNameOptionalstring
Optional authored work name filter used by EXPLICIT policy selection.

`InvocationReturnPolicy`

InvocationReturnPolicy

string

Primary-result selection policy for factory invocation responses. SUBMITTED_WORK_TERMINAL traces the work submitted by the invocation until it reaches its first terminal output. EXPLICIT selects configured work content from the invocation submit scope.

enum"SUBMITTED_WORK_TERMINAL" | "EXPLICIT"

`LoadableProviderSessionKind`

LoadableProviderSessionKind

string

Canonical provider-session identifier kind for provider-session detail requests that can be loaded by the API.

enum"session_id"

`LoadableProviderSessionProvider`

LoadableProviderSessionProvider

string

Canonical provider value for provider-session detail requests that can be loaded by the API.

enum"codex" | "cursor"

`LoadableProviderSessionRef`

LoadableProviderSessionRef

object

additionalPropertiesfalse (closed)

Fields

providerRequiredLoadableProviderSessionProvider
$ref →LoadableProviderSessionProvider (reference link; not expanded recursively)
kindRequiredLoadableProviderSessionKind
$ref →LoadableProviderSessionKind (reference link; not expanded recursively)
idRequiredstring
Provider-session identifier to resolve. This is an identifier, not a filesystem path.

`ModelOperation`

ModelOperation

object

One provider-agnostic operation exposed by a model worker, such as `TTS`.

additionalPropertiesfalse (closed)

Fields

nameRequiredModelOperationName
$ref →ModelOperationName (reference link; not expanded recursively)
inputsOptionalModelOperationSlot[]
Named operation input slots this worker can consume.
outputsOptionalModelOperationSlot[]
Named operation output slots this worker can produce.

`ModelOperationContentType`

ModelOperationContentType

string

Uppercase content-part categories supported by worker model-operation capability slots.

enum"TEXT" | "IMAGE" | "AUDIO" | "JSON" | "BINARY"

`ModelOperationName`

ModelOperationName

string

Uppercase public operation identifier such as `TTS`, `ASR`, or `EMBED`.

pattern^[A-Z][A-Z0-9_]*$

`ModelOperationSlot`

ModelOperationSlot

object

One named capability slot declared by a model operation.

additionalPropertiesfalse (closed)

Fields

nameRequiredstring
Stable slot name used by workstation-side bindings and diagnostics.
contentTypesRequiredModelOperationContentType[]
Uppercase content types accepted or produced by this slot.
- minItems1
requiredOptionalboolean
Whether this input slot must be resolved before invocation starts. Output slots omit this field when not needed.

`ModelResourceSummary`

ModelResourceSummary

object

Fields

nameRequiredstring
Factory-authored resource name.
typeRequiredResourceType
$ref →ResourceType (reference link; not expanded recursively)
capacityRequiredinteger
Declared factory capacity for this resource.
- minimum0
modelOptionalstring
Concrete model identifier when the resource is model-specific.
backendOptionalstring
Local runtime backend identifier for model resources.
loadPolicyOptionalstring
Local load-policy metadata for model resources.
providerOptionalstring
Cloud provider identity when the resource models quota or routing.

`OrchestratorPhaseStatus`

OrchestratorPhaseStatus

string

Canonical workflow phase lifecycle status for orchestrator phase events.

enum"ACTIVE" | "COMPLETED" | "SKIPPED"

`ProviderDiagnostic`

ProviderDiagnostic

object

additionalPropertiesfalse (closed)

Fields

providerOptionalstring
modelOptionalstring
requestMetadataOptionalStringMap
$ref →StringMap (reference link; not expanded recursively)
responseMetadataOptionalStringMap
$ref →StringMap (reference link; not expanded recursively)

`ProviderFailureMetadata`

ProviderFailureMetadata

object

additionalPropertiesfalse (closed)

Fields

familyOptionalWorkFailureFamily
$ref →WorkFailureFamily (reference link; not expanded recursively)
typeOptionalWorkFailureType
$ref →WorkFailureType (reference link; not expanded recursively)

`ProviderSessionMetadata`

ProviderSessionMetadata

object

additionalPropertiesfalse (closed)

Fields

providerOptionalstring
kindOptionalstring
idOptionalstring

`Relation`

Relation

object

additionalPropertiesfalse (closed)

Fields

typeRequiredRelationType
$ref →RelationType (reference link; not expanded recursively)
targetWorkIdOptionalstring
targetWorkNameRequiredstring
sourceWorkNameRequiredstring
requiredStateOptionalstring

`RelationType`

RelationType

string

Relationship category between two pieces of work.

enum"DEPENDS_ON" | "PARENT_CHILD" | "SPAWNED_BY"

`RenderedPromptDiagnostic`

RenderedPromptDiagnostic

object

additionalPropertiesfalse (closed)

Fields

systemPromptHashOptionalstring
userMessageHashOptionalstring
variablesOptionalStringMap
$ref →StringMap (reference link; not expanded recursively)

`RequiredTool`

RequiredTool

object

One declarative external tool dependency for a portable factory.

additionalPropertiesfalse (closed)

Fields

nameRequiredstring
Human-readable tool name used in manifests and validation output.
commandRequiredstring
Executable lookup token that must resolve on PATH.
purposeOptionalstring
Optional explanation of why the portable factory requires this tool.
versionArgsOptionalarray
Optional argument vector used by future validation flows to probe the tool version without changing the executable lookup token.

`ResolvedModelOperationBinding`

ResolvedModelOperationBinding

object

additionalPropertiesfalse (closed)

Fields

slotRequiredstring
Stable input slot name declared by the worker capability.
sourceRequiredResolvedModelOperationBindingSource
$ref →ResolvedModelOperationBindingSource (reference link; not expanded recursively)
contentRequiredWorkContent
Resolved content bound to the slot.
$ref →WorkContent (reference link; not expanded recursively)

`ResolvedModelOperationBindingSource`

ResolvedModelOperationBindingSource

string

Source used to resolve one invocation slot binding.

enum"INPUT" | "CONFIG" | "DEFAULT" | "OMITTED"

`Resource`

Resource

object

Shared capacity that limits how much work the factory can run at once, such as worker slots or external service quotas.

additionalPropertiesfalse (closed)

Fields

idOptionalstring
Optional durable public identifier for this resource. When present, graph and layout references should use this id instead of the mutable name.
nameRequiredstring
Resource name referenced from worker requirements and workstation resourceUsage entries.
typeOptionalallOf
Optional uppercase resource family, such as `MODEL`, `PROVIDER_QUOTA`, or `INVOCATION_SLOT`.
$ref →ResourceType (reference link; not expanded recursively)
capacityRequiredinteger
Total units of this resource available to the factory at one time.
- minimum1
modelOptionalstring
Stable managed runtime identity for `MODEL` resources, such as `OMNIVOICE_Q4_K_M`. Packaged and authored factories declare the same managed-runtime dependency through this field plus matching `MODEL_WORKER.model` values.
backendOptionalstring
Managed runtime backend identifier for `MODEL` resources, such as `LLAMACPP`. Backend selection stays provider-agnostic in customer-facing factory config.
loadPolicyOptionalstring
Managed runtime load policy for `MODEL` resources, such as `ON_DEMAND` or `EAGER`.
providerOptionalstring
Provider identity associated with this resource, especially for `PROVIDER_QUOTA` resources.

`ResourceManifest`

ResourceManifest

object

Canonical portability manifest for Agent Factory bundles. Required tools are validation-only PATH dependencies; bundled files carry portable content for restoration inside the factory boundary.

additionalPropertiesfalse (closed)

Fields

requiredToolsOptionalRequiredTool[]
Declarative external tools that must already resolve on PATH. These entries are validated but not embedded or installed.
bundledFilesOptionalBundledFile[]
Portable bundled files that belong inside the factory boundary. Entries are explicit only, use factory-relative target paths, and must stay under the canonical script, docs, or inputs roots for SCRIPT, DOC, or INPUT entries, or match the supported root-helper allowlist for ROOT_HELPER entries. Export, share, flatten, and materialize flows auto-discover SCRIPT and DOC files under the documented factory subtrees, but ROOT_HELPER entries such as Makefile are opt-in manifest entries that travel only when explicitly declared here. In v1 shared-factory flows, INPUT entries capture the source factory's current starter work at share time and are restored as independent recipient copies.

`ResourceRequirement`

ResourceRequirement

object

additionalPropertiesfalse (closed)

Fields

nameRequiredstring
capacityRequiredinteger
- minimum1

`ResourceType`

ResourceType

string

Uppercase resource families supported by the public factory-config contract.

enum"MODEL" | "PROVIDER_QUOTA" | "INVOCATION_SLOT"

`RunnerID`

RunnerID

string

Stable built-in runner identifiers supported by factory and workstation runner selection.

enum"codex" | "gemini" | "kiro" | "cursor-cli" | "opencode" | "pi"

`RunnerSelectionSource`

RunnerSelectionSource

string

Configuration layer that supplied the resolved built-in runner selection for a dispatch.

enum"workstation" | "factory" | "legacy_provider" | "default"

`SafeAgentRunDiagnostic`

SafeAgentRunDiagnostic

object

Dashboard-safe agent-run inspection metadata distinct from provider-session transcript ownership.

additionalPropertiesfalse (closed)

Fields

executionBehaviorOptionalstring
Stable execution behavior marker for agent-loop runs.
- enum"agent_run"
failureClassOptionalstring
Stable agent-run failure class when execution failed.
recoveryActionOptionalstring
Customer-visible recovery guidance for actionable agent-run failures.
toolPolicyOptionalstring
Effective agent tool policy for the run.
toolCallCountOptionalintegerformat: int32
Number of recorded tool lifecycle events for the run.
- minimum0
toolDiagnosticsOptionalAgentRunToolDiagnosticEntry[]
Bounded tool diagnostics separate from final agent output.
transcriptOptionalAgentRunTranscriptEntry[]
Bounded transcript metadata separate from tool diagnostics and final output.

`SafeWorkDiagnostics`

SafeWorkDiagnostics

object

Dashboard-facing execution diagnostics that omit raw prompts, command stdin, and command environment values.

additionalPropertiesfalse (closed)

Fields

renderedPromptOptionalRenderedPromptDiagnostic
$ref →RenderedPromptDiagnostic (reference link; not expanded recursively)
providerOptionalProviderDiagnostic
$ref →ProviderDiagnostic (reference link; not expanded recursively)
agentRunOptionalSafeAgentRunDiagnostic
$ref →SafeAgentRunDiagnostic (reference link; not expanded recursively)
invocationOptionalInvocationDiagnostic
$ref →InvocationDiagnostic (reference link; not expanded recursively)

`ScriptExecutionOutcome`

ScriptExecutionOutcome

string

Result category returned by one public script execution boundary.

enum"SUCCEEDED" | "FAILED_EXIT_CODE" | "TIMED_OUT" | "PROCESS_ERROR"

`ScriptFailureType`

ScriptFailureType

string

Stable failure classification for script responses without a normal process exit code.

enum"TIMEOUT" | "PROCESS_ERROR"

`StringMap`

StringMap

object

additionalPropertiestrue (open)

`WallClock`

WallClock

object

additionalPropertiesfalse (closed)

Fields

startedAtOptionalstringformat: date-time
finishedAtOptionalstringformat: date-time

`Work`

Work

object

A piece of work.

additionalPropertiesfalse (closed)

Fields

nameRequiredstring
A human readable name for the work, not unique
workIdOptionalstring
Unique identifier for the work
requestIdOptionalstring
Identifier for the original request that created this work, if applicable
workTypeNameOptionalstring
Configured work type name from factory.json for this submitted work item.
stateOptionalWorkState
Current lifecycle state for this work item when returned by read APIs. Submit requests use the state's name when an explicit initial state is provided.
$ref →WorkState (reference link; not expanded recursively)
chainingTraceDepthOptionalinteger
Current chaining depth for this work item when the runtime already knows its upstream lineage.
- minimum1
currentChainingTraceIdOptionalstring
Explicit chaining-trace identifier for this submitted work item.
previousChainingTraceIdsOptionalarray
Explicit predecessor chaining traces that directly caused this work item.
traceIdOptionalstring
Legacy trace identifier retained for compatibility; prefer currentChainingTraceId.
contentOptionalWorkContent
Optional canonical ordered work content parts for this work item.
$ref →WorkContent (reference link; not expanded recursively)
payloadOptional
Opaque work payload forwarded as raw JSON, or a binary data, or whatever else.
tagsOptionalStringMap
Key-value pairs for storing arbitrary metadata about the work. Both keys and values are strings.
$ref →StringMap (reference link; not expanded recursively)
relationsOptionalRelation[]
Current outbound relationships attached to this listed source work item when returned by read APIs.
stopSummaryOptionalFactoryStopSummary
Canonical stopped-state summary for existing work inspection reads when this work item explains paused, blocked, needs-human, or interrupted automation.
$ref →FactoryStopSummary (reference link; not expanded recursively)

`WorkAudioContentPart`

WorkAudioContentPart

object

Ordered audio content for one work item.

allOf

/components/schemas/WorkContentCommonFields

Fields

typeRequiredallOf
- enum"AUDIO"
$ref →WorkContentPartType (reference link; not expanded recursively)
urlRequiredWorkContentURLProperty
$ref →WorkContentURLProperty (reference link; not expanded recursively)
fileOptionalWorkContentDeprecatedFileProperty
$ref →WorkContentDeprecatedFileProperty (reference link; not expanded recursively)

`WorkBinaryContentPart`

WorkBinaryContentPart

object

Ordered binary content for one work item.

allOf

/components/schemas/WorkContentCommonFields

Fields

typeRequiredallOf
- enum"BINARY"
$ref →WorkContentPartType (reference link; not expanded recursively)
urlRequiredWorkContentURLProperty
$ref →WorkContentURLProperty (reference link; not expanded recursively)
fileOptionalWorkContentDeprecatedFileProperty
$ref →WorkContentDeprecatedFileProperty (reference link; not expanded recursively)

`WorkContent`

WorkContent

array

Ordered canonical content parts for one work item.

`WorkContentCommonFields`

WorkContentCommonFields

object

Fields

slotOptionalstring
Optional slot name used by model-operation binding selectors and diagnostics.
labelOptionalstring
Optional caller-defined label for slot binding or diagnostics.
roleOptionalstring
Optional semantic role for model-operation authoring.
contentTypeOptionalstring
Optional MIME content type for file-backed or structured parts.
artifactIdOptionalstring
Optional artifact identifier for externally materialized content.
metadataOptionalWorkContentMetadata
$ref →WorkContentMetadata (reference link; not expanded recursively)

`WorkContentDeprecatedFileProperty`

WorkContentDeprecatedFileProperty

string

Deprecated host-local file path. Use url instead. Legacy values may be normalized to url at ingest during migration.

`WorkContentMetadata`

WorkContentMetadata

object

Optional metadata attached to one work content part.

additionalPropertiestrue (open)

`WorkContentPart`

WorkContentPart

One ordered canonical content part on a work item.

oneOf

`WorkContentPartType`

WorkContentPartType

string

Supported canonical work content part types. Legacy lowercase text and image values remain accepted for backward compatibility.

enum"text" | "image" | "TEXT" | "IMAGE" | "AUDIO" | "JSON" | "BINARY"

`WorkContentURLProperty`

WorkContentURLProperty

string

Canonical content reference for file-backed parts. Supported schemes are file://, http://, https://, data:, and you-artifact:// for session-scoped factory artifact refs.

minLength1

`Worker`

Worker

object

A reusable worker definition that tells the factory how a workstation should execute work, such as through a model-backed agent or a script.

additionalPropertiesfalse (closed)

Fields

idOptionalstring
Optional durable public identifier for this worker. When present, graph and layout references should use this id instead of the mutable name.
nameRequiredstring
Worker name referenced by Workstation.worker.
typeOptionalallOf
Worker implementation family to instantiate for this definition.
$ref →WorkerType (reference link; not expanded recursively)
providerOptionalallOf
Built-in hosted provider identity when this worker uses repository-owned hosted execution.
$ref →HostedWorkerProvider (reference link; not expanded recursively)
modelOptionalstring
Model identifier to request from the configured model provider when this worker uses model execution.
modelProviderOptionalallOf
Canonical model-provider identifier used for model routing and provider diagnostics. Current public built-in values are `CLAUDE` and `CODEX`; the runtime maps them onto the underlying provider command IDs.
$ref →WorkerModelProvider (reference link; not expanded recursively)
modelLocalityOptionalallOf
Provider locality for this model capability declaration. Use `LOCAL` for embedded or host-managed inference and `CLOUD` for remote provider execution.
$ref →WorkerModelLocality (reference link; not expanded recursively)
executorProviderOptionalallOf
Canonical executor adapter identifier used to select the worker execution provider or wrapper. The current public built-in value is `SCRIPT_WRAP`.
$ref →WorkerProvider (reference link; not expanded recursively)
operationsOptionalModelOperation[]
Provider-agnostic model operations that this worker can execute, including named input and output slots.
commandOptionalstring
Command to execute when this worker runs through a command or script provider.
argsOptionalarray
Additional command arguments passed to the configured command.
resourcesOptionalResourceRequirement[]
Resource capacity this worker requires before it can be dispatched.
timeoutOptionalstring
Optional Go duration that caps one worker execution attempt.
stopTokenOptionalstring
Marker that tells model-oriented workers where to stop generated output when the provider supports it.
skipPermissionsOptionalboolean
When true, bypasses permission checks for providers that support permission gating.
openCodeAgentOptionalstring
Optional OpenCode agent profile name for model workers that dispatch through the OpenCode runner. When set, OpenCode dispatches invoke `opencode run --agent <name>`. Discover agent names with `opencode agent list` (see https://opencode.ai/docs/cli/).
authOptionalallOf
Hosted-worker authentication contract. V1 hosted workers accept only auth.secretRef.
$ref →HostedWorkerAuth (reference link; not expanded recursively)
linearOptionalallOf
Provider-specific configuration for the built-in hosted LINEAR worker.
$ref →HostedLinearWorkerConfig (reference link; not expanded recursively)
agentToolsOptionalallOf
Explicit agent-loop tool policy for AGENT_WORKER definitions. Omit or set policy DISABLED to run agent loops without advertising or executing tools.
$ref →AgentWorkerToolsConfig (reference link; not expanded recursively)
bodyOptionalstring
Inline worker instructions or script body when the worker is authored directly in factory config.

`WorkerModelLocality`

WorkerModelLocality

string

Provider locality for a model worker capability declaration.

enum"LOCAL" | "CLOUD"

`WorkerModelProvider`

WorkerModelProvider

string

Canonical model-provider identifiers supported by model workers in factory config.

enum"CLAUDE" | "CODEX" | "CURSOR" | "GEMINI" | "KIRO" | "OPENCODE" | "PI" | "AGY"

`WorkerProvider`

WorkerProvider

string

Concrete worker-provider wrappers supported by the public factory-config contract.

enum"SCRIPT_WRAP"

`WorkerType`

WorkerType

string

Worker implementation families supported by the public factory-config contract.

enum"INFERENCE_WORKER" | "AGENT_WORKER" | "SCRIPT_WORKER" | "POLLER_WORKER" | "MODEL_WORKER" | "HOSTED_WORKER"

`WorkFailureFamily`

WorkFailureFamily

string

Stable machine-readable failure family used to decide retry and routing behavior for failed work.

enum"terminal" | "retryable" | "throttle"

`WorkFailureType`

WorkFailureType

string

Stable machine-readable failure type used to classify failed work across providers and runtimes.

enum"auth_failure" | "permanent_bad_request" | "throttled" | "internal_server_error" | "timeout" | "unknown" | "misconfigured" | "missing_executable" | "command_line_too_long"

`WorkImageContentPart`

WorkImageContentPart

object

Ordered image content for one work item.

allOf

/components/schemas/WorkContentCommonFields

Fields

typeRequiredallOf
- enum"image" | "IMAGE"
$ref →WorkContentPartType (reference link; not expanded recursively)
urlRequiredWorkContentURLProperty
$ref →WorkContentURLProperty (reference link; not expanded recursively)
fileOptionalWorkContentDeprecatedFileProperty
$ref →WorkContentDeprecatedFileProperty (reference link; not expanded recursively)

`WorkJsonContentPart`

WorkJsonContentPart

object

Ordered JSON content for one work item.

allOf

/components/schemas/WorkContentCommonFields

Fields

typeRequiredallOf
- enum"JSON"
$ref →WorkContentPartType (reference link; not expanded recursively)
jsonRequired
Arbitrary JSON value preserved in canonical part order.

`WorkMetrics`

WorkMetrics

object

additionalPropertiesfalse (closed)

Fields

durationMillisOptionalintegerformat: int64
- minimum0
costOptionalnumberformat: double
retryCountOptionalinteger

`WorkOutcome`

WorkOutcome

string

Result category returned by a workstation execution.

enum"ACCEPTED" | "CONTINUE" | "REJECTED" | "FAILED"

`WorkPropagation`

WorkPropagation

object

Optional workstation policy for how downstream work receives payload content after this workstation completes. When omitted, downstream work uses the workstation output payload.

additionalPropertiesfalse (closed)

Fields

modeRequiredallOf
Propagation mode for downstream work payload selection after this workstation succeeds.
$ref →WorkPropagationMode (reference link; not expanded recursively)

`WorkPropagationMode`

WorkPropagationMode

string

Work payload propagation mode for a workstation. OUTPUT_AS_PAYLOAD uses the workstation output as the downstream work payload. PRESERVE_INPUT keeps the consumed input payload for downstream work instead of replacing it with the workstation output.

enum"OUTPUT_AS_PAYLOAD" | "PRESERVE_INPUT"

`WorkRequestType`

WorkRequestType

string

Kind of work request accepted by the factory.

enum"FACTORY_REQUEST_BATCH"

`WorkState`

WorkState

object

A lifecycle state that a work item can occupy inside one work type.

additionalPropertiesfalse (closed)

Fields

idOptionalstring
Optional durable public identifier for this state within its work type. When present, graph and layout references should use this id instead of the mutable name.
nameRequiredstring
Customer-authored state name referenced by workstation inputs and outputs.
typeRequiredallOf
Lifecycle category for this state, such as initial, processing, terminal, or failed.
$ref →WorkStateType (reference link; not expanded recursively)

`WorkStateChangeSource`

WorkStateChangeSource

string

Origin of a WORK_STATE_CHANGE event.

enum"api" | "cli" | "cascading-failure"

`WorkStateType`

WorkStateType

string

Categories of work states. The factory runtime treats these categories differently for lifecycle tracking and metrics purposes. Initial: The work is waiting to be picked up by a workstation. Processing: The work has been partially processed, and is continuing through its lifecycle. Terminal: The work has completed successfully. Failed: The work has failed.

enum"INITIAL" | "PROCESSING" | "TERMINAL" | "FAILED"

`Workstation`

Workstation

object

A processing step in the factory graph. Workstations consume authored work states, run a worker or logical move, and emit the next work states.

additionalPropertiesfalse (closed)

Fields

idOptionalstring
Optional durable public identifier for this workstation. Graph and layout references should use this id instead of the mutable name.
nameRequiredstring
Customer-authored workstation name used by guards, diagnostics, and authored references.
behaviorOptionalallOf
Scheduling behavior for this workstation, such as STANDARD, REPEATER, or CRON execution.
$ref →WorkstationKind (reference link; not expanded recursively)
typeOptionalallOf
Runtime workstation implementation type, equivalent to the workstation AGENTS.md frontmatter type.
$ref →WorkstationType (reference link; not expanded recursively)
operationOptionalallOf
Uppercase provider-agnostic operation requested by `MODEL_INVOKE` workstations, such as `TTS`.
$ref →ModelOperationName (reference link; not expanded recursively)
operationBindingsOptionalWorkstationOperationBinding[]
Optional workstation-authored slot bindings that resolve operation inputs from runtime content or static config content.
workerRequiredstring
Name of a worker declared in the workers list.
runnerOptionalallOf
Optional workstation-specific runner override. When omitted, dispatch falls back to the factory runner, then worker modelProvider compatibility when no explicit runner is configured, then the default codex runner.
$ref →RunnerID (reference link; not expanded recursively)
openCodeAgentOptionalstring
Optional OpenCode agent profile override for this workstation. When set, overrides the worker default for OpenCode dispatches and invokes `opencode run --agent <name>`. Discover agent names with `opencode agent list` (see https://opencode.ai/docs/cli/).
promptFileOptionalstring
Path to a prompt template file loaded for model-oriented workstation execution.
outputSchemaOptionalstring
JSON schema string used to validate or parse structured model output when configured.
outcomeFormatOptionalallOf
Optional worker-output parsing mode for model workstations. When set to `decision-envelope`, agent output is parsed as a reviewer/checker JSON envelope that maps directly onto WorkResult outcome, feedback, output, and optional recorded output work instead of stop-token routing.
$ref →WorkstationOutcomeFormat (reference link; not expanded recursively)
limitsOptionalallOf
Retry and execution ceilings applied to this workstation.
$ref →WorkstationLimits (reference link; not expanded recursively)
workPropagationOptionalallOf
Optional policy for whether downstream work uses the workstation output payload or preserves the consumed input payload.
$ref →WorkPropagation (reference link; not expanded recursively)
bodyOptionalstring
Inline workstation instructions or script body when authored directly in factory config.
cronOptionalallOf
Cron trigger configuration for workstations whose behavior is CRON.
$ref →WorkstationCron (reference link; not expanded recursively)
inputsRequiredWorkstationIO[]
Work states this workstation can consume before it dispatches.
outputsOptionalWorkstationIO[]
Work states emitted after a non-classifier workstation succeeds. Classifier workstations must use classificationRoutes instead of normal success outputs.
classificationRoutesOptionalClassificationRoute[]
Explicit label-to-destination routing used only by CLASSIFIER_WORKSTATION definitions. Each route must declare a unique non-empty label and one or more outputs.
onContinueOptionalWorkstationIO[]
Optional destination emitted when the workstation makes partial progress and should continue iterating. Classifier workstations must not declare onContinue.
onRejectionOptionalWorkstationIO[]
Optional destination emitted when the worker rejects the current work without a hard failure. Classifier workstations must not declare onRejection.
onFailureOptionalWorkstationIO[]
Optional destination emitted when the workstation fails permanently.
resourcesOptionalResourceRequirement[]
Resource capacity this workstation consumes while one dispatch is in flight.
copyReferencedScriptsOptionalboolean
Copy supported referenced script files into the expanded workstation layout when config expand runs.
guardsOptionalWorkstationGuard[]
Guarded loop breakers should use `VISIT_COUNT` guards here with a `LOGICAL_MOVE` workstation instead of top-level exhaustion rules.
stopWordsOptionalarray
Stop words authored on the topology entry for model-oriented dispatches.
workingDirectoryOptionalstring
Go template resolved from token tags at dispatch time.
worktreeOptionalstring
Go template resolved and passed as the worktree path to CLI dispatchers.
envOptionalallOf
Environment variables added to the workstation execution context.
$ref →StringMap (reference link; not expanded recursively)

`WorkstationCron`

WorkstationCron

object

Trigger timing for cron workstations. Cron workstations use a schedule expression; interval triggers are not supported.

additionalPropertiesfalse (closed)

Fields

scheduleRequiredstring
Standard five-field cron expression used to produce internal time work while the factory service is running.
triggerAtStartOptionalboolean
When true, service startup submits one immediate internal time work item before waiting for the next scheduled cron fire.
Defaultfalse
jitterOptionalstring
Non-negative Go duration used as the maximum deterministic delay added to scheduled time tokens. Defaults to "0s".
expiryWindowOptionalstring
Positive Go duration after due_at before a stale cron time token expires and can be consumed by the system expiry transition. Defaults to the duration until the next scheduled cron fire when omitted.

`WorkstationGuard`

WorkstationGuard

object

Guard attached to a workstation as a whole.

additionalPropertiesfalse (closed)

Fields

typeRequiredallOf
Guard condition to evaluate for this workstation-level attachment.
$ref →WorkstationGuardType (reference link; not expanded recursively)
workstationOptionalstring
For `VISIT_COUNT` guards, the workstation whose visits are counted.
maxVisitsOptionalinteger
For `VISIT_COUNT` guards, the visit threshold.
- minimum1
matchConfigOptionalallOf
For `MATCHES_FIELDS` guards, the field-selector configuration used to compare candidate inputs.
$ref →GuardMatchConfig (reference link; not expanded recursively)
parentInputOptionalstring
For parent-aware input guards, the parent workType name from another input in the same workstation.
matchInputOptionalstring
For `SAME_NAME` and `SAME_TRACE_ID` input guards, the peer input workType name from another input in the same workstation.
spawnedByOptionalstring
For dynamic fanout input guards, the workstation that spawns the children for count tracking.

`WorkstationGuardType`

WorkstationGuardType

string

Guard condition attached to a workstation as a whole.

enum"VISIT_COUNT" | "MATCHES_FIELDS"

`WorkstationIO`

WorkstationIO

object

One authored work-state reference consumed or emitted by a workstation.

additionalPropertiesfalse (closed)

Fields

workTypeRequiredstring
Name of the work type consumed or emitted at this edge of the workstation.
stateRequiredstring
Name of the work state consumed or emitted for the referenced work type.
guardsOptionalInputGuard[]
Per-input guards that must pass before this specific input can be used.

`WorkstationKind`

WorkstationKind

string

Scheduling kind for a workstation, which determines how the engine schedules and dispatches work to it. Standard workstations are scheduled as soon as their inputs are ready, and can have multiple work items in-flight at the same time. Repeater workstations are triggered whenever their inputs change, and will reloop the outputs on rejection back to the initial place. Cron workstations create internal time work and dispatch their configured worker when time and input guards are satisfied. Poller workstations bind a poller-capable worker that the service runtime supervises as a long-lived ingress loop.

Default"STANDARD"

enum"STANDARD" | "REPEATER" | "CRON" | "POLLER"

`WorkstationLimits`

WorkstationLimits

object

Retry and execution ceilings applied to one workstation definition.

additionalPropertiesfalse (closed)

Fields

maxRetriesOptionalinteger
Maximum number of retry attempts after a failed dispatch before the workstation gives up.
maxExecutionTimeOptionalstring
Go duration limit for one dispatch attempt before it times out.

`WorkstationOperationBinding`

WorkstationOperationBinding

object

One workstation-authored binding for a provider-agnostic model-operation input slot.

additionalPropertiesfalse (closed)

Fields

slotRequiredstring
Stable input slot name declared by the worker operation.
selectorOptionalallOf
Ordered runtime-input selector used before falling back to config or default content.
$ref →WorkstationOperationBindingSelector (reference link; not expanded recursively)
configOptionalallOf
Static authored content bound directly or used as the first fallback when runtime input does not match.
$ref →WorkContent (reference link; not expanded recursively)
defaultContentOptionalallOf
Optional final fallback content when neither runtime input nor config content resolves the slot.
$ref →WorkContent (reference link; not expanded recursively)

`WorkstationOperationBindingSelector`

WorkstationOperationBindingSelector

object

Selector fields used to resolve one content part from ordered runtime input.

additionalPropertiesfalse (closed)

Fields

slotOptionalstring
Match a content part by its authored slot field.
labelOptionalstring
Match a content part by its label field.
typeOptionalallOf
Match a content part by its uppercase public type.
$ref →ModelOperationContentType (reference link; not expanded recursively)
roleOptionalstring
Match a content part by its role field.

`WorkstationOutcomeFormat`

WorkstationOutcomeFormat

string

Optional worker-output parsing mode for model workstations. When set to `decision-envelope`, agent output is parsed as a reviewer/checker JSON envelope that maps directly onto WorkResult outcome, feedback, output, and optional recorded output work instead of stop-token routing.

enum"decision-envelope"

`WorkstationType`

WorkstationType

string

Runtime workstation implementation types supported by the public factory-config contract.

enum"INFERENCE_RUN" | "AGENT_RUN" | "SCRIPT_RUN" | "POLLER_RUN" | "MODEL_WORKSTATION" | "MODEL_INVOKE" | "LOGICAL_MOVE" | "CLASSIFIER_WORKSTATION"

`WorkTextContentPart`

WorkTextContentPart

object

Ordered inline text content for one work item.

allOf

/components/schemas/WorkContentCommonFields

Fields

typeRequiredallOf
- enum"text" | "TEXT"
$ref →WorkContentPartType (reference link; not expanded recursively)
textRequiredstring
Inline text content preserved in canonical part order.

`WorkType`

WorkType

object

A named category of work that can move through the factory. Each work type declares the lifecycle states its work items can occupy.

additionalPropertiesfalse (closed)

Fields

idOptionalstring
Optional durable public identifier for this work type. When present, graph and layout references should use this id instead of the mutable name.
nameRequiredstring
Customer-authored work type name referenced by workstation inputs, outputs, and submitted work.
statesRequiredWorkState[]
Lifecycle states available for work items of this type.
handlingBehaviorOptionalWorkTypeHandlingBehavior[]
Optional CLI routing markers for this work type. Factories used with you run --factory must declare handlingBehavior DEFAULT on exactly one work type.

`WorkTypeHandlingBehavior`

WorkTypeHandlingBehavior

string

Declares how the CLI should route simplified one-shot prompt submissions for this work type. DEFAULT marks the single work type that receives positional prompts from you run --factory.

enum"DEFAULT"

Reconnect, identity, and lifecycle

Client-facing recovery contracts for the canonical session event stream. Does not open a live Factory connection or re-implement the API OpenAPI UI.

Reconnect cursors

Canonical session stream /factory-sessions/{session_id}/events (getEventsBySessionId).

When both after_event_id and after_sequence are present, after_event_id wins.

For session-scoped streams, after_sequence prefers FactoryEvent.context.sessionSequence when that field is present; otherwise it falls back to FactoryEvent.context.sequence. Omitting both cursors starts replay from the beginning of the session's currently retained history.

after_event_idquery · string · optional
Session-scoped reconnect cursor identifying the last acknowledged FactoryEvent.id. The stream replays only events recorded after this stable event identifier. When both after_event_id and after_sequence are present on GET /factory-sessions/{session_id}/events, after_event_id wins.
after_sequencequery · integer · optional
Session-scoped reconnect cursor identifying the last acknowledged ordering point. Session-scoped FactoryEvent streams prefer FactoryEvent.context.sessionSequence when present and otherwise fall back to FactoryEvent.context.sequence. When both after_event_id and after_sequence are present on GET /factory-sessions/{session_id}/events, after_event_id wins. Cursors that no longer match the retained history boundary surface as cursor_stale on JSON reconnect probes or invalid-cursor 400 responses on SSE open.

Identity handshake

Compare X-Factory-Session-* handshake headers with the latest sync-preflight or session-read identity set before reusing a persisted reconnect cursor. A changed streamGenerationId / X-Factory-Session-Stream-Generation-Id invalidates prior cursors even when factorySessionId is unchanged.

X-Factory-Session-Backend-Scope-Id
Stable backend scope identifier for the current live Factory Session event history. Compare this handshake header with session-sync or preflight `backendScopeId` values before reusing reconnect cursors or stream-derived projections.
X-Factory-Session-Logical-Session-Key-Id
Stable logical session key for the resolved Factory Session target within the current backend scope. Compare this handshake header with session-sync or preflight `logicalSessionKeyId` values before reusing reconnect cursors or stream-derived projections.
X-Factory-Session-Factory-Session-Id
Resolved UUID Factory Session identifier for the current live event history. Compare this handshake header with session-sync or preflight `factorySessionId` values before reusing reconnect cursors or stream-derived projections.
X-Factory-Session-Stream-Generation-Id
Opaque invalidation token for the current live Factory Session event history. Compare this handshake header with session-sync or preflight `streamGenerationID` values before reusing reconnect cursors or stream-derived projections.

A changed X-Factory-Session-Stream-Generation-Id means the current stream generation invalidates prior cursors even when the factory session id is unchanged.

Stream lifecycle

Retained-history catch-up, live continuation, keepalive waiting, gap behavior, and stale-cursor recovery for event-stream clients.

Retained history then live: The server sends retained history first in ascending tick order, then continues on the same connection with live FactoryEvent records.
Keepalive waiting state: Successful SSE responses use Connection keep-alive. Idle periods while waiting for new canonical events are normal waiting state, not terminal stream completion, unless the HTTP connection closes.
Gap behavior (STREAM_GAP): On the ephemeral response-events stream, when a cursor predates retained history the first emitted record is STREAM_GAP and describes the lost range rather than silently skipping events.
Stale-cursor recovery: Cursors that no longer match the retained history boundary return typed invalid-cursor handling (400 on SSE open, CURSOR_STALE on the JSON reconnect probe) rather than silently skipping events.

JSON reconnect probe

Same route as the canonical SSE open (/factory-sessions/{session_id}/events). Request Accept: application/json to receive FactorySessionEventStreamRecovery instead of text/event-stream.

When Accept includes application/json, the canonical session events route acts as a reconnect probe and returns FactorySessionEventStreamRecovery instead of opening Server-Sent Events. CURSOR_STALE tells clients to retry with omitAfterEventId and omitAfterSequence set. UNKNOWN_SESSION means the selector does not resolve to a live or durable session and never falls back to the default session. STREAM_READY means the probe succeeded and the client may open the SSE stream.

Recovery outcomes

CURSOR_STALE
INTERNAL_ERROR
STREAM_READY
UNKNOWN_SESSION

Retry guidance fields

omitAfterEventId — True when the next reconnect must omit after_event_id and replay from the start of the session stream.
omitAfterSequence — True when the next reconnect must omit after_sequence and replay from the start of the session stream.

Dual-Accept / HTTP transport ownership (handshake response wiring, status codes, and the full OpenAPI operation UI) remains on the API operation page. See API transport summary.

Static SSE frame and reconnect examples

Copyable wire shapes for id: / event: / data: frames and reconnect usage. Examples never open a live Factory connection, EventSource, or proxy route.

FactoryEvent SSE frame

Illustrative static fixturetext

Illustrative text/event-stream frame shape for the canonical session stream. The data body uses real envelope field names; nested values are placeholders — decode full payloads from the FactoryEvent catalog.

id: <decimal-or-stable-event-id>
event: FactoryEvent
data: {"schemaVersion":"agent-factory.event.v1","id":"<event-id>","type":"RUN_REQUEST","context":{"…":"see FactoryEvent catalog"},"payload":{"…":"see payload variant for type"}}

SSE keepalive comment

Illustrative static fixturetext

Illustrative keepalive comment line. Idle periods are normal waiting state, not terminal stream completion, unless the HTTP connection closes.

: keepalive

Canonical SSE reconnect request

Illustrative static fixturehttp

Illustrative reconnect request for the canonical session stream. Query cursor names and identity handshake headers match the documented contracts; values are placeholders.

GET /factory-sessions/<session-id>/events?after_event_id=<last-acknowledged-id> HTTP/1.1
Accept: text/event-stream
Connection: keep-alive
X-Factory-Session-Backend-Scope-Id: <compare-with-preflight-value>
X-Factory-Session-Logical-Session-Key-Id: <compare-with-preflight-value>
X-Factory-Session-Factory-Session-Id: <compare-with-preflight-value>
X-Factory-Session-Stream-Generation-Id: <compare-with-preflight-value>

# Cursor precedence: when both after_event_id and after_sequence are present, after_event_id wins.
# Compare handshake response headers before reusing a persisted cursor.
# This is a static example — docs never open EventSource or fetch a Factory host.

JSON reconnect-probe response

OpenAPI authored examplejson

Authored OpenAPI example for FactorySessionEventStreamRecovery on Accept: application/json. Dual-Accept HTTP transport ownership remains on the API operation page.

{
  "factorySessionId": "session-alpha",
  "outcome": "CURSOR_STALE",
  "retry": {
    "omitAfterEventId": true,
    "omitAfterSequence": true
  }
}

Events

Event Corpus

Fields

FactoryEventType (envelope.type)

FactoryEventContext (envelope.context)

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Fields

Kind (FactoryResponseEventKind)

Phase (FactoryResponseEventPhase)

FactoryEventType `(envelope.type)`

FactoryEventContext `(envelope.context)`

Kind `(FactoryResponseEventKind)`

Phase `(FactoryResponseEventPhase)`