YOU

Events

Reference for the factory event stream.

This is a reference for the factory event stream. Every event a session emits is a FactoryEvent: one shared envelope, and a payload chosen by the event type. The lifecycle below lists those types in the order a session emits them — the run opens, the factory declares its structure, work is created, a workstation dispatches it, a worker executes, the orchestrator advances, artifacts land — and each type links to its payload.

Event lifecycle

Every published FactoryEvent type, in the order one session emits them. Each type links to its payload below.

  1. Session

    The outer lifecycle of one run: the request that opens it, the pause and resume controls that interrupt it, the result as it is revised, and the response that closes it.

    1. RUN_REQUEST
    2. SESSION_STARTED
    3. SESSION_LIFECYCLE_CONTROL
    4. SESSION_PAUSED
    5. SESSION_RESUMED
    6. SESSION_RESULT_UPDATED
    7. SESSION_COMPLETED
    8. RUN_RESPONSE

  2. Factory structure

    What the factory is, declared at session start and amended while the session runs — the topology a graph is drawn from.

    1. INITIAL_STRUCTURE_REQUEST
    2. FACTORY_CHANGE
    3. RELATIONSHIP_CHANGE_REQUEST
    4. FACTORY_STATE_RESPONSE

  3. Work

    Work entering the factory and moving between the states its work type declares.

    1. WORK_REQUEST
    2. WORK_STATE_CHANGE

  4. Workstation dispatch

    A workstation handing work to a worker: the request, the queue it waits in, the worker session it binds to, and the outcome — including the interruption and reconciliation paths.

    1. DISPATCH_REQUEST
    2. DISPATCH_QUEUED
    3. DISPATCH_WORKER_SESSION_ASSOCIATION
    4. DISPATCH_INTERRUPTED
    5. DISPATCH_RECONCILED
    6. DISPATCH_RESPONSE

  5. Worker execution

    What a worker does once dispatched: model and inference round trips, script execution, and the result of a child agent run.

    1. MODEL_REQUEST
    2. MODEL_RESPONSE
    3. INFERENCE_REQUEST
    4. INFERENCE_RESPONSE
    5. SCRIPT_REQUEST
    6. SCRIPT_RESPONSE
    7. AGENT_RUN_RESPONSE

  6. Orchestrator

    How the run advances between phases and where it checkpoints, for both the Petri-net default and the JavaScript orchestrator.

    1. ORCHESTRATOR_PHASE_CHANGED
    2. ORCHESTRATOR_CHECKPOINT_WRITTEN
    3. JAVASCRIPT_PHASE_CHANGE
    4. JAVASCRIPT_CHECKPOINT_REF

  7. Artifacts

    Durable output attached to the run. Anything the stages above did not claim is listed here.

    1. ARTIFACT_CREATED

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
  • contextRequiredFactoryEventContext
  • 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" | "DISPATCH_WORKER_SESSION_ASSOCIATION" | "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.

  • 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.

Session

The outer lifecycle of one run: the request that opens it, the pause and resume controls that interrupt it, the result as it is revised, and the response that closes it.

RUN_REQUEST

#RUN_REQUEST

Payload RunRequestEventPayload

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

SESSION_STARTED

#SESSION_STARTED

Payload SessionStartedEventPayload

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.

SESSION_LIFECYCLE_CONTROL

#SESSION_LIFECYCLE_CONTROL

Payload SessionLifecycleControlEventPayload

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

SESSION_PAUSED

#SESSION_PAUSED

Payload SessionPausedEventPayload

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.

  • pausedAtRequiredstringformat: date-time

    When the Factory Session entered PAUSED.

SESSION_RESUMED

#SESSION_RESUMED

Payload SessionResumedEventPayload

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.

  • resumedAtRequiredstringformat: date-time

    When the Factory Session returned to RUNNING.

SESSION_RESULT_UPDATED

#SESSION_RESULT_UPDATED

