@you-agent-factory/client 0.0.2 → 0.0.6

package/dist/contracts.d.ts

@@ -19,6 +19,7 @@ export declare const FACTORY_EVENT_TYPES: {
     readonly FactoryEventTypeWorkRequest: "WORK_REQUEST";
     readonly FactoryEventTypeRelationshipChangeRequest: "RELATIONSHIP_CHANGE_REQUEST";
     readonly FactoryEventTypeDispatchRequest: "DISPATCH_REQUEST";
+    readonly FactoryEventTypeDispatchWorkerSessionAssociation: "DISPATCH_WORKER_SESSION_ASSOCIATION";
     readonly FactoryEventTypeModelRequest: "MODEL_REQUEST";
     readonly FactoryEventTypeModelResponse: "MODEL_RESPONSE";
     readonly FactoryEventTypeInferenceRequest: "INFERENCE_REQUEST";

package/dist/generated/factory-event.schema.json

@@ -515,10 +515,40 @@
             ],
             "type": "object"
         },
+        "DispatchWorkerSessionAssociationEventPayload": {
+            "additionalProperties": false,
+            "description": "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.",
+            "properties": {
+                "workerSessionId": {
+                    "description": "Non-empty Worker Session identity allocated for the dispatch.",
+                    "minLength": 1,
+                    "type": "string"
+                }
+            },
+            "required": [
+                "workerSessionId"
+            ],
+            "type": "object"
+        },
         "Factory": {
             "additionalProperties": false,
             "description": "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.",
             "properties": {
+                "description": {
+                    "allOf": [
+                        {
+                            "$ref": "#/$defs/NameValue"
+                        }
+                    ],
+                    "description": "Optional localized customer-facing explanation of this Factory."
+                },
+                "examples": {
+                    "description": "Ordered runnable invocation examples. Canonical Factory documents write examples here; legacy invocationSignature.examples are accepted only by the Factory input compatibility mapper.",
+                    "items": {
+                        "$ref": "#/$defs/FactoryInvocationExample"
+                    },
+                    "type": "array"
+                },
                 "factoryDirectory": {
                     "description": "Directory that contained the factory.json used for this serialized runtime config.",
                     "type": "string"
@@ -1002,6 +1032,7 @@
                 "WORK_REQUEST",
                 "RELATIONSHIP_CHANGE_REQUEST",
                 "DISPATCH_REQUEST",
+                "DISPATCH_WORKER_SESSION_ASSOCIATION",
                 "MODEL_REQUEST",
                 "MODEL_RESPONSE",
                 "INFERENCE_REQUEST",
@@ -1041,7 +1072,7 @@
                 "modelProvider": {
                     "allOf": [
                         {
-                            "$ref": "#/$defs/WorkerModelProvider"
+                            "$ref": "#/$defs/ProviderIdentity"
                         }
                     ],
                     "description": "Provider whose inference-throttle history controls this factory-level guard."
@@ -1073,32 +1104,53 @@
             ],
             "type": "string"
         },
+        "FactoryInvocationArguments": {
+            "additionalProperties": {
+                "oneOf": [
+                    {
+                        "type": "string"
+                    },
+                    {
+                        "items": {
+                            "type": "string"
+                        },
+                        "type": "array"
+                    }
+                ]
+            },
+            "description": "Structured Factory invocation arguments keyed by parameter name, external name, or alias. Each value is either one string or an ordered array of strings.",
+            "type": "object"
+        },
         "FactoryInvocationExample": {
             "additionalProperties": false,
             "description": "One example invocation for docs, help, and packaged-factory inspection.",
             "properties": {
-                "argv": {
-                    "description": "CLI-style argument vector rendered after factory selection.",
-                    "items": {
-                        "type": "string"
-                    },
-                    "type": "array"
+                "args": {
+                    "allOf": [
+                        {
+                            "$ref": "#/$defs/FactoryInvocationArguments"
+                        }
+                    ],
+                    "description": "Structured invocation arguments; values are never parsed or executed while loading the Factory."
                 },
                 "description": {
-                    "description": "Customer-facing explanation of what the example does.",
-                    "type": "string"
+                    "allOf": [
+                        {
+                            "$ref": "#/$defs/NameValue"
+                        }
+                    ],
+                    "description": "Localized customer-facing explanation of what the example does."
                 },
                 "name": {
                     "description": "Stable example name.",
-                    "type": "string"
-                },
-                "stdin": {
-                    "description": "Example stdin payload when the signature routes stdin into one parameter.",
+                    "minLength": 1,
                     "type": "string"
                 }
             },
             "required": [
-                "name"
+                "name",
+                "description",
+                "args"
             ],
             "type": "object"
         },
@@ -1279,13 +1331,6 @@
             "additionalProperties": false,
             "description": "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.",
             "properties": {
-                "examples": {
-                    "description": "Example invocations rendered in docs, help, and inspection surfaces.",
-                    "items": {
-                        "$ref": "#/$defs/FactoryInvocationExample"
-                    },
-                    "type": "array"
-                },
                 "outputContract": {
                     "allOf": [
                         {
@@ -2982,6 +3027,9 @@
                     "description": "Worker-declared model locality, such as LOCAL or CLOUD.",
                     "type": "string"
                 },
+                "providerSession": {
+                    "$ref": "#/$defs/ProviderSessionMetadata"
+                },
                 "resourceAcquired": {
                     "description": "Whether the invocation acquired the required local model resources.",
                     "type": "boolean"
@@ -3016,6 +3064,49 @@
             ],
             "type": "object"
         },
+        "NameValue": {
+            "additionalProperties": false,
+            "description": "A customer-facing value with a required base fallback and optional exact locale overrides. Locale tags must use their canonical BCP 47 spelling.",
+            "properties": {
+                "id": {
+                    "description": "Optional stable metadata identifier; consumers must not render it as display copy.",
+                    "type": "string"
+                },
+                "locales": {
+                    "description": "Canonical BCP 47 locales for which the base value was authored.",
+                    "items": {
+                        "minLength": 2,
+                        "type": "string"
+                    },
+                    "type": "array",
+                    "uniqueItems": true
+                },
+                "type": {
+                    "description": "Discriminator for localized customer-facing metadata.",
+                    "enum": [
+                        "LOCALIZABLE_ASSET"
+                    ],
+                    "type": "string"
+                },
+                "value": {
+                    "description": "Required base value returned when no exact locale override exists.",
+                    "minLength": 1,
+                    "type": "string"
+                },
+                "values": {
+                    "additionalProperties": {
+                        "type": "string"
+                    },
+                    "description": "Exact canonical BCP 47 locale tags mapped to localized overrides.",
+                    "type": "object"
+                }
+            },
+            "required": [
+                "type",
+                "value"
+            ],
+            "type": "object"
+        },
         "OrchestratorCheckpointWrittenEventPayload": {
             "additionalProperties": false,
             "description": "Orchestrator checkpoint reference recorded on the canonical factory event stream. Checkpoint identity lives in FactoryEvent.context and raw VM bodies remain orchestrator-owned.",
@@ -3131,6 +3222,13 @@
             },
             "type": "object"
         },
+        "ProviderIdentity": {
+            "description": "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.",
+            "maxLength": 128,
+            "minLength": 1,
+            "pattern": "^(?:[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*|ANTIGRAVITY|ANTHROPIC|CLAUDE|CODEX|OPENAI)$",
+            "type": "string"
+        },
         "ProviderSessionMetadata": {
             "additionalProperties": false,
             "properties": {
@@ -3146,6 +3244,11 @@
             },
             "type": "object"
         },
+        "ReasoningEffort": {
+            "description": "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": "^(?:[\t-\r …   - \u2028\u2029  　]*(?:[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])?[\t-\r …   - \u2028\u2029  　]*|\\$\\{[A-Za-z0-9_.-]+\\})$",
+            "type": "string"
+        },
         "Relation": {
             "additionalProperties": false,
             "properties": {
@@ -3409,11 +3512,8 @@
             "description": "Stable built-in runner identifiers supported by factory and workstation runner selection.",
             "enum": [
                 "codex",
-                "gemini",
-                "kiro",
-                "cursor-cli",
-                "opencode",
-                "pi"
+                "claude",
+                "antigravity"
             ],
             "type": "string"
         },
@@ -4328,6 +4428,14 @@
             "additionalProperties": false,
             "description": "A named category of work that can move through the factory. Each work type declares the lifecycle states its work items can occupy.",
             "properties": {
+                "description": {
+                    "allOf": [
+                        {
+                            "$ref": "#/$defs/NameValue"
+                        }
+                    ],
+                    "description": "Optional localized customer-facing explanation of this work type."
+                },
                 "handlingBehavior": {
                     "description": "Optional CLI routing markers for this work type. Factories used with you run --factory must declare handlingBehavior DEFAULT on exactly one work type.",
                     "items": {
@@ -4399,13 +4507,21 @@
                     "description": "Command to execute when this worker runs through a command or script provider.",
                     "type": "string"
                 },
+                "description": {
+                    "allOf": [
+                        {
+                            "$ref": "#/$defs/NameValue"
+                        }
+                    ],
+                    "description": "Optional localized customer-facing explanation of this worker."
+                },
                 "executorProvider": {
                     "allOf": [
                         {
                             "$ref": "#/$defs/WorkerProvider"
                         }
                     ],
-                    "description": "Canonical executor adapter identifier used to select the worker execution provider or wrapper. The current public built-in value is `SCRIPT_WRAP`."
+                    "description": "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."
                 },
                 "id": {
                     "description": "Optional durable public identifier for this worker. When present, graph and layout references should use this id instead of the mutable name.",
@@ -4432,21 +4548,21 @@
                     "description": "Provider locality for this model capability declaration. Use `LOCAL` for embedded or host-managed inference and `CLOUD` for remote provider execution."
                 },
                 "modelProvider": {
-                    "allOf": [
+                    "description": "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.",
+                    "oneOf": [
+                        {
+                            "$ref": "#/$defs/ProviderIdentity"
+                        },
                         {
-                            "$ref": "#/$defs/WorkerModelProvider"
+                            "pattern": "^\\$\\{[A-Za-z0-9_.-]+\\}$",
+                            "type": "string"
                         }
-                    ],
-                    "description": "Canonical model-provider identifier used for model routing and provider diagnostics. Current public built-in values are `CLAUDE` and `CODEX`; the runtime maps them onto the underlying provider command IDs."
+                    ]
                 },
                 "name": {
                     "description": "Worker name referenced by Workstation.worker.",
                     "type": "string"
                 },
-                "openCodeAgent": {
-                    "description": "Optional OpenCode agent profile name for model workers that dispatch through the OpenCode runner. When set, OpenCode dispatches invoke `opencode run --agent \u003cname\u003e`. Discover agent names with `opencode agent list` (see https://opencode.ai/docs/cli/).",
-                    "type": "string"
-                },
                 "operations": {
                     "description": "Provider-agnostic model operations that this worker can execute, including named input and output slots.",
                     "items": {
@@ -4462,6 +4578,9 @@
                     ],
                     "description": "Built-in hosted provider identity when this worker uses repository-owned hosted execution."
                 },
+                "reasoningEffort": {
+                    "$ref": "#/$defs/ReasoningEffort"
+                },
                 "resources": {
                     "description": "Resource capacity this worker requires before it can be dispatched.",
                     "items": {
@@ -4503,25 +4622,11 @@
             ],
             "type": "string"
         },
-        "WorkerModelProvider": {
-            "description": "Canonical model-provider identifiers supported by model workers in factory config.",
-            "enum": [
-                "CLAUDE",
-                "CODEX",
-                "CURSOR",
-                "GEMINI",
-                "KIRO",
-                "OPENCODE",
-                "PI",
-                "AGY"
-            ],
-            "type": "string"
-        },
         "WorkerProvider": {
-            "description": "Concrete worker-provider wrappers supported by the public factory-config contract.",
-            "enum": [
-                "SCRIPT_WRAP"
-            ],
+            "description": "Worker execution mechanism. Canonical values are ACP and SCRIPT_WRAP; extensible lowercase identities remain accepted for compatibility with existing factories.",
+            "maxLength": 128,
+            "minLength": 1,
+            "pattern": "^(?:ACP|SCRIPT_WRAP|\\$\\{[A-Za-z0-9_.-]+\\}|[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*)$",
             "type": "string"
         },
         "WorkerType": {
@@ -4571,6 +4676,14 @@
                     ],
                     "description": "Cron trigger configuration for workstations whose behavior is CRON."
                 },
+                "description": {
+                    "allOf": [
+                        {
+                            "$ref": "#/$defs/NameValue"
+                        }
+                    ],
+                    "description": "Optional localized customer-facing explanation of this workstation."
+                },
                 "env": {
                     "allOf": [
                         {
@@ -4630,10 +4743,6 @@
                     },
                     "type": "array"
                 },
-                "openCodeAgent": {
-                    "description": "Optional OpenCode agent profile override for this workstation. When set, overrides the worker default for OpenCode dispatches and invokes `opencode run --agent \u003cname\u003e`. Discover agent names with `opencode agent list` (see https://opencode.ai/docs/cli/).",
-                    "type": "string"
-                },
                 "operation": {
                     "allOf": [
                         {
@@ -4732,8 +4841,12 @@
         },
         "WorkstationCron": {
             "additionalProperties": false,
-            "description": "Trigger timing for cron workstations. Cron workstations use a schedule expression; interval triggers are not supported.",
+            "description": "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.",
             "properties": {
+                "every": {
+                    "description": "Positive Go duration interval, such as 30s, 5m, 1h, or 1h30m, used instead of schedule.",
+                    "type": "string"
+                },
                 "expiryWindow": {
                     "description": "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.",
                     "type": "string"
@@ -4752,9 +4865,6 @@
                     "type": "boolean"
                 }
             },
-            "required": [
-                "schedule"
-            ],
             "type": "object"
         },
         "WorkstationGuard": {
@@ -4774,10 +4884,14 @@
                     "type": "string"
                 },
                 "maxVisits": {
-                    "description": "For `VISIT_COUNT` guards, the visit threshold.",
+                    "description": "For `VISIT_COUNT` guards, the fixed visit ceiling.",
                     "minimum": 1,
                     "type": "integer"
                 },
+                "maxVisitsArgument": {
+                    "description": "Optional invocation argument whose positive integer value tightens the fixed visit ceiling.",
+                    "type": "string"
+                },
                 "parentInput": {
                     "description": "For parent-aware input guards, the parent workType name from another input in the same workstation.",
                     "type": "string"
@@ -4857,6 +4971,20 @@
                     "description": "Go duration limit for one dispatch attempt before it times out.",
                     "type": "string"
                 },
+                "maxGeneratedWorkItems": {
+                    "description": "Fixed maximum number of Work items one accepted worker-emitted FACTORY_REQUEST_BATCH may contain.",
+                    "minimum": 1,
+                    "type": "integer"
+                },
+                "maxGeneratedWorkItemsArgument": {
+                    "description": "Optional invocation argument whose positive integer value tightens the fixed generated-Work ceiling.",
+                    "type": "string"
+                },
+                "maxGeneratedWorkItemsArgumentOffset": {
+                    "description": "Offset added to the invocation argument before applying the generated-Work ceiling.",
+                    "minimum": 0,
+                    "type": "integer"
+                },
                 "maxRetries": {
                     "description": "Maximum number of retry attempts after a failed dispatch before the workstation gives up.",
                     "type": "integer"
@@ -4964,6 +5092,7 @@
             "DISPATCH_RECONCILED": "#/$defs/DispatchReconciledEventPayload",
             "DISPATCH_REQUEST": "#/$defs/DispatchRequestEventPayload",
             "DISPATCH_RESPONSE": "#/$defs/DispatchResponseEventPayload",
+            "DISPATCH_WORKER_SESSION_ASSOCIATION": "#/$defs/DispatchWorkerSessionAssociationEventPayload",
             "FACTORY_CHANGE": "#/$defs/FactoryChangeEventPayload",
             "FACTORY_STATE_RESPONSE": "#/$defs/FactoryStateResponseEventPayload",
             "INFERENCE_REQUEST": "#/$defs/InferenceRequestEventPayload",
@@ -4991,6 +5120,35 @@
         },
         "propertyName": "type"
     },
+    "not": {
+        "properties": {
+            "context": {
+                "not": {
+                    "properties": {
+                        "dispatchId": {
+                            "minLength": 1,
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "dispatchId"
+                    ],
+                    "type": "object"
+                }
+            },
+            "type": {
+                "enum": [
+                    "DISPATCH_WORKER_SESSION_ASSOCIATION"
+                ],
+                "type": "string"
+            }
+        },
+        "required": [
+            "type",
+            "context"
+        ],
+        "type": "object"
+    },
     "oneOf": [
         {
             "properties": {
@@ -5082,6 +5240,21 @@
             ],
             "type": "object"
         },
+        {
+            "properties": {
+                "payload": {
+                    "$ref": "#/$defs/DispatchWorkerSessionAssociationEventPayload"
+                },
+                "type": {
+                    "const": "DISPATCH_WORKER_SESSION_ASSOCIATION"
+                }
+            },
+            "required": [
+                "type",
+                "payload"
+            ],
+            "type": "object"
+        },
         {
             "properties": {
                 "payload": {