Factory Sessions

Discover, inspect, and control a live Factory Session, including identity, lifecycle, and its relationship to a loaded Factory.

Relationship To A Factory

Every live Factory Session loads one Factory. The live FactoryName fragment is the named Factory identity that session resolves. Teaching embeds show that identity shape from the live Factory schema. Exhaustive FactorySession, Dispatch, artifact, and event contracts live on the full schema, API, and events reference pages rather than on this surface.

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

Teaching embeds show the live FactoryName fragment a session resolves. Full FactorySession, Dispatch, artifact, and event contracts stay on the schema, API, and events reference pages.

Discover Sessions

Session list is the primary liveness check on a running host. Use it to confirm a Factory Session is accepting work before you submit or inspect. An empty list means the host responded but no live session is registered yet. A connection failure means nothing is listening on that host and port—start or attach a factory before retrying.

List live sessions on the default local host:

you session list

If the list is empty or the host is unreachable, no live session is accepting work on that host—do not submit yet.

Inspect A Session

Session show reads one live Factory Session projection by session id, including identity and runtime fields for that session. Each live session owns its own runtime state—loaded factory, work, and relative paths. When more than one session exists, submit and work commands must target the intended session id rather than assuming the default.

Inspect one live session by id:

you session show <session-id>

Replace <session-id> with a SESSION ID from session list. On single-session local hosts the default compatibility session is often ~default.

Pause And Resume

Pause and resume control one live Factory Session without dropping buffered work. Pause stops automatic progression while the host can still accept inbound submissions; resume restarts processing for that same session id. Apply the control to the intended session, then confirm the outcome by re-reading session status for that same session id.

Pause one live session by id:

you session pause <session-id>

Resume the same paused session:

you session resume <session-id>

After pause or resume, confirm the outcome with you session show <session-id> (or the matching durable status read) for that same session id before assuming the control took effect.

Durable JavaScript Session

Durable JavaScript runs are still Factory Sessions. Dynamic workflow is shorthand for a JavaScript orchestrator-backed session—not a separate runtime object. Use a bounded path: validate source without creating a session, start one durable Factory Session, then read status and result for that same session id. Shared inspection nouns—Dispatch, FactoryArtifact, and FactoryEvent—belong to that same Factory Session id across CLI and related surfaces.

Validate JavaScript workflow source without creating a session:

you workflow validate --kind WORKFLOW_NAME --value <workflow-name>

Start one durable Factory Session asynchronously:

you workflow start --request-id <request-id> --workflow <workflow-name>

Read lifecycle status and progress for that same session id:

you workflow status <session-id>

Read the final or partial result for that same session id:

you workflow result <session-id>

Dispatch, FactoryArtifact, and FactoryEvent records for child work all point back to the same Factory Session id returned at start. Keep validate → start → status/result on one session; MCP host setup and full dynamic-workflow authoring stay on sibling pages.

How To Use

Confirm a live session with session list before submitting work. Inspect one session with session show when you need its identity and runtime projection. Apply pause or resume for that same session id when you need lifecycle control, then re-read status to confirm the outcome. For durable JavaScript work, validate source without creating a session, start one durable Factory Session, then read status and result for that same session id. Open the CLI docs for the broader command matrix, submitting work for batch schema, factories dynamic workflows for JavaScript orchestrator configuration, factories configuration for factory.json topology, or the Cursor dynamic workflows guide when you need Model Context Protocol (MCP) host setup. Exhaustive FactorySession API and event inventories stay on the API and events reference pages.

Limits And Assumptions

This page is a web Factory Session reference for identity, discovery, inspect, lifecycle, Factory relationship, and durable overview. It is not a full CLI flag dump, not a sync of packaged you docs, not Model Context Protocol (MCP) host setup, not dynamic-workflow authoring, not submitting-work batch schema, and not the OpenAPI, schema, or events reference. Exhaustive FactorySession, Dispatch, artifact, and event inventories stay on the schema, API, and events reference pages linked from the Factory relationship section.