Payload SessionResultUpdatedEventPayload

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
  • artifactIdsOptionalarray

    Artifact identifiers associated with this result update.

  • resultSummaryOptionalWorkContent

    Bounded customer-visible result summary without raw prompts or secrets.

SESSION_COMPLETED

#SESSION_COMPLETED

Payload SessionCompletedEventPayload

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
  • completedAtRequiredstringformat: date-time

    When durable session execution reached a terminal state.

  • durationMillisOptionalintegerformat: int64

    Total session execution duration in milliseconds.

  • resultStatusOptionalFactoryEventSessionResultStatus
  • artifactIdsOptionalarray

    Artifact identifiers associated with the terminal session outcome.

  • dispatchCountsOptionalFactorySessionJavaScriptChildDispatchCounts

    Dispatch queue, running, and completed counts at terminal completion.

  • failureDetailOptionalFailureDetail

    Canonical failure details when the session completed unsuccessfully.

RUN_RESPONSE

#RUN_RESPONSE

Payload RunResponseEventPayload

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

Factory structure

What the factory is, declared at session start and amended while the session runs — the topology a graph is drawn from.

INITIAL_STRUCTURE_REQUEST

#INITIAL_STRUCTURE_REQUEST

Payload InitialStructureRequestEventPayload

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

FACTORY_CHANGE

#FACTORY_CHANGE

Payload FactoryChangeEventPayload

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

RELATIONSHIP_CHANGE_REQUEST

#RELATIONSHIP_CHANGE_REQUEST

Payload RelationshipChangeRequestEventPayload

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

FACTORY_STATE_RESPONSE

#FACTORY_STATE_RESPONSE

Payload FactoryStateResponseEventPayload

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

Work

Work entering the factory and moving between the states its work type declares.

WORK_REQUEST

#WORK_REQUEST

Payload WorkRequestEventPayload

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

WORK_STATE_CHANGE

#WORK_STATE_CHANGE

Payload WorkStateChangeEventPayload

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
  • triggerWorkIdOptionalstring

    Optional work identifier that triggered a cascade move.

  • reasonOptionalstring

    Optional human-readable reason for the move.

Workstation dispatch

A workstation handing work to a worker: the request, the queue it waits in, the worker session it binds to, and the outcome — including the interruption and reconciliation paths.

DISPATCH_REQUEST

#DISPATCH_REQUEST

Payload DispatchRequestEventPayload

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

DISPATCH_QUEUED

#DISPATCH_QUEUED

Payload DispatchQueuedEventPayload

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
  • 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.

DISPATCH_WORKER_SESSION_ASSOCIATION

#DISPATCH_WORKER_SESSION_ASSOCIATION

Payload DispatchWorkerSessionAssociationEventPayload

DispatchWorkerSessionAssociationEventPayload example

Corpus-constructed examplejson

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

{
  "workerSessionId": "example-"
}

DispatchWorkerSessionAssociationEventPayload

object

Canonical association between one Factory dispatch and the Worker Session allocated to execute it. Dispatch identity remains authoritative in FactoryEvent.context.dispatchId and is not repeated in this payload.

  • additionalPropertiesfalse (closed)

Fields

  • workerSessionIdRequiredstring

    Non-empty Worker Session identity allocated for the dispatch.

    • minLength1

DISPATCH_INTERRUPTED

#DISPATCH_INTERRUPTED

Payload DispatchInterruptedEventPayload

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
  • interruptedAtRequiredstringformat: date-time

    When the interruption was observed.

  • retryPlannedRequiredboolean

    Whether a retry dispatch is planned.

  • providerSessionRefOptionalLoadableProviderSessionRef

    Related provider-session reference when applicable.

  • checkpointRefOptionalFactorySessionJavaScriptCheckpointRef

    Related checkpoint reference when applicable.

DISPATCH_RECONCILED

#DISPATCH_RECONCILED

Payload DispatchReconciledEventPayload

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
  • reconciliationSourceRequiredDispatchReconciliationSource
  • replayedRequiredboolean

    Whether reconciliation facts were emitted during stream replay.

  • usageOptionalFactoryDispatchUsage

    Usage summary after reconciliation when available.

  • resultArtifactRefOptionalFactoryArtifactRef

    Result artifact reference without raw artifact bodies.

  • artifactIdsOptionalarray

    Artifact identifiers produced or updated by reconciliation.

  • failureDetailOptionalFailureDetail

    Canonical failure details when reconciliation failed.

DISPATCH_RESPONSE

#DISPATCH_RESPONSE

Payload DispatchResponseEventPayload

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
  • outputOptionalstring
  • errorOptionalstring
  • feedbackOptionalstring
  • selectedClassificationLabelOptionalstring
  • failureDetailOptionalFailureDetail
  • providerFailureOptionalProviderFailureMetadata
  • metricsOptionalWorkMetrics
  • durationMillisOptionalintegerformat: int64
  • outputWorkOptionalWork[]
  • outputResourcesOptionalResource[]
  • metadataOptionalStringMap

Worker execution

What a worker does once dispatched: model and inference round trips, script execution, and the result of a child agent run.

MODEL_REQUEST

#MODEL_REQUEST

Payload ModelRequestEventPayload

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.

MODEL_RESPONSE

#MODEL_RESPONSE

Payload ModelResponseEventPayload

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
  • 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
  • diagnosticsOptionalSafeWorkDiagnostics
  • providerSessionOptionalProviderSessionMetadata
  • failureDetailOptionalFailureDetail

INFERENCE_REQUEST

#INFERENCE_REQUEST

Payload InferenceRequestEventPayload

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.

INFERENCE_RESPONSE

#INFERENCE_RESPONSE

Payload InferenceResponseEventPayload

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
  • responseOptionalstring

    Provider response text when present.

  • durationMillisRequiredintegerformat: int64

    Provider call duration in milliseconds.

    • minimum0
  • providerSessionOptionalProviderSessionMetadata
  • diagnosticsOptionalSafeWorkDiagnostics
  • exitCodeOptionalinteger

    Process exit code when the provider failure exposes one.

  • failureDetailOptionalFailureDetail

SCRIPT_REQUEST

#SCRIPT_REQUEST

Payload ScriptRequestEventPayload

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.

SCRIPT_RESPONSE

#SCRIPT_RESPONSE

Payload ScriptResponseEventPayload

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
  • 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

AGENT_RUN_RESPONSE

#AGENT_RUN_RESPONSE

Payload AgentRunResponseEventPayload

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
  • durationMillisRequiredintegerformat: int64

    Agent-loop execution duration in milliseconds.

    • minimum0
  • diagnosticsOptionalSafeWorkDiagnostics

Orchestrator

How the run advances between phases and where it checkpoints, for both the Petri-net default and the JavaScript orchestrator.

ORCHESTRATOR_PHASE_CHANGED

#ORCHESTRATOR_PHASE_CHANGED

Payload OrchestratorPhaseChangedEventPayload

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
  • 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.

ORCHESTRATOR_CHECKPOINT_WRITTEN

#ORCHESTRATOR_CHECKPOINT_WRITTEN

Payload OrchestratorCheckpointWrittenEventPayload

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.

  • resumabilityStatusRequiredCheckpointResumabilityStatus
  • warningsOptionalFactoryDispatchWarning[]

    Customer-visible checkpoint warnings.

JAVASCRIPT_PHASE_CHANGE

#JAVASCRIPT_PHASE_CHANGE

Payload JavaScriptPhaseChangeEventPayload

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

JAVASCRIPT_CHECKPOINT_REF

#JAVASCRIPT_CHECKPOINT_REF

Payload JavaScriptCheckpointRefEventPayload

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

Artifacts

Durable output attached to the run. Anything the stages above did not claim is listed here.

ARTIFACT_CREATED

#ARTIFACT_CREATED

Payload ArtifactCreatedEventPayload

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
  • capturedAtOptionalstringformat: date-time

    When the artifact payload was captured.

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
  • phaseRequiredFactoryResponseEventPhase
  • provenanceRequiredFactoryResponseEventProvenance
  • payloadRequiredFactoryResponseEventPayload
  • 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

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
  • 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

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

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

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

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
  • runnerSelectionSourceOptionalRunnerSelectionSource

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
  • descriptionOptionalNameValue

    Optional localized customer-facing explanation of this Factory.

  • idOptionalstring

    Factory identifier used as the factory-level template context fallback.

  • runnerOptionalRunnerID

    Default runner selection for the factory when a workstation does not declare its own runner override.

  • factoryDirectoryOptionalstring

    Directory that contained the factory.json used for this serialized runtime config.

  • sourceDirectoryOptionalstring

    Original source directory for record/replay and drift diagnostics.

  • versionOptionalHybridLogicalTimestamp

    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.

  • metadataOptionalStringMap

    Free-form factory-level metadata carried through runtime serialization and replay diagnostics.

  • orchestratorOptionalFactoryOrchestrator

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

  • inputTypesOptionalInputType[]

    Named input kinds accepted by the factory. The default input type is implicit and must not be declared.

  • invocationReturnOptionalInvocationReturn

    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.

  • invocationSignatureOptionalFactoryInvocationSignature

    Optional canonical callable argument contract shared by CLI, API, dashboard, docs, and packaged factories. When omitted, callers use the factory's compatibility invocation behavior.

  • examplesOptionalFactoryInvocationExample[]

    Ordered runnable invocation examples. Canonical Factory documents write examples here; legacy invocationSignature.examples are accepted only by the Factory input compatibility mapper.

  • 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.

  • supportingFilesOptionalResourceManifest

    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.

  • layoutOptionalFactoryLayout

    Optional non-executable graph editor layout metadata keyed by canonical graph node and edge ids.

  • 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

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
  • visibilityRequiredFactoryArtifactVisibility
  • 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

  • typeRequiredFactoryGuardType

    Factory-level guard condition to evaluate before dispatch-ready transitions can proceed.

  • modelProviderRequiredProviderIdentity

    Provider whose inference-throttle history controls this factory-level guard.

  • 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"

FactoryInvocationArguments

FactoryInvocationArguments

object

Structured Factory invocation arguments keyed by parameter name, external name, or alias. Each value is either one string or an ordered array of strings.

  • additionalPropertiestrue (open)

FactoryInvocationExample

FactoryInvocationExample

object

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

  • additionalPropertiesfalse (closed)

Fields

  • nameRequiredstring

    Stable example name.

    • minLength1
  • descriptionRequiredNameValue

    Localized customer-facing explanation of what the example does.

  • argsRequiredFactoryInvocationArguments

    Structured invocation arguments; values are never parsed or executed while loading the Factory.

FactoryInvocationOutputContract

FactoryInvocationOutputContract

object

Customer-facing output hint for a factory invocation signature.

  • additionalPropertiesfalse (closed)

Fields

  • modeOptionalFactoryInvocationOutputContractMode

    High-level output contract mode exposed to callers.

  • 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.

  • typeHintOptionalFactoryInvocationParameterTypeHint

    String-first hint that guides parsing, docs, and dashboard form selection.

  • valueModeOptionalFactoryInvocationParameterValueMode

    Declares whether the parameter consumes one value, repeated values, variadic values, or file contents.

  • 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

  • kindRequiredFactoryInvocationParameterBindingKind

    Binding kind used to route invocation input into the parameter.

  • 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

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.

  • annotationsOptionalFactoryLayoutAnnotation[]

    Optional inert positioned notes and embedded-raster images that decorate the canvas without becoming graph topology.

  • viewportOptionalFactoryLayoutViewport
  • preferencesOptionalFactoryLayoutPreferences

FactoryLayoutAnnotation

FactoryLayoutAnnotation

object

Inert positioned canvas annotation. Its kind selects either note or image content; annotations never identify graph nodes or edges, and connection-like fields are invalid.

  • additionalPropertiesfalse (closed)

Fields

FactoryLayoutAnnotationKind

FactoryLayoutAnnotationKind

string

The inert annotation content variant.

  • enum"NOTE" | "IMAGE"

FactoryLayoutAnnotationPosition

FactoryLayoutAnnotationPosition

object

Explicit finite annotation position in canvas units. Each coordinate is bounded to keep portable layout metadata safe to render.

  • additionalPropertiesfalse (closed)

Fields

  • xRequirednumber

    Horizontal canvas coordinate between -100,000 and 100,000 inclusive.

    • minimum-100000
    • maximum100000
  • yRequirednumber

    Vertical canvas coordinate between -100,000 and 100,000 inclusive.

    • minimum-100000
    • maximum100000

FactoryLayoutAnnotationSize

FactoryLayoutAnnotationSize

object

Optional finite annotation dimensions in canvas units. Image annotations require this size; note annotations may omit it.

  • additionalPropertiesfalse (closed)

Fields

  • widthRequirednumber

    Positive authored width no greater than 10,000 canvas units.

    • minimum0
    • maximum10000
  • heightRequirednumber

    Positive authored height no greater than 10,000 canvas units.

    • minimum0
    • maximum10000

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

FactoryLayoutEmptyState

FactoryLayoutEmptyState

object

Inert presentation content for one canonical topology node when it has no live activity. It is definition metadata only and does not create events or runtime behavior.

  • additionalPropertiesfalse (closed)

Fields

  • textOptionalstring

    Literal empty-state text. It is not rendered as HTML or Markdown.

    • pattern\S
    • minLength1
    • maxLength500
  • imageOptionalFactoryLayoutImage

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
  • 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.

FactoryLayoutImage

FactoryLayoutImage

object

Inert embedded-raster image content with required alternative text.

  • additionalPropertiesfalse (closed)

Fields

  • sourceRequiredFactoryLayoutImageSource
  • alternativeTextRequiredstring

    Literal alternative text for the embedded image.

    • pattern\S
    • minLength1
    • maxLength500

FactoryLayoutImageSource

FactoryLayoutImageSource

object

Extensible discriminated image-source shape. Version 1 supports only embedded raster data.

  • additionalPropertiesfalse (closed)

Fields

  • kindRequiredstring

    Source variant discriminator. EMBEDDED carries portable base64 raster data.

    • enum"EMBEDDED"
  • mediaTypeRequiredstring

    Declared media type for the embedded raster.

    • enum"image/png" | "image/jpeg" | "image/webp"
  • dataRequiredstringformat: byte

    Strict padded base64 payload for the embedded raster source, limited to 2 MiB after decoding.

    • minLength4
    • maxLength2796204

FactoryLayoutNode

FactoryLayoutNode

object

Portable graph node layout keyed by canonical graph node id.

  • additionalPropertiesfalse (closed)

Fields

FactoryLayoutNote

FactoryLayoutNote

object

Literal plain-text note content. Line breaks are preserved as authored text and are not interpreted as Markdown or HTML.

  • additionalPropertiesfalse (closed)

Fields

  • titleOptionalstring

    Optional literal plain-text note title.

    • maxLength160
  • bodyRequiredstring

    Required literal plain-text note body.

    • pattern\S
    • minLength1
    • maxLength4000
  • toneRequiredFactoryLayoutNoteTone

FactoryLayoutNoteTone

FactoryLayoutNoteTone

string

Presentation-only tone for a note annotation.

  • enum"NEUTRAL" | "ACCENT" | "INFO" | "SUCCESS" | "WARNING" | "DANGER"

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

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.

  • inlineSourceOptionalFactoryOrchestratorJavaScriptInlineSource

    Inline workflow source when the factory carries source text directly.

  • sourceHashOptionalstring

    Optional content hash for the resolved workflow source.

  • entrypointOptionalstring

    Optional exported entrypoint or phase name used to start the workflow.

  • metadataOptionalStringMap

    Free-form JavaScript orchestrator metadata for authoring and diagnostics.

  • 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

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

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

FactoryResponseEventResourceRefContentBlock

FactoryResponseEventResourceRefContentBlock

object

Factory resource reference content block.

  • additionalPropertiesfalse (closed)

Fields

FactoryResponseEventStructuredOutputContentBlock

FactoryResponseEventStructuredOutputContentBlock

object

Structured JSON output content block.

  • additionalPropertiesfalse (closed)

Fields

FactoryResponseEventTextContentBlock

FactoryResponseEventTextContentBlock

object

Inline text content block.

  • additionalPropertiesfalse (closed)

Fields

FactoryResponseEventToolRequestContentBlock

FactoryResponseEventToolRequestContentBlock

object

Tool invocation request content block with bounded argument summary.

  • additionalPropertiesfalse (closed)

Fields

  • kindRequiredFactoryResponseEventContentBlockKind
    • enum"TOOL_REQUEST"
  • 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.

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
  • dispatchKindRequiredFactoryDispatchKind
  • 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.

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
  • 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.

  • latestDispatchOptionalFactoryStopDispatchSummary
  • 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
  • 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.

  • mappingOptionalHostedLinearWorkerMapping

    Deterministic mapping fields for canonical work submission generation.

  • claimOptionalHostedLinearWorkerClaim

    Optional claim-related configuration that v1 hosted Linear polling allows.

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

  • typeRequiredInputGuardType

    Guard condition to evaluate for this input-level attachment.

  • workstationOptionalstring

    For `VISIT_COUNT` guards, the workstation whose visits are counted.

  • maxVisitsOptionalinteger

    For `VISIT_COUNT` guards, the visit threshold.

    • minimum1
  • matchConfigOptionalGuardMatchConfig

    For `MATCHES_FIELDS` guards, the field-selector configuration used to compare candidate inputs.

  • 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

InvocationDiagnostic

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

  • policyRequiredInvocationReturnPolicy

    Return selection policy for this factory.

  • 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

ModelOperation

ModelOperation

object

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

  • additionalPropertiesfalse (closed)

Fields

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
  • 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.

NameValue

NameValue

object

A customer-facing value with a required base fallback and optional exact locale overrides. Locale tags must use their canonical BCP 47 spelling.

  • additionalPropertiesfalse (closed)

Fields

  • typeRequiredstring

    Discriminator for localized customer-facing metadata.

    • enum"LOCALIZABLE_ASSET"
  • valueRequiredstring

    Required base value returned when no exact locale override exists.

    • minLength1
  • localesOptionalarray

    Canonical BCP 47 locales for which the base value was authored.

    • uniqueItemstrue
  • valuesOptionalobject

    Exact canonical BCP 47 locale tags mapped to localized overrides.

    • additionalPropertiestrue (open)
  • idOptionalstring

    Optional stable metadata identifier; consumers must not render it as display copy.

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
  • responseMetadataOptionalStringMap

ProviderFailureMetadata

ProviderIdentity

ProviderIdentity

string

Open provider identity used by authored modelProvider fields. Extension identities use lowercase letters and digits separated by dots or hyphens. Built-in identities and documented legacy aliases remain accepted compatibility spellings. For example, `customer.provider` is a valid extension identity.

  • pattern^(?:[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*|ANTIGRAVITY|ANTHROPIC|CLAUDE|CODEX|OPENAI)$
  • minLength1
  • maxLength128

ProviderSessionMetadata

ProviderSessionMetadata

object
  • additionalPropertiesfalse (closed)

Fields

  • providerOptionalstring
  • kindOptionalstring
  • idOptionalstring

ReasoningEffort

ReasoningEffort

string

Optional provider-neutral reasoning effort. Surrounding whitespace and letter case are normalized. Omit the field to preserve the selected provider and model default. Factory definitions may use an exact invocation-parameter placeholder such as `${executorReasoningEffort}`.

  • pattern^(?:[ - …   - 

  　]*(?:[mM][iI][nN][iI][mM][aA][lL]|[lL][oO][wW]|[mM][eE][dD][iI][uU][mM]|[hH][iI][gG][hH]|[xX][hH][iI][gG][hH]|[mM][aA][xX])?[ - …   - 

  　]*|\$\{[A-Za-z0-9_.-]+\})$

Relation

Relation

object
  • additionalPropertiesfalse (closed)

Fields

  • typeRequiredRelationType
  • 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

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

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.

  • typeOptionalResourceType

    Optional uppercase resource family, such as `MODEL`, `PROVIDER_QUOTA`, or `INVOCATION_SLOT`.

  • 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" | "claude" | "antigravity"

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

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.

  • 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.

  • 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.

  • 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.

WorkAudioContentPart

WorkBinaryContentPart

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

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

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.

  • descriptionOptionalNameValue

    Optional localized customer-facing explanation of this worker.

  • typeOptionalWorkerType

    Worker implementation family to instantiate for this definition.

  • providerOptionalHostedWorkerProvider

    Built-in hosted provider identity when this worker uses repository-owned hosted execution.

  • modelOptionalstring

    Model identifier to request from the configured model provider when this worker uses model execution.

  • modelProviderOptionaloneOf

    Canonical provider identity used for model routing and provider diagnostics, or an exact invocation-parameter placeholder such as `${modelProvider}`. For `executorProvider: ACP`, this names the configured ACP integration, such as `cursor-acp`. Extension identities use lowercase standardized syntax; built-in values such as `CLAUDE` and `CODEX` remain compatibility conveniences.

  • reasoningEffortOptionalReasoningEffort
  • modelLocalityOptionalWorkerModelLocality

    Provider locality for this model capability declaration. Use `LOCAL` for embedded or host-managed inference and `CLOUD` for remote provider execution.

  • executorProviderOptionalWorkerProvider

    Execution mechanism. Use `ACP` for ACP-backed workers and put the configured integration identity (for example `cursor-acp`) in modelProvider. `SCRIPT_WRAP` remains the command-wrapper compatibility value; legacy named executor identities remain accepted during migration.

  • 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.

  • authOptionalHostedWorkerAuth

    Hosted-worker authentication contract. V1 hosted workers accept only auth.secretRef.

  • linearOptionalHostedLinearWorkerConfig

    Provider-specific configuration for the built-in hosted LINEAR worker.

  • agentToolsOptionalAgentWorkerToolsConfig

    Explicit agent-loop tool policy for AGENT_WORKER definitions. Omit or set policy DISABLED to run agent loops without advertising or executing tools.

  • 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"

WorkerProvider

WorkerProvider

string

Worker execution mechanism. Canonical values are ACP and SCRIPT_WRAP; extensible lowercase identities remain accepted for compatibility with existing factories.

  • pattern^(?:ACP|SCRIPT_WRAP|\$\{[A-Za-z0-9_.-]+\}|[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*)$
  • minLength1
  • maxLength128

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

WorkJsonContentPart

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

  • modeRequiredWorkPropagationMode

    Propagation mode for downstream work payload selection after this workstation succeeds.

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.

  • typeRequiredWorkStateType

    Lifecycle category for this state, such as initial, processing, terminal, or failed.

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.

  • descriptionOptionalNameValue

    Optional localized customer-facing explanation of this workstation.

  • behaviorOptionalWorkstationKind

    Scheduling behavior for this workstation, such as STANDARD, REPEATER, or CRON execution.

  • typeOptionalWorkstationType

    Runtime workstation implementation type, equivalent to the workstation AGENTS.md frontmatter type.

  • operationOptionalModelOperationName

    Uppercase provider-agnostic operation requested by `MODEL_INVOKE` workstations, such as `TTS`.

  • 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.

  • runnerOptionalRunnerID

    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.

  • 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.

  • outcomeFormatOptionalWorkstationOutcomeFormat

    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.

  • limitsOptionalWorkstationLimits

    Retry and execution ceilings applied to this workstation.

  • workPropagationOptionalWorkPropagation

    Optional policy for whether downstream work uses the workstation output payload or preserves the consumed input payload.

  • bodyOptionalstring

    Inline workstation instructions or script body when authored directly in factory config.

  • cronOptionalWorkstationCron

    Cron trigger configuration for workstations whose behavior is CRON.

  • 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.

  • envOptionalStringMap

    Environment variables added to the workstation execution context.

WorkstationCron

WorkstationCron

object

Trigger timing for scheduled workstations. Provide exactly one of a five-field cron schedule or a positive duration in every; Factory validation enforces the exclusive choice.

  • additionalPropertiesfalse (closed)

Fields

  • scheduleOptionalstring

    Standard five-field cron expression used to produce internal time work while the factory service is running.

  • everyOptionalstring

    Positive Go duration interval, such as 30s, 5m, 1h, or 1h30m, used instead of schedule.

  • 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

  • typeRequiredWorkstationGuardType

    Guard condition to evaluate for this workstation-level attachment.

  • workstationOptionalstring

    For `VISIT_COUNT` guards, the workstation whose visits are counted.

  • maxVisitsOptionalinteger

    For `VISIT_COUNT` guards, the fixed visit ceiling.

    • minimum1
  • maxVisitsArgumentOptionalstring

    Optional invocation argument whose positive integer value tightens the fixed visit ceiling.

  • matchConfigOptionalGuardMatchConfig

    For `MATCHES_FIELDS` guards, the field-selector configuration used to compare candidate inputs.

  • 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.

  • maxGeneratedWorkItemsOptionalinteger

    Fixed maximum number of Work items one accepted worker-emitted FACTORY_REQUEST_BATCH may contain.

    • minimum1
  • maxGeneratedWorkItemsArgumentOptionalstring

    Optional invocation argument whose positive integer value tightens the fixed generated-Work ceiling.

  • maxGeneratedWorkItemsArgumentOffsetOptionalinteger

    Offset added to the invocation argument before applying the generated-Work ceiling.

    • minimum0

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.

  • selectorOptionalWorkstationOperationBindingSelector

    Ordered runtime-input selector used before falling back to config or default content.

  • configOptionalWorkContent

    Static authored content bound directly or used as the first fallback when runtime input does not match.

  • defaultContentOptionalWorkContent

    Optional final fallback content when neither runtime input nor config content resolves the slot.

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.

  • typeOptionalModelOperationContentType

    Match a content part by its uppercase public type.

  • 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

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.

  • descriptionOptionalNameValue

    Optional localized customer-facing explanation of this work type.

  • 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"

Event stream operations

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

  • 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.

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
  }
}

On this page

Event lifecycleFactoryEvent envelopeSessionRUN_REQUESTSESSION_STARTEDSESSION_LIFECYCLE_CONTROLSESSION_PAUSEDSESSION_RESUMEDSESSION_RESULT_UPDATEDSESSION_COMPLETEDRUN_RESPONSEFactory structureINITIAL_STRUCTURE_REQUESTFACTORY_CHANGERELATIONSHIP_CHANGE_REQUESTFACTORY_STATE_RESPONSEWorkWORK_REQUESTWORK_STATE_CHANGEWorkstation dispatchDISPATCH_REQUESTDISPATCH_QUEUEDDISPATCH_WORKER_SESSION_ASSOCIATIONDISPATCH_INTERRUPTEDDISPATCH_RECONCILEDDISPATCH_RESPONSEWorker executionMODEL_REQUESTMODEL_RESPONSEINFERENCE_REQUESTINFERENCE_RESPONSESCRIPT_REQUESTSCRIPT_RESPONSEAGENT_RUN_RESPONSEOrchestratorORCHESTRATOR_PHASE_CHANGEDORCHESTRATOR_CHECKPOINT_WRITTENJAVASCRIPT_PHASE_CHANGEJAVASCRIPT_CHECKPOINT_REFArtifactsARTIFACT_CREATED