@orkestrel/scaffold 0.0.115 → 0.0.117

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/dist/bin/main.js +138 -16
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +1 -1
  4. package/dist/host/claude/agents/orkestrel.md +2 -2
  5. package/dist/host/claude/rules/names.md +3 -1
  6. package/dist/host/guides/abort.md +17 -17
  7. package/dist/host/guides/agent.md +445 -445
  8. package/dist/host/guides/brief.md +143 -143
  9. package/dist/host/guides/browser.md +731 -731
  10. package/dist/host/guides/budget.md +39 -39
  11. package/dist/host/guides/capture.md +298 -298
  12. package/dist/host/guides/console.md +109 -109
  13. package/dist/host/guides/contract.md +335 -335
  14. package/dist/host/guides/csv.md +30 -30
  15. package/dist/host/guides/database.md +163 -163
  16. package/dist/host/guides/emitter.md +17 -17
  17. package/dist/host/guides/form.md +99 -99
  18. package/dist/host/guides/guide.md +368 -183
  19. package/dist/host/guides/html.md +49 -49
  20. package/dist/host/guides/indexeddb.md +40 -40
  21. package/dist/host/guides/interpret.md +139 -139
  22. package/dist/host/guides/lsp.md +114 -114
  23. package/dist/host/guides/markdown.md +68 -68
  24. package/dist/host/guides/mcp.md +3745 -3745
  25. package/dist/host/guides/middleware.md +170 -170
  26. package/dist/host/guides/msg.md +95 -95
  27. package/dist/host/guides/ndjson.md +8 -8
  28. package/dist/host/guides/ollama.md +56 -56
  29. package/dist/host/guides/pool.md +21 -21
  30. package/dist/host/guides/probe.md +82 -82
  31. package/dist/host/guides/process.md +99 -99
  32. package/dist/host/guides/program.md +98 -96
  33. package/dist/host/guides/qualifier.md +70 -70
  34. package/dist/host/guides/queue.md +37 -37
  35. package/dist/host/guides/rater.md +38 -38
  36. package/dist/host/guides/reason.md +308 -308
  37. package/dist/host/guides/relation.md +50 -50
  38. package/dist/host/guides/router.md +58 -58
  39. package/dist/host/guides/scaffold.md +558 -419
  40. package/dist/host/guides/sea.md +128 -128
  41. package/dist/host/guides/server.md +100 -100
  42. package/dist/host/guides/sqlite.md +28 -28
  43. package/dist/host/guides/sse.md +20 -20
  44. package/dist/host/guides/study.md +444 -444
  45. package/dist/host/guides/table.md +82 -82
  46. package/dist/host/guides/template.md +41 -41
  47. package/dist/host/guides/terminal.md +121 -121
  48. package/dist/host/guides/test.md +273 -273
  49. package/dist/host/guides/timeout.md +18 -18
  50. package/dist/host/guides/tool.md +27 -27
  51. package/dist/host/guides/toolbox.md +166 -166
  52. package/dist/host/guides/websocket.md +54 -54
  53. package/dist/host/guides/worker.md +24 -24
  54. package/dist/host/guides/workflow.md +187 -187
  55. package/dist/host/guides/workspace.md +55 -55
  56. package/dist/host/manifest.json +55 -55
  57. package/dist/host/tests/setupPolicy.ts +5 -3
  58. package/dist/src/core/index.cjs +90 -4
  59. package/dist/src/core/index.cjs.map +1 -1
  60. package/dist/src/core/index.d.cts +229 -144
  61. package/dist/src/core/index.d.ts +229 -144
  62. package/dist/src/core/index.js +88 -5
  63. package/dist/src/core/index.js.map +1 -1
  64. package/dist/src/server/index.cjs +295 -66
  65. package/dist/src/server/index.cjs.map +1 -1
  66. package/dist/src/server/index.d.cts +193 -6
  67. package/dist/src/server/index.d.ts +193 -6
  68. package/dist/src/server/index.js +290 -69
  69. package/dist/src/server/index.js.map +1 -1
  70. package/package.json +5 -4
@@ -16,49 +16,49 @@ Source: [`src/core`](../src/core) (the tool factories) and [`src/server`](../src
16
16
 
17
17
  ### Factories
18
18
 
19
- | API | Kind | Summary |
20
- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
21
- | `createToolFunction` | function | Wraps a registered tool as a `WorkflowFunction` (`@orkestrel/workflow`) — the opt-in adapter that lets a `function`-form task run a `@orkestrel/tool` tool by name. |
22
- | `createAgentFunction` | function | Wraps a live `AgentInterface` (`@orkestrel/agent`) as a `WorkflowFunction` (`@orkestrel/workflow`) — the opt-in adapter that runs the agent to a settled result and carries immutable lineage metadata for contextual Toolbox composition. |
23
- | `createWorkflowFunctions` | function | Composes opaque host functions and raw agents into one immutable workflow registry. |
24
- | `createWorkflowDraftContract` | function | Compiles the lenient workflow draft contract `createWorkflowTool` parses an authored tree with — a `ContractInterface` over a `WorkflowDraft`, whose `id` and `name` are optional at the workflow, phase, and task levels. |
25
- | `createWorkflowTool` | function | Wraps a `WorkflowDefinition` as an LLM-callable tool — it advertises the flat authoring shape (`{ name?, steps: [{ name }] }`) as its `parameters`, and its handler completes the authored blob, validates it against the strict contract, and runs it through `runner`, forwarding the caller's optional named functions and native checkpoint store. |
26
- | `createWorkspaceTool` | function | Builds an LLM-callable workspace-editing tool — it advertises the `operation`-discriminated union (`workspaceToolShape`) as its `parameters`, and its handler parses the model-supplied args against that contract and dispatches the matched operation against the manager's active workspace, returning the plain result. |
27
- | `createAgentTool` | function | Builds an LLM-callable sub-agent delegation tool — it resolves a live, seeded `AgentInterface` from `registry` and runs it to completion for one delegated `task`. |
28
- | `createDescribeTool` | function | Builds an LLM-callable tool that returns the full `description` of another registered tool by name — the counterpart to the lean `summary` the other tools in this package advertise. |
29
- | `createPromptTool` | function | Builds an LLM-callable form tool — the ask side of the terminal seam. It asks a multi-field form and blocks until the addressed terminal answers, returning the resolved values record. |
30
- | `createAnswerTool` | function | Builds an LLM-callable answer tool — the answer side of the terminal seam. It lists the forms addressed to `AnswerToolOptions.to`, or answers one of them by id. |
31
- | `createDatabaseTool` | function | Builds an LLM-callable database tool — it creates, queries, and mutates `@orkestrel/database` databases through one `operation`-discriminated call (matching `createWorkspaceTool`'s single-tool-many-operations shape). |
32
- | `createRelationTool` | function | Builds an LLM-callable relation tool — it traverses and edits `@orkestrel/relation` relationships through one `operation`-discriminated call (matching `createDatabaseTool`'s single-tool-many-operations shape). |
33
- | `createMemoryDefinitionStore` | function | Creates the in-memory `DefinitionStoreInterface` — a process-lifetime `Map` of database definitions, the default store the database and relation tools persist their `DatabaseDefinition` configs through. |
34
- | `createDatabaseDefinitionStore` | function | Creates a `DefinitionStoreInterface` backed by one table of the `@orkestrel/database` layer — the driver-pluggable twin of `createMemoryDefinitionStore`, storing each database's definition as one opaque JSON column. |
35
- | `createInferTool` | function | Builds a standalone LLM-callable tool that infers a JSON Schema from example values — the utility half of the bridge from an existing API or database into an MCP tool (the other half, `createEndpointTool`, wraps one concrete endpoint). |
36
- | `createEndpointTool` | function | Wraps one concrete endpoint (`EndpointDefinition`) as an LLM-callable `ToolInterface` — the endpoint half of the bridge from an existing API or database into an MCP tool (the other half, `createInferTool`, is a standalone inference utility). |
19
+ | Name | Kind | Signature | Summary |
20
+ | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
21
+ | `createToolFunction` | function | `(tools: ToolManagerInterface, name: string) => WorkflowFunction` | Wraps a registered tool as a `WorkflowFunction` (`@orkestrel/workflow`) — the opt-in adapter that lets a `function`-form task run a `@orkestrel/tool` tool by name. |
22
+ | `createAgentFunction` | function | `(agent: AgentInterface, options?: AgentFunctionOptions) => AgentFunction` | Wraps a live `AgentInterface` (`@orkestrel/agent`) as a `WorkflowFunction` (`@orkestrel/workflow`) — the opt-in adapter that runs the agent to a settled result and carries immutable lineage metadata for contextual Toolbox composition. |
23
+ | `createWorkflowFunctions` | function | `(runner: WorkflowRunnerInterface, options?: WorkflowToolOptions) => WorkflowRegistry` | Composes opaque host functions and raw agents into one immutable workflow registry. |
24
+ | `createWorkflowDraftContract` | function | `() => ContractInterface<WorkflowDraft>` | Compiles the lenient workflow draft contract `createWorkflowTool` parses an authored tree with — a `ContractInterface` over a `WorkflowDraft`, whose `id` and `name` are optional at the workflow, phase, and task levels. |
25
+ | `createWorkflowTool` | function | `(definition: WorkflowDefinition, runner: WorkflowRunnerInterface, options?: WorkflowToolOptions) => ToolInterface` | Wraps a `WorkflowDefinition` as an LLM-callable tool — it advertises the flat authoring shape (`{ name?, steps: [{ name }] }`) as its `parameters`, and its handler completes the authored blob, validates it against the strict contract, and runs it through `runner`, forwarding the caller's optional named functions and native checkpoint store. |
26
+ | `createWorkspaceTool` | function | `(options?: WorkspaceToolOptions) => ToolInterface` | Builds an LLM-callable workspace-editing tool — it advertises the `operation`-discriminated union (`workspaceToolShape`) as its `parameters`, and its handler parses the model-supplied args against that contract and dispatches the matched operation against the manager's active workspace, returning the plain result. |
27
+ | `createAgentTool` | function | `(registry: AgentRegistryInterface, options?: AgentToolOptions) => ToolInterface` | Builds an LLM-callable sub-agent delegation tool — it resolves a live, seeded `AgentInterface` from `registry` and runs it to completion for one delegated `task`. |
28
+ | `createDescribeTool` | function | `(tools: ToolManagerInterface) => ToolInterface` | Builds an LLM-callable tool that returns the full `description` of another registered tool by name — the counterpart to the lean `summary` the other tools in this package advertise. |
29
+ | `createPromptTool` | function | `(options: PromptToolOptions) => ToolInterface` | Builds an LLM-callable form tool — the ask side of the terminal seam. It asks a multi-field form and blocks until the addressed terminal answers, returning the resolved values record. |
30
+ | `createAnswerTool` | function | `(options: AnswerToolOptions) => ToolInterface` | Builds an LLM-callable answer tool — the answer side of the terminal seam. It lists the forms addressed to `AnswerToolOptions.to`, or answers one of them by id. |
31
+ | `createDatabaseTool` | function | `(options?: DatabaseToolOptions) => ToolInterface` | Builds an LLM-callable database tool — it creates, queries, and mutates `@orkestrel/database` databases through one `operation`-discriminated call (matching `createWorkspaceTool`'s single-tool-many-operations shape). |
32
+ | `createRelationTool` | function | `(options: RelationToolOptions) => ToolInterface` | Builds an LLM-callable relation tool — it traverses and edits `@orkestrel/relation` relationships through one `operation`-discriminated call (matching `createDatabaseTool`'s single-tool-many-operations shape). |
33
+ | `createMemoryDefinitionStore` | function | `() => DefinitionStoreInterface` | Creates the in-memory `DefinitionStoreInterface` — a process-lifetime `Map` of database definitions, the default store the database and relation tools persist their `DatabaseDefinition` configs through. |
34
+ | `createDatabaseDefinitionStore` | function | `(driver?: DriverInterface) => DefinitionStoreInterface` | Creates a `DefinitionStoreInterface` backed by one table of the `@orkestrel/database` layer — the driver-pluggable twin of `createMemoryDefinitionStore`, storing each database's definition as one opaque JSON column. |
35
+ | `createInferTool` | function | `(options?: InferToolOptions) => ToolInterface` | Builds a standalone LLM-callable tool that infers a JSON Schema from example values — the utility half of the bridge from an existing API or database into an MCP tool (the other half, `createEndpointTool`, wraps one concrete endpoint). |
36
+ | `createEndpointTool` | function | `(definition: EndpointDefinition, options?: EndpointToolOptions) => ToolInterface` | Wraps one concrete endpoint (`EndpointDefinition`) as an LLM-callable `ToolInterface` — the endpoint half of the bridge from an existing API or database into an MCP tool (the other half, `createInferTool`, is a standalone inference utility). |
37
37
 
38
38
  ### Stores
39
39
 
40
40
  Concrete `DefinitionStoreInterface` implementations (AGENTS' Stores rule, point-access mold): `MemoryDefinitionStore` the in-memory default, `DatabaseDefinitionStore` the driver-pluggable twin over one `@orkestrel/database` table. They implement the same `get` / `set` / `delete` contract over different backing storage, and differ within it: the memory store copies on write and on read, while the table-backed store narrows an untrusted stored blob and reports `undefined` for a malformed one.
41
41
 
42
- | API | Kind | Summary |
43
- | ------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
44
- | `MemoryDefinitionStore` | class | Represents the in-memory `DefinitionStoreInterface` — a process-lifetime `Map` of `DatabaseDefinition`s keyed by database id, the default store `createMemoryDefinitionStore` builds. It implements the same `DefinitionStoreInterface` contract as `DatabaseDefinitionStore`: this store copies on write and on read; the table-backed store narrows an untrusted stored blob and reports `undefined` for a malformed one. |
45
- | `DatabaseDefinitionStore` | class | Represents a `DefinitionStoreInterface` backed by one table of the `@orkestrel/database` layer — a database's durable config state is a row, so persistence reduces to keyed point-access (`get` / `set` / `delete`) over a `TableInterface`, the driver-pluggable twin of the plain-`Map` `MemoryDefinitionStore`. |
42
+ | Name | Kind | Signature | Summary |
43
+ | ------------------------- | ----- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
44
+ | `MemoryDefinitionStore` | class | `new () => DefinitionStoreInterface` | Represents the in-memory `DefinitionStoreInterface` — a process-lifetime `Map` of `DatabaseDefinition`s keyed by database id, the default store `createMemoryDefinitionStore` builds. It implements the same `DefinitionStoreInterface` contract as `DatabaseDefinitionStore`: this store copies on write and on read; the table-backed store narrows an untrusted stored blob and reports `undefined` for a malformed one. |
45
+ | `DatabaseDefinitionStore` | class | `new (table: TableInterface<DatabaseDefinitionRow>) => DefinitionStoreInterface` | Represents a `DefinitionStoreInterface` backed by one table of the `@orkestrel/database` layer — a database's durable config state is a row, so persistence reduces to keyed point-access (`get` / `set` / `delete`) over a `TableInterface`, the driver-pluggable twin of the plain-`Map` `MemoryDefinitionStore`. |
46
46
 
47
47
  ### Resolvers
48
48
 
49
49
  `DatabaseResolver` is the implementation class a consumer composes directly. The factories
50
50
  `createDatabaseTool` and `createTerminalRoutes` remain the compact entry points.
51
51
 
52
- | API | Kind | Summary |
53
- | ------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
54
- | `DatabaseResolver` | class | Resolves a database definition into a cached live handle for a database tool, over the tool's live handles, its stored definitions, its driver registry, and an optional key generator. |
52
+ | Name | Kind | Signature | Summary |
53
+ | ------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
54
+ | `DatabaseResolver` | class | `new (handles: ReadonlyMap<string, DatabaseInterface>, drivers: Readonly<Record<string, () => DriverInterface>>, generator?: KeyFunction, store?: DefinitionStoreInterface) => DatabaseResolver` | Resolves a database definition into a cached live handle for a database tool, over the tool's live handles, its stored definitions, its driver registry, and an optional key generator. |
55
55
 
56
56
  ### Errors
57
57
 
58
- | API | Kind | Summary |
59
- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
60
- | `ToolboxError` | class | Represents a package-owned tool-call failure: malformed input or unresolved configuration (`TOOL`), delegation depth/cycle rejection (`DEPTH`), prompt failure (`DEADLOCK` / `EXPIRE` / `ANSWER`), or a translated upstream database/relation failure (`DATABASE` / `RELATION`). |
61
- | `isToolboxError` | function | Narrows an unknown caught value to a `ToolboxError`. |
58
+ | Name | Kind | Signature | Summary |
59
+ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
60
+ | `ToolboxError` | class | `new (code: ToolboxErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => ToolboxError` | Represents a package-owned tool-call failure: malformed input or unresolved configuration (`TOOL`), delegation depth/cycle rejection (`DEPTH`), prompt failure (`DEADLOCK` / `EXPIRE` / `ANSWER`), or a translated upstream database/relation failure (`DATABASE` / `RELATION`). |
61
+ | `isToolboxError` | function | `(value: unknown) => value is ToolboxError` | Narrows an unknown caught value to a `ToolboxError`. |
62
62
 
63
63
  ### Validators
64
64
 
@@ -66,50 +66,50 @@ The total `(value: unknown) => value is T` guards this package applies at its un
66
66
 
67
67
  In a guard table a `Shape` cell holds the type the guard narrows to.
68
68
 
69
- | API | Kind | Shape | Summary |
70
- | ---------------------- | -------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
71
- | `isWorkflowLineage` | function | `WorkflowLineage` | Narrows an unknown value to a valid alternating workflow lineage. |
72
- | `isAgentFunction` | function | `AgentFunction` | Narrows an unknown callable to Toolbox's frozen contextual agent adapter metadata. |
73
- | `isColumnPrimitive` | const | `ColumnPrimitive` | Narrows an unknown value to a `ColumnPrimitive`. |
74
- | `isColumnSpec` | function | `ColumnSpec` | Narrows an unknown value to a `ColumnSpec`. |
75
- | `isDatabaseDefinition` | function | `DatabaseDefinition` | Narrows an unknown value to a `DatabaseDefinition` — a non-empty `id` and `driver`, a `tables` record whose every value is `{ columns: record of valid ColumnSpec }`, plus optional `primary`, `indexes`, and finite `version` schema configuration. The boundary guard a `DefinitionStoreInterface` applies to an untrusted persisted blob before trusting it as a definition (never an `as`). |
69
+ | Name | Kind | Signature | Summary |
70
+ | ---------------------- | -------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
71
+ | `isWorkflowLineage` | function | `(value: unknown) => value is WorkflowLineage` | Narrows an unknown value to a valid alternating workflow lineage. |
72
+ | `isAgentFunction` | function | `(value: unknown) => value is AgentFunction` | Narrows an unknown callable to Toolbox's frozen contextual agent adapter metadata. |
73
+ | `isColumnPrimitive` | const | `Guard<ColumnPrimitive>` | Narrows an unknown value to a `ColumnPrimitive`. |
74
+ | `isColumnSpec` | function | `(value: unknown) => value is ColumnSpec` | Narrows an unknown value to a `ColumnSpec`. |
75
+ | `isDatabaseDefinition` | function | `(value: unknown) => value is DatabaseDefinition` | Narrows an unknown value to a `DatabaseDefinition` — a non-empty `id` and `driver`, a `tables` record whose every value is `{ columns: record of valid ColumnSpec }`, plus optional `primary`, `indexes`, and finite `version` schema configuration. The boundary guard a `DefinitionStoreInterface` applies to an untrusted persisted blob before trusting it as a definition (never an `as`). |
76
76
 
77
77
  ### Helpers
78
78
 
79
79
  Pure, side-effect-free, exhaustively unit-tested under AGENTS' export-and-test-reusable-logic law and narrow-untrusted-input-with-guards rule — the lenient-authoring synthesis path and the ancestry tags `createAgentTool` and `createAgentFunction` share.
80
80
 
81
- | API | Kind | Summary |
82
- | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
83
- | `tagWorkflow` | function | Returns the ancestry identifier of a workflow in a run chain — `workflow:<id>`. |
84
- | `tagAgent` | function | Returns the ancestry identifier of an agent in a run chain — `agent:<name>`. |
85
- | `summarizeWorkflow` | function | Builds the plain success summary `createWorkflowTool` returns on a completed run — the universal tool-handler contract: return a plain value on success, appearing identically over both the agent loop and MCP. |
86
- | `extendLineage` | function | Appends one tag to a workflow lineage and returns a frozen copy. |
87
- | `normalizeLineage` | function | Returns the canonical workflow lineage — validated, copied, and frozen. |
88
- | `deriveWorkflowDepth` | function | Derives the zero-based workflow nesting depth from a valid lineage. |
89
- | `resolveWorkflowTarget` | function | Resolves an owned workflow input through the supplied flat or draft contracts. |
90
- | `completeDraft` | function | Completes a `WorkflowDraft` into a strict `WorkflowDefinition` — synthesizes a missing `id` deterministically and positionally, and defaults a missing `name` to its resolved `id`. |
91
- | `completePhaseDraft` | function | Completes one `PhaseDraft` into a strict phase definition — the per-phase step of `completeDraft` (phase `index` → `phase-<index>` when its id is omitted). |
92
- | `completeTaskDraft` | function | Completes one `TaskDraft` into a strict task definition — the per-task leaf step of `completeDraft` (task `index` of phase `<phaseId>` → `<phaseId>-task-<index>` when its id is omitted). |
93
- | `expandSteps` | function | Expands a flat `WorkflowSteps` blob into a strict `WorkflowDefinition` — each step becomes a one-task phase, in order. |
94
- | `inferTerminalCode` | function | Maps a caught error to the `ToolboxErrorCode` the terminal-tool factory throws with — the pure classification step of that factory's error handling. |
95
- | `inferDatabaseCode` | function | Maps a caught error to the granular `DatabaseErrorCode` (`@orkestrel/database`) the code `createDatabaseTool` throws with — the pure classification step of that factory's error handling, mirroring `inferTerminalCode`'s idiom for `@orkestrel/database`. |
96
- | `inferRelationCode` | function | Maps a caught error to the granular `RelationErrorCode` (`@orkestrel/relation`) the code `createRelationTool` throws with — the pure classification step of that factory's error handling, mirroring `inferTerminalCode`'s idiom for `@orkestrel/relation`. |
97
- | `expandInclude` | function | Expands the relation tool's flat dot-path `include` list into a live `@orkestrel/relation` `Include` tree — the pure leaf `createRelationTool` calls before a `'load'` / `'find'` call. |
98
- | `resolveRelationManager` | function | Resolves which registered `RelationManagerInterface` a relation-tool call addresses — the pure manager-resolution leaf `createRelationTool` calls on every operation. |
99
- | `resolveRelationModel` | function | Resolves a `model` name against a live `RelationManagerInterface` — the pure model-lookup leaf `createRelationTool` calls on every operation, mirroring `resolveRelationManager`'s guard shape. |
100
- | `clampQuery` | function | Clamps a `'records'` call's query to a row cap, and builds the probe query the caller reads with — the pure leaf `createDatabaseTool`'s `'records'` operation uses to detect truncation without a separate `count` round trip. |
101
- | `resolveLimit` | function | Picks the effective row limit a tool reads with — the requested count when it sits inside the cap, the cap when it exceeds it, and `0` when either falls below zero. |
102
- | `normalizeQuery` | function | Returns the canonical live `@orkestrel/database` `QueryInput` for the database tool's parsed serialized query — each condition's omitted `connector` defaults to `'and'`. |
81
+ | Name | Kind | Signature | Summary |
82
+ | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
83
+ | `tagWorkflow` | function | `(id: string) => string` | Returns the ancestry identifier of a workflow in a run chain — `workflow:<id>`. |
84
+ | `tagAgent` | function | `(name: string) => string` | Returns the ancestry identifier of an agent in a run chain — `agent:<name>`. |
85
+ | `summarizeWorkflow` | function | `(result: WorkflowResult) => WorkflowToolResult` | Builds the plain success summary `createWorkflowTool` returns on a completed run — the universal tool-handler contract: return a plain value on success, appearing identically over both the agent loop and MCP. |
86
+ | `extendLineage` | function | `(lineage: WorkflowLineage, tag: string) => WorkflowLineage` | Appends one tag to a workflow lineage and returns a frozen copy. |
87
+ | `normalizeLineage` | function | `(lineage?: WorkflowLineage) => WorkflowLineage` | Returns the canonical workflow lineage — validated, copied, and frozen. |
88
+ | `deriveWorkflowDepth` | function | `(lineage: WorkflowLineage) => number` | Derives the zero-based workflow nesting depth from a valid lineage. |
89
+ | `resolveWorkflowTarget` | function | `(owned: JSONRecord, definition: WorkflowDefinition, steps: ContractInterface<WorkflowSteps>, draft: ContractInterface<WorkflowDraft>) => WorkflowDefinition \| undefined` | Resolves an owned workflow input through the supplied flat or draft contracts. |
90
+ | `completeDraft` | function | `(draft: WorkflowDraft) => WorkflowDefinition` | Completes a `WorkflowDraft` into a strict `WorkflowDefinition` — synthesizes a missing `id` deterministically and positionally, and defaults a missing `name` to its resolved `id`. |
91
+ | `completePhaseDraft` | function | `(phase: PhaseDraft, index: number) => WorkflowDefinition['phases'][number]` | Completes one `PhaseDraft` into a strict phase definition — the per-phase step of `completeDraft` (phase `index` → `phase-<index>` when its id is omitted). |
92
+ | `completeTaskDraft` | function | `(task: TaskDraft, phaseId: string, index: number) => WorkflowDefinition['phases'][number]['tasks'][number]` | Completes one `TaskDraft` into a strict task definition — the per-task leaf step of `completeDraft` (task `index` of phase `<phaseId>` → `<phaseId>-task-<index>` when its id is omitted). |
93
+ | `expandSteps` | function | `(flat: WorkflowSteps) => WorkflowDefinition` | Expands a flat `WorkflowSteps` blob into a strict `WorkflowDefinition` — each step becomes a one-task phase, in order. |
94
+ | `inferTerminalCode` | function | `(error: unknown) => ToolboxErrorCode \| undefined` | Maps a caught error to the `ToolboxErrorCode` the terminal-tool factory throws with — the pure classification step of that factory's error handling. |
95
+ | `inferDatabaseCode` | function | `(error: unknown) => DatabaseErrorCode \| undefined` | Maps a caught error to the granular `DatabaseErrorCode` (`@orkestrel/database`) the code `createDatabaseTool` throws with — the pure classification step of that factory's error handling, mirroring `inferTerminalCode`'s idiom for `@orkestrel/database`. |
96
+ | `inferRelationCode` | function | `(error: unknown) => RelationErrorCode \| undefined` | Maps a caught error to the granular `RelationErrorCode` (`@orkestrel/relation`) the code `createRelationTool` throws with — the pure classification step of that factory's error handling, mirroring `inferTerminalCode`'s idiom for `@orkestrel/relation`. |
97
+ | `expandInclude` | function | `(paths: readonly string[] \| undefined, depth: number) => Include` | Expands the relation tool's flat dot-path `include` list into a live `@orkestrel/relation` `Include` tree — the pure leaf `createRelationTool` calls before a `'load'` / `'find'` call. |
98
+ | `resolveRelationManager` | function | `(managers: Readonly<Record<string, RelationManagerInterface>>, name: string \| undefined) => RelationManagerInterface` | Resolves which registered `RelationManagerInterface` a relation-tool call addresses — the pure manager-resolution leaf `createRelationTool` calls on every operation. |
99
+ | `resolveRelationModel` | function | `(manager: RelationManagerInterface, name: string) => ModelInterface` | Resolves a `model` name against a live `RelationManagerInterface` — the pure model-lookup leaf `createRelationTool` calls on every operation, mirroring `resolveRelationManager`'s guard shape. |
100
+ | `clampQuery` | function | `(query: QueryInput \| undefined, cap: number) => ClampedQuery` | Clamps a `'records'` call's query to a row cap, and builds the probe query the caller reads with — the pure leaf `createDatabaseTool`'s `'records'` operation uses to detect truncation without a separate `count` round trip. |
101
+ | `resolveLimit` | function | `(requested: number \| undefined, cap: number) => number` | Picks the effective row limit a tool reads with — the requested count when it sits inside the cap, the cap when it exceeds it, and `0` when either falls below zero. |
102
+ | `normalizeQuery` | function | `(query: DatabaseQueryInput \| undefined) => QueryInput \| undefined` | Returns the canonical live `@orkestrel/database` `QueryInput` for the database tool's parsed serialized query — each condition's omitted `connector` defaults to `'and'`. |
103
103
 
104
104
  ### Compilers
105
105
 
106
106
  The `TableSpec` column DSL compiled into the live `@orkestrel/database` `TableMap` a `createDatabase` call accepts — one composite walk over the spec, and the `compileColumn` / `compileColumnPrimitive` leaves it maps with.
107
107
 
108
- | API | Kind | Summary |
109
- | ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
110
- | `expandTables` | function | Compiles a `TableSpec` into the `@orkestrel/database` `TableMap` it configures — each `ColumnSpec` maps to the matching primitive shaper (`'string'` → `stringShape()`, `'integer'` → `integerShape()`, `'number'` → `numberShape()`, `'boolean'` → `booleanShape()`), wrapped in `optionalShape` when the column declares `optional: true`. Total, pure. |
111
- | `compileColumn` | function | Compiles one `ColumnSpec` into its `@orkestrel/database` column shape — the per-column leaf `expandTables` maps over. |
112
- | `compileColumnPrimitive` | function | Compiles one `ColumnPrimitive` into its primitive `@orkestrel/database` shape — the leaf `compileColumn` wraps. |
108
+ | Name | Kind | Signature | Summary |
109
+ | ------------------------ | -------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
110
+ | `expandTables` | function | `(spec: TableSpec) => TableMap` | Compiles a `TableSpec` into the `@orkestrel/database` `TableMap` it configures — each `ColumnSpec` maps to the matching primitive shaper (`'string'` → `stringShape()`, `'integer'` → `integerShape()`, `'number'` → `numberShape()`, `'boolean'` → `booleanShape()`), wrapped in `optionalShape` when the column declares `optional: true`. Total, pure. |
111
+ | `compileColumn` | function | `(spec: ColumnSpec) => ContractShape` | Compiles one `ColumnSpec` into its `@orkestrel/database` column shape — the per-column leaf `expandTables` maps over. |
112
+ | `compileColumnPrimitive` | function | `(primitive: ColumnPrimitive) => ContractShape` | Compiles one `ColumnPrimitive` into its primitive `@orkestrel/database` shape — the leaf `compileColumn` wraps. |
113
113
 
114
114
  ### Shapes
115
115
 
@@ -117,116 +117,116 @@ The shape values each `create*Tool` factory (and `createWorkflowDraftContract`)
117
117
 
118
118
  A `Shape` cell holds the constant's declared type.
119
119
 
120
- | API | Kind | Shape | Summary |
121
- | ---------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
122
- | `agentToolShape` | const | `ObjectShape<{ task, provider?, tools?, system? }>` | Describes the shape of `AgentToolArguments` — `createAgentTool`'s advertised `parameters`. |
123
- | `taskDraftShape` | const | `ObjectShape<{ id?, name?, description?, behavior?, retries?, timeout? }>` | Describes the shape of a `TaskDraft` — identical to a strict task shape except that `id` and `name` are optional. |
124
- | `phaseDraftShape` | const | `ObjectShape<{ id?, name?, description?, tasks, concurrency?, bail? }>` | Describes the shape of a phase in a draft workflow — identical to a strict phase shape except that `id` and `name` are optional and each task takes `taskDraftShape`. |
125
- | `workflowDraftShape` | const | `ObjectShape<{ id?, name?, description?, phases, bail? }>` | Describes the shape of a draft workflow — identical to a strict workflow shape except that `id` and `name` are optional at the workflow, phase, and task levels, so a small model can omit every identity string and let the tool synthesize them positionally. |
126
- | `stepShape` | const | `ObjectShape<{ name }>` | Describes the shape of one flat step — `{ name }` — the building block of `workflowStepsShape`. |
127
- | `workflowStepsShape` | const | `ObjectShape<{ name?, steps }>` | Describes the flat authoring shape `createWorkflowTool` advertises as its `parameters` — the simplest surface a small model can fill: `{ name?, steps: [{ name }] }`. |
128
- | `workspaceToolShape` | const | `UnionShape<[{ operation: 'read', path }, { operation: 'list' }, { operation: 'has', path }, { operation: 'search', query, regex?, sensitive?, limit? }, { operation: 'replace', query, replacement, regex?, sensitive?, limit? }, { operation: 'write', path, content }, { operation: 'splice', path, content, fromLine, fromColumn, toLine, toColumn }, { operation: 'prepend', path, content }, { operation: 'append', path, content }, { operation: 'move', from, to }, { operation: 'remove', path }, { operation: 'workspaces' }, { operation: 'switch', id }]>` | Describes the shape of a `WorkspaceOperation` — a descriptive tagged union over the workspace edit, read, and navigation operations, discriminated by the `operation` literal (never a bare `kind`). Each variant leads with its `operation` discriminant then its flat fields, every field through `stringShape` / `optionalShape` / `integerShape({ min: 1 })` / `booleanShape`, each carrying a strong field-level `description`. |
129
- | `describeToolShape` | const | `ObjectShape<{ name }>` | Describes the shape of `DescribeToolArguments` — `createDescribeTool`'s advertised `parameters`. |
130
- | `promptToolShape` | const | `ObjectShape<{ to, schema }>` | Describes the shape of `createPromptTool`'s call arguments — `to` names the terminal identity and `schema` carries the complete multi-field form document. |
131
- | `answerToolShape` | const | `UnionShape<[{ operation: 'pending' }, { operation: 'answer', id, values }]>` | Describes the shape of `createAnswerTool`'s call arguments — discriminated by `operation`: `'pending'` lists the forms addressed to this tool's terminal, while `'answer'` resolves one by `id` with a complete `values` record. |
132
- | `databaseToolShape` | const | `UnionShape<[{ operation: 'create', id, tables, driver?, primary?, indexes?, version? }, { operation: 'tables', id }, { operation: 'get', id, table, key }, { operation: 'records', id, table, query? }, { operation: 'count', id, table, query? }, { operation: 'aggregate', id, table, function, column, query? }, { operation: 'add', id, table, row }, { operation: 'set', id, table, row }, { operation: 'update', id, table, key, changes }, { operation: 'remove', id, table, key }, { operation: 'destroy', id }]>` | Describes the shape of `createDatabaseTool`'s call arguments — discriminated by `operation` into the database operations `'create'`, `'tables'`, `'get'`, `'records'`, `'count'`, `'aggregate'`, `'add'`, `'set'`, `'update'`, `'remove'`, and `'destroy'`. |
133
- | `columnPrimitiveShape` | const | `LiteralShape<'string' \| 'integer' \| 'number' \| 'boolean'>` | Describes a `ColumnPrimitive` literal — the leaf `columnSpecShape` wraps. |
134
- | `columnSpecShape` | const | `UnionShape<[columnPrimitiveShape, { primitive, optional? }]>` | Describes a `ColumnSpec` — a bare `columnPrimitiveShape`, or `{ primitive, optional }`. |
135
- | `tableSpecShape` | const | `ObjectShape<Record<never, never>, ObjectShape<{ columns }>>` | Describes a `TableSpec` — table name to `{ columns }`, each column a `columnSpecShape`. |
136
- | `keyShape` | const | `UnionShape<[ArrayShape<UnionShape<[StringShape, NumberShape]>>, StringShape, NumberShape]>` | Describes one key value for the database tool and the relation tool — a string or number; the array form (multiple keys, positional) resolves first, so an array argument is read as many keys rather than one. |
137
- | `rowShape` | const | `ObjectShape<Record<never, never>, JSONShape>` | Describes a loose row — a flat object of column name to JSON value. |
138
- | `rowsShape` | const | `UnionShape<[ArrayShape<rowShape>, rowShape]>` | Describes one or many loose rows — the array form resolves first, so an array argument is read as many rows rather than one. |
139
- | `conditionShape` | const | `ObjectShape<{ column, operator, values, connector? }>` | Describes one serialized where condition — `values` is always an array, even for a single-value operator. |
140
- | `orderShape` | const | `ObjectShape<{ column, direction }>` | Describes one sort term — a `column` to sort by and the `direction` to sort it in. |
141
- | `queryShape` | const | `ObjectShape<{ conditions?, order?, limit?, offset? }>` | Describes the serialized query form — conditions, order, and pagination. |
142
- | `relationToolShape` | const | `UnionShape<[{ operation: 'load', manager?, model, key, include? }, { operation: 'find', manager?, model, include?, limit?, offset?, sort?, direction? }, { operation: 'link', manager?, model, key, relation, target }, { operation: 'unlink', manager?, model, key, relation, target }, { operation: 'links', manager?, model, key, relation }]>` | Describes the shape of `createRelationTool`'s call arguments — discriminated by `operation` into the relation operations `'load'`, `'find'`, `'link'`, `'unlink'`, and `'links'`. |
143
- | `singleKeyShape` | const | `UnionShape<[StringShape, NumberShape]>` | Describes a single row key (not an array) — used by `'link'` / `'unlink'` / `'links'`, which address exactly one owning row. |
144
- | `includeShape` | const | `OptionalShape<ArrayShape<StringShape>>` | Describes the flat dot-path relation include list, expanded through `expandInclude`. |
145
- | `managerShape` | const | `OptionalShape<StringShape>` | Describes which registered relation manager to address — omitted resolves to the sole registered manager. |
146
- | `inferToolShape` | const | `ObjectShape<{ samples, format?, enum?, candidates? }>` | Describes the shape of `createInferTool`'s call arguments — one or more example `samples` to infer a JSON Schema from, plus per-call `format` / `enum` toggles and an optional `candidates` array to check against the inferred schema. |
120
+ | Name | Kind | Signature | Summary |
121
+ | ---------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
122
+ | `agentToolShape` | const | `import("@orkestrel/contract").ObjectShape<{ task: import("@orkestrel/contract").StringShape; provider: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; tools: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>>; system: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Describes the shape of `AgentToolArguments` — `createAgentTool`'s advertised `parameters`. |
123
+ | `taskDraftShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>` | Describes the shape of a `TaskDraft` — identical to a strict task shape except that `id` and `name` are optional. |
124
+ | `phaseDraftShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; tasks: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a phase in a draft workflow — identical to a strict phase shape except that `id` and `name` are optional and each task takes `taskDraftShape`. |
125
+ | `workflowDraftShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; phases: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; tasks: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a draft workflow — identical to a strict workflow shape except that `id` and `name` are optional at the workflow, phase, and task levels, so a small model can omit every identity string and let the tool synthesize them positionally. |
126
+ | `stepShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; }, false>` | Describes the shape of one flat step — `{ name }` — the building block of `workflowStepsShape`. |
127
+ | `workflowStepsShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; steps: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; }, false>>; }, false>` | Describes the flat authoring shape `createWorkflowTool` advertises as its `parameters` — the simplest surface a small model can fill: `{ name?, steps: [{ name }] }`. |
128
+ | `workspaceToolShape` | const | `import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["read"]>; path: import("@orkestrel/contract").StringShape; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["list"]>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["has"]>; path: import("@orkestrel/contract").StringShape; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["search"]>; query: import("@orkestrel/contract").StringShape; regex: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; sensitive: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; limit: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["replace"]>; query: import("@orkestrel/contract").StringShape; replacement: import("@orkestrel/contract").StringShape; regex: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; sensitive: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; limit: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["write"]>; path: import("@orkestrel/contract").StringShape; content: import("@orkestrel/contract").StringShape; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["splice"]>; path: import("@orkestrel/contract").StringShape; content: import("@orkestrel/contract").StringShape; fromLine: import("@orkestrel/contract").NumberShape; fromColumn: import("@orkestrel/contract").NumberShape; toLine: import("@orkestrel/contract").NumberShape; toColumn: import("@orkestrel/contract").NumberShape; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["prepend"]>; path: import("@orkestrel/contract").StringShape; content: import("@orkestrel/contract").StringShape; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["append"]>; path: import("@orkestrel/contract").StringShape; content: import("@orkestrel/contract").StringShape; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["move"]>; from: import("@orkestrel/contract").StringShape; to: import("@orkestrel/contract").StringShape; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["remove"]>; path: import("@orkestrel/contract").StringShape; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["workspaces"]>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["switch"]>; id: import("@orkestrel/contract").StringShape; }, false>]>` | Describes the shape of a `WorkspaceOperation` — a descriptive tagged union over the workspace edit, read, and navigation operations, discriminated by the `operation` literal (never a bare `kind`). Each variant leads with its `operation` discriminant then its flat fields, every field through `stringShape` / `optionalShape` / `integerShape({ min: 1 })` / `booleanShape`, each carrying a strong field-level `description`. |
129
+ | `describeToolShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; }, false>` | Describes the shape of `DescribeToolArguments` — `createDescribeTool`'s advertised `parameters`. |
130
+ | `promptToolShape` | const | `import("@orkestrel/contract").ObjectShape<{ to: import("@orkestrel/contract").StringShape; schema: import("@orkestrel/contract").JSONShape; }, false>` | Describes the shape of `createPromptTool`'s call arguments — `to` names the terminal identity and `schema` carries the complete multi-field form document. |
131
+ | `answerToolShape` | const | `import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["pending"]>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["answer"]>; id: import("@orkestrel/contract").StringShape; values: import("@orkestrel/contract").JSONShape; }, false>]>` | Describes the shape of `createAnswerTool`'s call arguments — discriminated by `operation`: `'pending'` lists the forms addressed to this tool's terminal, while `'answer'` resolves one by `id` with a complete `values` record. |
132
+ | `databaseToolShape` | const | `import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["create"]>; id: import("@orkestrel/contract").StringShape; tables: import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").ObjectShape<{ columns: import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").LiteralShape<readonly ["string", "integer", "number", "boolean"]>, import("@orkestrel/contract").ObjectShape<{ primitive: import("@orkestrel/contract").LiteralShape<readonly ["string", "integer", "number", "boolean"]>; optional: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; }, false>]>>; }, false>>; driver: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; primary: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").StringShape>>; indexes: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>>>>; version: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["tables"]>; id: import("@orkestrel/contract").StringShape; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["get"]>; id: import("@orkestrel/contract").StringShape; table: import("@orkestrel/contract").StringShape; key: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>>, import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["records"]>; id: import("@orkestrel/contract").StringShape; table: import("@orkestrel/contract").StringShape; query: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<{ conditions: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ column: import("@orkestrel/contract").StringShape; operator: import("@orkestrel/contract").LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>; values: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").JSONShape>; connector: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly ["and", "or"]>>; }, false>>>; order: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ column: import("@orkestrel/contract").StringShape; direction: import("@orkestrel/contract").LiteralShape<readonly ["ascending", "descending"]>; }, false>>>; limit: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; offset: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["count"]>; id: import("@orkestrel/contract").StringShape; table: import("@orkestrel/contract").StringShape; query: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<{ conditions: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ column: import("@orkestrel/contract").StringShape; operator: import("@orkestrel/contract").LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>; values: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").JSONShape>; connector: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly ["and", "or"]>>; }, false>>>; order: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ column: import("@orkestrel/contract").StringShape; direction: import("@orkestrel/contract").LiteralShape<readonly ["ascending", "descending"]>; }, false>>>; limit: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; offset: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["aggregate"]>; id: import("@orkestrel/contract").StringShape; table: import("@orkestrel/contract").StringShape; function: import("@orkestrel/contract").LiteralShape<readonly ["count", "sum", "average", "minimum", "maximum"]>; column: import("@orkestrel/contract").StringShape; query: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<{ conditions: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ column: import("@orkestrel/contract").StringShape; operator: import("@orkestrel/contract").LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>; values: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").JSONShape>; connector: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly ["and", "or"]>>; }, false>>>; order: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ column: import("@orkestrel/contract").StringShape; direction: import("@orkestrel/contract").LiteralShape<readonly ["ascending", "descending"]>; }, false>>>; limit: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; offset: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["add"]>; id: import("@orkestrel/contract").StringShape; table: import("@orkestrel/contract").StringShape; row: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").JSONShape>>, import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").JSONShape>]>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["set"]>; id: import("@orkestrel/contract").StringShape; table: import("@orkestrel/contract").StringShape; row: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").JSONShape>>, import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").JSONShape>]>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["update"]>; id: import("@orkestrel/contract").StringShape; table: import("@orkestrel/contract").StringShape; key: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>>, import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>; changes: import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").JSONShape>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["remove"]>; id: import("@orkestrel/contract").StringShape; table: import("@orkestrel/contract").StringShape; key: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>>, import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["destroy"]>; id: import("@orkestrel/contract").StringShape; }, false>]>` | Describes the shape of `createDatabaseTool`'s call arguments — discriminated by `operation` into the database operations `'create'`, `'tables'`, `'get'`, `'records'`, `'count'`, `'aggregate'`, `'add'`, `'set'`, `'update'`, `'remove'`, and `'destroy'`. |
133
+ | `columnPrimitiveShape` | const | `import("@orkestrel/contract").LiteralShape<readonly ["string", "integer", "number", "boolean"]>` | Describes a `ColumnPrimitive` literal — the leaf `columnSpecShape` wraps. |
134
+ | `columnSpecShape` | const | `import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").LiteralShape<readonly ["string", "integer", "number", "boolean"]>, import("@orkestrel/contract").ObjectShape<{ primitive: import("@orkestrel/contract").LiteralShape<readonly ["string", "integer", "number", "boolean"]>; optional: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; }, false>]>` | Describes a `ColumnSpec` — a bare `columnPrimitiveShape`, or `{ primitive, optional }`. |
135
+ | `tableSpecShape` | const | `import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").ObjectShape<{ columns: import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").LiteralShape<readonly ["string", "integer", "number", "boolean"]>, import("@orkestrel/contract").ObjectShape<{ primitive: import("@orkestrel/contract").LiteralShape<readonly ["string", "integer", "number", "boolean"]>; optional: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; }, false>]>>; }, false>>` | Describes a `TableSpec` — table name to `{ columns }`, each column a `columnSpecShape`. |
136
+ | `keyShape` | const | `import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>>, import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>` | Describes one key value for the database tool and the relation tool — a string or number; the array form (multiple keys, positional) resolves first, so an array argument is read as many keys rather than one. |
137
+ | `rowShape` | const | `import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").JSONShape>` | Describes a loose row — a flat object of column name to JSON value. |
138
+ | `rowsShape` | const | `import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").JSONShape>>, import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").JSONShape>]>` | Describes one or many loose rows — the array form resolves first, so an array argument is read as many rows rather than one. |
139
+ | `conditionShape` | const | `import("@orkestrel/contract").ObjectShape<{ column: import("@orkestrel/contract").StringShape; operator: import("@orkestrel/contract").LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>; values: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").JSONShape>; connector: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly ["and", "or"]>>; }, false>` | Describes one serialized where condition — `values` is always an array, even for a single-value operator. |
140
+ | `orderShape` | const | `import("@orkestrel/contract").ObjectShape<{ column: import("@orkestrel/contract").StringShape; direction: import("@orkestrel/contract").LiteralShape<readonly ["ascending", "descending"]>; }, false>` | Describes one sort term — a `column` to sort by and the `direction` to sort it in. |
141
+ | `queryShape` | const | `import("@orkestrel/contract").ObjectShape<{ conditions: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ column: import("@orkestrel/contract").StringShape; operator: import("@orkestrel/contract").LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>; values: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").JSONShape>; connector: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly ["and", "or"]>>; }, false>>>; order: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ column: import("@orkestrel/contract").StringShape; direction: import("@orkestrel/contract").LiteralShape<readonly ["ascending", "descending"]>; }, false>>>; limit: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; offset: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>` | Describes the serialized query form — conditions, order, and pagination. |
142
+ | `relationToolShape` | const | `import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["load"]>; manager: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; model: import("@orkestrel/contract").StringShape; key: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>>, import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>; include: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["find"]>; manager: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; model: import("@orkestrel/contract").StringShape; include: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>>; limit: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; offset: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; sort: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; direction: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly ["ascending", "descending"]>>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["link"]>; manager: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; model: import("@orkestrel/contract").StringShape; key: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>; relation: import("@orkestrel/contract").StringShape; target: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["unlink"]>; manager: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; model: import("@orkestrel/contract").StringShape; key: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>; relation: import("@orkestrel/contract").StringShape; target: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>; }, false>, import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly ["links"]>; manager: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; model: import("@orkestrel/contract").StringShape; key: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>; relation: import("@orkestrel/contract").StringShape; }, false>]>` | Describes the shape of `createRelationTool`'s call arguments — discriminated by `operation` into the relation operations `'load'`, `'find'`, `'link'`, `'unlink'`, and `'links'`. |
143
+ | `singleKeyShape` | const | `import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>` | Describes a single row key (not an array) — used by `'link'` / `'unlink'` / `'links'`, which address exactly one owning row. |
144
+ | `includeShape` | const | `import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>>` | Describes the flat dot-path relation include list, expanded through `expandInclude`. |
145
+ | `managerShape` | const | `import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>` | Describes which registered relation manager to address — omitted resolves to the sole registered manager. |
146
+ | `inferToolShape` | const | `import("@orkestrel/contract").ObjectShape<{ samples: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").JSONShape>; format: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; enum: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; candidates: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").JSONShape>>; }, false>` | Describes the shape of `createInferTool`'s call arguments — one or more example `samples` to infer a JSON Schema from, plus per-call `format` / `enum` toggles and an optional `candidates` array to check against the inferred schema. |
147
147
 
148
148
  ### Constants
149
149
 
150
150
  A `Shape` cell holds the constant's declared type.
151
151
 
152
- | Constant | Kind | Shape | Summary |
153
- | ------------------------------ | ----- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
154
- | `AGENT_TOOL_NAME` | const | `string` | Holds the name `createAgentTool` advertises by default, `'agent'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
155
- | `AGENT_TOOL_DEPTH` | const | `number` | Holds the maximum nesting depth a delegation chain (agent tool → sub-agent → agent tool → …) may reach, `8` — the bound `createAgentTool`'s depth/cycle guard enforces. |
156
- | `AGENT_TOOL_DESCRIPTION` | const | `string` | Holds the description `createAgentTool` advertises — a short guide covering the required task and optional provider, tools, and system overrides. |
157
- | `AGENT_TOOL_SUMMARY` | const | `string` | Holds the lean `ToolInterface.summary` `createAgentTool` advertises in place of `AGENT_TOOL_DESCRIPTION` — one sentence offering sub-agent delegation and pointing at `describe` for the optional overrides. |
158
- | `MAX_WORKFLOW_CHAIN` | const | `number` | Holds the maximum nesting depth a workflow → agent → workflow chain may reach, `8` — the bound `createAgentFunction` and `createWorkflowTool`'s depth/cycle guards enforce. |
159
- | `WORKFLOW_TOOL_NAME` | const | `string` | Holds the name `createWorkflowTool` advertises by default, `'workflow'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under, and the name `createAgentFunction` binds the depth/cycle-aware workflow tool under onto a wrapped agent's `context.tools`. |
160
- | `WORKFLOW_TOOL_FLAT_EXAMPLE` | const | `WorkflowSteps` | Holds a complete flat authoring example — the primary way a small model authors a workflow through `createWorkflowTool`: `{ name, steps: [{ name }] }`. |
161
- | `WORKFLOW_TOOL_NESTED_EXAMPLE` | const | `WorkflowDefinition` | Holds a minimal nested authoring example — the advanced escape-hatch form a model can use instead of the flat shape: a full `WorkflowDefinition` (`@orkestrel/workflow`). |
162
- | `WORKFLOW_TOOL_DESCRIPTION` | const | `string` | Holds the description `createWorkflowTool` advertises — the flat authoring form, its worked example, and the advanced nested definition form. |
163
- | `WORKFLOW_TOOL_SUMMARY` | const | `string` | Holds the lean `ToolInterface.summary` `createWorkflowTool` advertises in place of `WORKFLOW_TOOL_DESCRIPTION` — one sentence offering multi-phase authoring and pointing at `describe` for the authoring schema and its examples. |
164
- | `WORKSPACE_TOOL_NAME` | const | `string` | Holds the name `createWorkspaceTool` advertises by default, `'workspace'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
165
- | `WORKSPACE_TOOL_EXAMPLE` | const | `WorkspaceOperation` | Holds a valid `WorkspaceOperation` object — the canonical example embedded verbatim in `WORKSPACE_TOOL_DESCRIPTION`. |
166
- | `WORKSPACE_TOOL_DESCRIPTION` | const | `string` | Holds the description `createWorkspaceTool` advertises — the operation-keyed workspace protocol, all supported operations, and worked examples. |
167
- | `WORKSPACE_TOOL_SUMMARY` | const | `string` | Holds the lean `ToolInterface.summary` `createWorkspaceTool` advertises in place of `WORKSPACE_TOOL_DESCRIPTION` — one sentence offering the `operation`-keyed file editing and pointing at `describe` for the operation list and its fields. |
168
- | `DESCRIBE_TOOL_NAME` | const | `string` | Holds the name `createDescribeTool` advertises by default, `'describe'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
169
- | `DESCRIBE_TOOL_SUMMARY` | const | `string` | Holds the lean `ToolInterface.summary` `createDescribeTool` advertises — this tool needs no teaching of its own, so its summary and description are both short. |
170
- | `DESCRIBE_TOOL_DESCRIPTION` | const | `string` | Holds the description `createDescribeTool` advertises — the registered tool `name` it requires, and the full description of that tool it returns. |
171
- | `PROMPT_TOOL_NAME` | const | `string` | Holds the name `createPromptTool` advertises by default, `'ask'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
172
- | `PROMPT_TOOL_SUMMARY` | const | `string` | Holds the lean `ToolInterface.summary` `createPromptTool` advertises in place of `PROMPT_TOOL_DESCRIPTION` — one sentence offering the blocking multi-field ask and pointing at `describe` for the schema. |
173
- | `PROMPT_TOOL_DESCRIPTION` | const | `string` | Holds the form protocol `createPromptTool` advertises — the required `to` and `schema`, how a field declares its control and its rules, and a worked example. |
174
- | `ANSWER_TOOL_NAME` | const | `string` | Holds the name `createAnswerTool` advertises by default, `'answer'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
175
- | `ANSWER_TOOL_SUMMARY` | const | `string` | Holds the lean `ToolInterface.summary` `createAnswerTool` advertises in place of `ANSWER_TOOL_DESCRIPTION` — one sentence offering the pending listing and the answer call, and pointing at `describe` for the fields each takes. |
176
- | `ANSWER_TOOL_DESCRIPTION` | const | `string` | Holds the protocol `createAnswerTool` advertises — the `pending` and `answer` operations and the `values` record an answer supplies, each with a worked example. |
177
- | `DATABASE_TOOL_NAME` | const | `string` | Holds the name `createDatabaseTool` advertises by default, `'database'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
178
- | `DATABASE_TOOL_SUMMARY` | const | `string` | Holds the lean `ToolInterface.summary` `createDatabaseTool` advertises in place of `DATABASE_TOOL_DESCRIPTION` — one sentence offering the `operation`-keyed database call and pointing at `describe` for the operation list, the query form, and the column DSL. |
179
- | `DATABASE_TOOL_DESCRIPTION` | const | `string` | Holds the description `createDatabaseTool` advertises — a multi-line guide that teaches a small model the operation list, the serialized query form, and the `TableSpec` column DSL. |
180
- | `DATABASE_TOOL_LIMIT` | const | `number` | Holds the default cap on rows a `records` call returns when the caller omits `query.limit`, `1000` — the database tool's default row ceiling. |
181
- | `DATABASE_TOOL_MUTATIONS` | const | `readonly string[]` | Lists the runtime-frozen database-tool mutation names disabled by `DatabaseToolOptions.readonly`. |
182
- | `RELATION_TOOL_NAME` | const | `string` | Holds the name `createRelationTool` advertises by default, `'relation'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
183
- | `RELATION_TOOL_SUMMARY` | const | `string` | Holds the lean `ToolInterface.summary` `createRelationTool` advertises in place of `RELATION_TOOL_DESCRIPTION` — one sentence offering the `operation`-keyed relationship traversal and pointing at `describe` for the include-path syntax. |
184
- | `RELATION_TOOL_DESCRIPTION` | const | `string` | Holds the description `createRelationTool` advertises — a multi-line guide that teaches a small model the operation list and the flat dot-path `include` syntax. |
185
- | `RELATION_TOOL_LIMIT` | const | `number` | Holds the default cap on rows a `find` or `links` call returns when the caller omits `limit`, `1000` — the relation tool's default row ceiling. |
186
- | `RELATION_TOOL_DEPTH` | const | `number` | Holds the default cap on how many `include` path segments deep a `load` or `find` call may traverse, `3` — the relation tool's default include-depth ceiling. |
187
- | `INFER_TOOL_NAME` | const | `string` | Holds the name `createInferTool` advertises by default, `'infer'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
188
- | `INFER_TOOL_SUMMARY` | const | `string` | Holds the lean `ToolInterface.summary` `createInferTool` advertises in place of `INFER_TOOL_DESCRIPTION` — one sentence offering schema inference from example values and pointing at `describe` for the fields it takes. |
189
- | `INFER_TOOL_DESCRIPTION` | const | `string` | Holds the schema-inference protocol `createInferTool` advertises — the required `samples`, the optional `format`, `enum`, and `candidates` arguments, and a worked example of the bare return and of the `candidates`-wrapped return. |
152
+ | Name | Kind | Signature | Summary |
153
+ | ------------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
154
+ | `AGENT_TOOL_NAME` | const | `"agent"` | Holds the name `createAgentTool` advertises by default, `'agent'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
155
+ | `AGENT_TOOL_DEPTH` | const | `8` | Holds the maximum nesting depth a delegation chain (agent tool → sub-agent → agent tool → …) may reach, `8` — the bound `createAgentTool`'s depth/cycle guard enforces. |
156
+ | `AGENT_TOOL_DESCRIPTION` | const | `string` | Holds the description `createAgentTool` advertises — a short guide covering the required task and optional provider, tools, and system overrides. |
157
+ | `AGENT_TOOL_SUMMARY` | const | `"Delegate a task to a sub-agent and return its result; each call runs one sub-agent turn to completion. Call describe('agent') for the optional provider/tools/system overrides."` | Holds the lean `ToolInterface.summary` `createAgentTool` advertises in place of `AGENT_TOOL_DESCRIPTION` — one sentence offering sub-agent delegation and pointing at `describe` for the optional overrides. |
158
+ | `MAX_WORKFLOW_CHAIN` | const | `8` | Holds the maximum nesting depth a workflow → agent → workflow chain may reach, `8` — the bound `createAgentFunction` and `createWorkflowTool`'s depth/cycle guards enforce. |
159
+ | `WORKFLOW_TOOL_NAME` | const | `"workflow"` | Holds the name `createWorkflowTool` advertises by default, `'workflow'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under, and the name `createAgentFunction` binds the depth/cycle-aware workflow tool under onto a wrapped agent's `context.tools`. |
160
+ | `WORKFLOW_TOOL_FLAT_EXAMPLE` | const | `WorkflowSteps` | Holds a complete flat authoring example — the primary way a small model authors a workflow through `createWorkflowTool`: `{ name, steps: [{ name }] }`. |
161
+ | `WORKFLOW_TOOL_NESTED_EXAMPLE` | const | `WorkflowDefinition` | Holds a minimal nested authoring example — the advanced escape-hatch form a model can use instead of the flat shape: a full `WorkflowDefinition` (`@orkestrel/workflow`). |
162
+ | `WORKFLOW_TOOL_DESCRIPTION` | const | `string` | Holds the description `createWorkflowTool` advertises — the flat authoring form, its worked example, and the advanced nested definition form. |
163
+ | `WORKFLOW_TOOL_SUMMARY` | const | `"Author and run a multi-phase workflow in one call \u2014 phases run in sequence, tasks within a phase run concurrently. Call describe('workflow') for the full authoring schema and examples."` | Holds the lean `ToolInterface.summary` `createWorkflowTool` advertises in place of `WORKFLOW_TOOL_DESCRIPTION` — one sentence offering multi-phase authoring and pointing at `describe` for the authoring schema and its examples. |
164
+ | `WORKSPACE_TOOL_NAME` | const | `"workspace"` | Holds the name `createWorkspaceTool` advertises by default, `'workspace'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
165
+ | `WORKSPACE_TOOL_EXAMPLE` | const | `WorkspaceOperation` | Holds a valid `WorkspaceOperation` object — the canonical example embedded verbatim in `WORKSPACE_TOOL_DESCRIPTION`. |
166
+ | `WORKSPACE_TOOL_DESCRIPTION` | const | `string` | Holds the description `createWorkspaceTool` advertises — the operation-keyed workspace protocol, all supported operations, and worked examples. |
167
+ | `WORKSPACE_TOOL_SUMMARY` | const | `"Read and edit files in a workspace \u2014 one operation per call (read, write, list, search, replace, splice, move, remove, plus workspace switching), chosen by the 'operation' field. Call describe('workspace') for the full operation list and fields."` | Holds the lean `ToolInterface.summary` `createWorkspaceTool` advertises in place of `WORKSPACE_TOOL_DESCRIPTION` — one sentence offering the `operation`-keyed file editing and pointing at `describe` for the operation list and its fields. |
168
+ | `DESCRIBE_TOOL_NAME` | const | `"describe"` | Holds the name `createDescribeTool` advertises by default, `'describe'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
169
+ | `DESCRIBE_TOOL_SUMMARY` | const | `"Return the full description of a named registered tool."` | Holds the lean `ToolInterface.summary` `createDescribeTool` advertises — this tool needs no teaching of its own, so its summary and description are both short. |
170
+ | `DESCRIBE_TOOL_DESCRIPTION` | const | `"Return the full description of a registered tool by its name. Required: name - the registered tool name (see another tool listing for available names)."` | Holds the description `createDescribeTool` advertises — the registered tool `name` it requires, and the full description of that tool it returns. |
171
+ | `PROMPT_TOOL_NAME` | const | `"ask"` | Holds the name `createPromptTool` advertises by default, `'ask'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
172
+ | `PROMPT_TOOL_SUMMARY` | const | `"Ask another terminal a multi-field form and BLOCK until it answers; the call resolves with the values record. Call describe('ask') for the schema."` | Holds the lean `ToolInterface.summary` `createPromptTool` advertises in place of `PROMPT_TOOL_DESCRIPTION` — one sentence offering the blocking multi-field ask and pointing at `describe` for the schema. |
173
+ | `PROMPT_TOOL_DESCRIPTION` | const | `string` | Holds the form protocol `createPromptTool` advertises — the required `to` and `schema`, how a field declares its control and its rules, and a worked example. |
174
+ | `ANSWER_TOOL_NAME` | const | `"answer"` | Holds the name `createAnswerTool` advertises by default, `'answer'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
175
+ | `ANSWER_TOOL_SUMMARY` | const | `"List forms addressed to this terminal, or answer one by id with a values record. Call describe('answer') for the required fields."` | Holds the lean `ToolInterface.summary` `createAnswerTool` advertises in place of `ANSWER_TOOL_DESCRIPTION` — one sentence offering the pending listing and the answer call, and pointing at `describe` for the fields each takes. |
176
+ | `ANSWER_TOOL_DESCRIPTION` | const | `string` | Holds the protocol `createAnswerTool` advertises — the `pending` and `answer` operations and the `values` record an answer supplies, each with a worked example. |
177
+ | `DATABASE_TOOL_NAME` | const | `"database"` | Holds the name `createDatabaseTool` advertises by default, `'database'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
178
+ | `DATABASE_TOOL_SUMMARY` | const | `"Create and query a database \u2014 one operation per call (create, tables, get, records, count, aggregate, add, set, update, remove, destroy), chosen by the 'operation' field. Call describe('database') for the full operation list, the query form, and the column DSL."` | Holds the lean `ToolInterface.summary` `createDatabaseTool` advertises in place of `DATABASE_TOOL_DESCRIPTION` — one sentence offering the `operation`-keyed database call and pointing at `describe` for the operation list, the query form, and the column DSL. |
179
+ | `DATABASE_TOOL_DESCRIPTION` | const | `string` | Holds the description `createDatabaseTool` advertises — a multi-line guide that teaches a small model the operation list, the serialized query form, and the `TableSpec` column DSL. |
180
+ | `DATABASE_TOOL_LIMIT` | const | `1000` | Holds the default cap on rows a `records` call returns when the caller omits `query.limit`, `1000` — the database tool's default row ceiling. |
181
+ | `DATABASE_TOOL_MUTATIONS` | const | `readonly string[]` | Lists the runtime-frozen database-tool mutation names disabled by `DatabaseToolOptions.readonly`. |
182
+ | `RELATION_TOOL_NAME` | const | `"relation"` | Holds the name `createRelationTool` advertises by default, `'relation'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
183
+ | `RELATION_TOOL_SUMMARY` | const | `"Traverse and edit relationships between database rows \u2014 one operation per call (load, find, link, unlink, links), chosen by the 'operation' field. Call describe('relation') for the include-path syntax."` | Holds the lean `ToolInterface.summary` `createRelationTool` advertises in place of `RELATION_TOOL_DESCRIPTION` — one sentence offering the `operation`-keyed relationship traversal and pointing at `describe` for the include-path syntax. |
184
+ | `RELATION_TOOL_DESCRIPTION` | const | `string` | Holds the description `createRelationTool` advertises — a multi-line guide that teaches a small model the operation list and the flat dot-path `include` syntax. |
185
+ | `RELATION_TOOL_LIMIT` | const | `1000` | Holds the default cap on rows a `find` or `links` call returns when the caller omits `limit`, `1000` — the relation tool's default row ceiling. |
186
+ | `RELATION_TOOL_DEPTH` | const | `3` | Holds the default cap on how many `include` path segments deep a `load` or `find` call may traverse, `3` — the relation tool's default include-depth ceiling. |
187
+ | `INFER_TOOL_NAME` | const | `"infer"` | Holds the name `createInferTool` advertises by default, `'infer'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
188
+ | `INFER_TOOL_SUMMARY` | const | `"Infer a JSON Schema (as advertised tool parameters) from one or more example values. Call describe('infer') for the required fields."` | Holds the lean `ToolInterface.summary` `createInferTool` advertises in place of `INFER_TOOL_DESCRIPTION` — one sentence offering schema inference from example values and pointing at `describe` for the fields it takes. |
189
+ | `INFER_TOOL_DESCRIPTION` | const | `string` | Holds the schema-inference protocol `createInferTool` advertises — the required `samples`, the optional `format`, `enum`, and `candidates` arguments, and a worked example of the bare return and of the `candidates`-wrapped return. |
190
190
 
191
191
  ### Types
192
192
 
193
193
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
194
194
 
195
- | Type | Kind | Shape | Summary |
196
- | -------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
197
- | `TaskDraft` | interface | `{ id?, name?, description?, behavior?, retries?, timeout? }` | Represents a draft task — a `TaskDefinition` (`@orkestrel/workflow`) with optional `id` and `name`. |
198
- | `PhaseDraft` | interface | `{ id?, name?, description?, tasks, concurrency?, bail? }` | Represents a draft phase — a `PhaseDefinition` (`@orkestrel/workflow`) with optional `id` and `name` and `TaskDraft` tasks. |
199
- | `WorkflowDraft` | interface | `{ id?, name?, description?, phases, bail? }` | Represents a draft workflow — a `WorkflowDefinition` (`@orkestrel/workflow`) with optional `id` and `name` at the workflow, phase, and task levels. |
200
- | `WorkflowStep` | interface | `{ name }` | Represents one flat step — `{ name }` — the building block of a `WorkflowSteps` blob. |
201
- | `WorkflowSteps` | interface | `{ name?, steps }` | Represents the flat authoring blob `createWorkflowTool` advertises — `{ name?, steps }` — the simplest surface a small model can fill. |
202
- | `WorkflowToolResult` | interface | `{ status, count, durable?, fault? }` | Represents the JSON-safe run summary returned by `createWorkflowTool`. |
203
- | `WorkflowLineage` | type | `readonly string[]` | Represents one immutable workflow/agent call chain — strictly alternating tags, each unique, beginning with a workflow tag. |
204
- | `WorkflowAgents` | type | `Readonly<Record<string, AgentInterface>>` | Represents raw live agents keyed by the workflow function names that invoke them. |
205
- | `AgentFunction` | type | `WorkflowFunction & { category, lineage }` | Represents a contextual agent adapter carrying immutable metadata for Toolbox composition. |
206
- | `AgentFunctionOptions` | interface | `{ runner?, lineage?, functions?, agents?, store? }` | Represents the options for `createAgentFunction` — the opt-in adapter that wraps a live `AgentInterface` (`@orkestrel/agent`) as an `AgentFunction` with immutable lineage metadata and optional nested-workflow composition. |
207
- | `WorkflowToolOptions` | interface | `{ lineage?, functions?, agents?, store? }` | Represents the options for `createWorkflowTool` and `createWorkflowFunctions` — lineage-aware composition of opaque leaves, raw agents, and native workflow persistence. |
208
- | `WorkspaceToolOptions` | interface | `{ name?, description?, manager?, store? }` | Represents the options for `createWorkspaceTool` — either a caller-built `WorkspaceManagerInterface` to drive directly, or a `WorkspaceStoreInterface` the tool constructs a fresh manager over; neither given constructs a manager over `@orkestrel/workspace`'s in-memory store. |
209
- | `WorkspaceOperation` | type | `{ operation: 'read', path } \| { operation: 'list' } \| { operation: 'has', path } \| { operation: 'search', query, regex?, sensitive?, limit? } \| { operation: 'replace', query, replacement, regex?, sensitive?, limit? } \| { operation: 'write', path, content } \| { operation: 'splice', path, content, fromLine, fromColumn, toLine, toColumn } \| { operation: 'prepend', path, content } \| { operation: 'append', path, content } \| { operation: 'move', from, to } \| { operation: 'remove', path } \| { operation: 'workspaces' } \| { operation: 'switch', id }` | Represents one operation an agent invokes through `createWorkspaceTool` — a flat, descriptive tagged union over the workspace edit, read, and navigation actions, discriminated by the `operation` literal (a discriminant is named for its axis — the action being performed — never `kind`). |
210
- | `AgentToolOptions` | interface | `{ name?, description?, provider?, tools?, system?, depth?, ancestry?, store? }` | Represents the options for `createAgentTool` — the sub-agent delegation defaults, the nesting-depth / cycle guard bookkeeping, and the advertised tool overrides. |
211
- | `AgentToolArguments` | interface | `{ task, provider?, tools?, system? }` | Represents the flat args `createAgentTool` accepts — a delegated `task` plus the minimal optional `AgentJobInput` (`@orkestrel/agent`) fields a caller may override per-call. |
212
- | `ToolboxErrorCode` | type | `'TOOL' \| 'DEPTH' \| 'DEADLOCK' \| 'EXPIRE' \| 'ANSWER' \| 'DATABASE' \| 'RELATION'` | Represents the machine-readable code a thrown `ToolboxError` carries — a thrown, typed, code-bearing error, never a `{ error }` return. |
213
- | `DescribeToolArguments` | interface | `{ name }` | Represents the flat args `createDescribeTool` accepts — the registered tool `name` whose full `description` a model wants back. |
214
- | `PromptToolOptions` | interface | `{ manager, from, name?, description? }` | Represents the options for `createPromptTool` — the live `TerminalManagerInterface` (`@orkestrel/terminal`) to `ask` through, the terminal name `from`, and the advertised tool overrides. |
215
- | `AnswerToolOptions` | interface | `{ manager, to, name?, description? }` | Represents the options for `createAnswerTool` — the live `TerminalManagerInterface` (`@orkestrel/terminal`) to list / answer prompts through, the terminal name `to`, and the advertised tool overrides. |
216
- | `ColumnPrimitive` | type | `'string' \| 'integer' \| 'number' \| 'boolean'` | Represents one column's declared primitive — a shorthand, or `integer` for a whole-number `number`. |
217
- | `ColumnSpec` | type | `ColumnPrimitive \| { primitive, optional? }` | Represents one table column's spec — either a bare `ColumnPrimitive` shorthand, or `{ primitive, optional }` when the column may be absent from a row. |
218
- | `TableSpec` | type | `Readonly<Record<string, { columns }>>` | Represents a database's table layout — one entry per table, each a flat map of column name to `ColumnSpec`. The small-model-facing DSL `expandTables` compiles into an `@orkestrel/database` `TableMap`. |
219
- | `DatabaseDefinition` | interface | `{ id, driver, tables, primary?, indexes?, version? }` | Represents one database's config-only definition — an `id`, a `driver`, and a `TableSpec`, with optional `primary`, `indexes`, and `version` schema configuration. |
220
- | `DatabaseDefinitionRow` | interface | `{ id, definition }` | Represents one opaque persisted row — the shape a definition-row-backed `TableInterface` store reads/writes; `definition` is narrowed with `isDatabaseDefinition` on read. |
221
- | `DefinitionStoreInterface` | interface | `{} plus get, set, delete` | Represents the point-access persistence seam for `DatabaseDefinition` configs — the twin of `@orkestrel/terminal`'s `TerminalStoreInterface`, storing a database's config-only blueprint rather than a live handle. Every primitive is async; `delete` of an absent id is a no-op. |
222
- | `DatabaseQueryInput` | interface | `{ conditions?, order?, limit?, offset? }` | Represents the serialized wire query a database-tool call carries — the parsed form of `queryShape`, which `normalizeQuery` normalizes into a live `@orkestrel/database` `QueryInput`. |
223
- | `ClampedQuery` | interface | `{ query, limit }` | Represents the probe query and effective row limit `clampQuery` returns. |
224
- | `DatabaseToolOptions` | interface | `{ name?, description?, databases?, store?, drivers?, generator?, limit?, timeout?, readonly? }` | Represents the options for `createDatabaseTool` — the live handles, definition store, driver registry, key generator, row cap, timeout, and readonly gate the tool composes. |
225
- | `RelationToolOptions` | interface | `{ name?, description?, managers, limit?, depth? }` | Represents the options for `createRelationTool` — the required live `RelationManagerInterface` registry a call addresses, the row cap, and the `include` depth cap. |
226
- | `InferToolOptions` | interface | `{ name?, description? }` | Represents the options for `createInferTool` — advertised name and description overrides only; `format` and `enum` are runtime call arguments (see `inferToolShape`), not construction-time options, because a model chooses them per call. |
227
- | `EndpointHandler` | type | `(args: Readonly<Record<string, unknown>>, context: ToolContext) => Promise<unknown> \| unknown` | Represents the handler `EndpointDefinition.execute` implements — it mirrors `@orkestrel/tool`'s `ToolOptions.execute` signature exactly, so `createEndpointTool` forwards the execution context it receives to the handler unchanged and a handler that reads `context.signal` observes the caller's cancellation. |
228
- | `EndpointDefinition` | interface | `{ name, description, samples, execute }` | Represents one concrete endpoint `createEndpointTool` wraps as an LLM-callable `ToolInterface` — the advertised identity, a non-empty set of example values its `parameters` are inferred from, and the local handler that runs a call. |
229
- | `EndpointToolOptions` | interface | `{ format?, enum?, validate? }` | Represents the construction-time tuning for `createEndpointTool` — the inferred `parameters` schema's `format` and `enum` constraints, and whether that same schema is enforced at `execute` time. |
195
+ | Name | Kind | Signature | Summary |
196
+ | -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
197
+ | `TaskDraft` | interface | `{ id?, name?, description?, behavior?, retries?, timeout? }` | Represents a draft task — a `TaskDefinition` (`@orkestrel/workflow`) with optional `id` and `name`. |
198
+ | `PhaseDraft` | interface | `{ id?, name?, description?, tasks, concurrency?, bail? }` | Represents a draft phase — a `PhaseDefinition` (`@orkestrel/workflow`) with optional `id` and `name` and `TaskDraft` tasks. |
199
+ | `WorkflowDraft` | interface | `{ id?, name?, description?, phases, bail? }` | Represents a draft workflow — a `WorkflowDefinition` (`@orkestrel/workflow`) with optional `id` and `name` at the workflow, phase, and task levels. |
200
+ | `WorkflowStep` | interface | `{ name }` | Represents one flat step — `{ name }` — the building block of a `WorkflowSteps` blob. |
201
+ | `WorkflowSteps` | interface | `{ name?, steps }` | Represents the flat authoring blob `createWorkflowTool` advertises — `{ name?, steps }` — the simplest surface a small model can fill. |
202
+ | `WorkflowToolResult` | interface | `{ status, count, durable?, fault? }` | Represents the JSON-safe run summary returned by `createWorkflowTool`. |
203
+ | `WorkflowLineage` | type | `readonly string[]` | Represents one immutable workflow/agent call chain — strictly alternating tags, each unique, beginning with a workflow tag. |
204
+ | `WorkflowAgents` | type | `Readonly<Record<string, AgentInterface>>` | Represents raw live agents keyed by the workflow function names that invoke them. |
205
+ | `AgentFunction` | type | `WorkflowFunction & { readonly category: 'agent'; readonly lineage: WorkflowLineage; }` | Represents a contextual agent adapter carrying immutable metadata for Toolbox composition. |
206
+ | `AgentFunctionOptions` | interface | `{ runner?, lineage?, functions?, agents?, store? }` | Represents the options for `createAgentFunction` — the opt-in adapter that wraps a live `AgentInterface` (`@orkestrel/agent`) as an `AgentFunction` with immutable lineage metadata and optional nested-workflow composition. |
207
+ | `WorkflowToolOptions` | interface | `{ lineage?, functions?, agents?, store? }` | Represents the options for `createWorkflowTool` and `createWorkflowFunctions` — lineage-aware composition of opaque leaves, raw agents, and native workflow persistence. |
208
+ | `WorkspaceToolOptions` | interface | `{ name?, description?, manager?, store? }` | Represents the options for `createWorkspaceTool` — either a caller-built `WorkspaceManagerInterface` to drive directly, or a `WorkspaceStoreInterface` the tool constructs a fresh manager over; neither given constructs a manager over `@orkestrel/workspace`'s in-memory store. |
209
+ | `WorkspaceOperation` | type | `{ readonly operation: 'read'; readonly path: string; } \| { readonly operation: 'list'; } \| { readonly operation: 'has'; readonly path: string; } \| { readonly operation: 'search'; readonly query: string; readonly regex?: boolean; readonly sensitive?: boolean; readonly limit?: number; } \| { readonly operation: 'replace'; readonly query: string; readonly replacement: string; readonly regex?: boolean; readonly sensitive?: boolean; readonly limit?: number; } \| { readonly operation: 'write'; readonly path: string; readonly content: string; } \| { readonly operation: 'splice'; readonly path: string; readonly content: string; readonly fromLine: number; readonly fromColumn: number; readonly toLine: number; readonly toColumn: number; } \| { readonly operation: 'prepend'; readonly path: string; readonly content: string; } \| { readonly operation: 'append'; readonly path: string; readonly content: string; } \| { readonly operation: 'move'; readonly from: string; readonly to: string; } \| { readonly operation: 'remove'; readonly path: string; } \| { readonly operation: 'workspaces'; } \| { readonly operation: 'switch'; readonly id: string; }` | Represents one operation an agent invokes through `createWorkspaceTool` — a flat, descriptive tagged union over the workspace edit, read, and navigation actions, discriminated by the `operation` literal (a discriminant is named for its axis — the action being performed — never `kind`). |
210
+ | `AgentToolOptions` | interface | `{ name?, description?, provider?, tools?, system?, depth?, ancestry?, store? }` | Represents the options for `createAgentTool` — the sub-agent delegation defaults, the nesting-depth / cycle guard bookkeeping, and the advertised tool overrides. |
211
+ | `AgentToolArguments` | interface | `{ task, provider?, tools?, system? }` | Represents the flat args `createAgentTool` accepts — a delegated `task` plus the minimal optional `AgentJobInput` (`@orkestrel/agent`) fields a caller may override per-call. |
212
+ | `ToolboxErrorCode` | type | `'TOOL' \| 'DEPTH' \| 'DEADLOCK' \| 'EXPIRE' \| 'ANSWER' \| 'DATABASE' \| 'RELATION'` | Represents the machine-readable code a thrown `ToolboxError` carries — a thrown, typed, code-bearing error, never a `{ error }` return. |
213
+ | `DescribeToolArguments` | interface | `{ name }` | Represents the flat args `createDescribeTool` accepts — the registered tool `name` whose full `description` a model wants back. |
214
+ | `PromptToolOptions` | interface | `{ manager, from, name?, description? }` | Represents the options for `createPromptTool` — the live `TerminalManagerInterface` (`@orkestrel/terminal`) to `ask` through, the terminal name `from`, and the advertised tool overrides. |
215
+ | `AnswerToolOptions` | interface | `{ manager, to, name?, description? }` | Represents the options for `createAnswerTool` — the live `TerminalManagerInterface` (`@orkestrel/terminal`) to list / answer prompts through, the terminal name `to`, and the advertised tool overrides. |
216
+ | `ColumnPrimitive` | type | `'string' \| 'integer' \| 'number' \| 'boolean'` | Represents one column's declared primitive — a shorthand, or `integer` for a whole-number `number`. |
217
+ | `ColumnSpec` | type | `ColumnPrimitive \| Readonly<{ readonly primitive: ColumnPrimitive; readonly optional?: boolean; }>` | Represents one table column's spec — either a bare `ColumnPrimitive` shorthand, or `{ primitive, optional }` when the column may be absent from a row. |
218
+ | `TableSpec` | type | `Readonly<Record<string, Readonly<{ readonly columns: Readonly<Record<string, ColumnSpec>>; }>>>` | Represents a database's table layout — one entry per table, each a flat map of column name to `ColumnSpec`. The small-model-facing DSL `expandTables` compiles into an `@orkestrel/database` `TableMap`. |
219
+ | `DatabaseDefinition` | interface | `{ id, driver, tables, primary?, indexes?, version? }` | Represents one database's config-only definition — an `id`, a `driver`, and a `TableSpec`, with optional `primary`, `indexes`, and `version` schema configuration. |
220
+ | `DatabaseDefinitionRow` | interface | `{ id, definition }` | Represents one opaque persisted row — the shape a definition-row-backed `TableInterface` store reads/writes; `definition` is narrowed with `isDatabaseDefinition` on read. |
221
+ | `DefinitionStoreInterface` | interface | `{ get(), set(), delete() }` | Represents the point-access persistence seam for `DatabaseDefinition` configs — the twin of `@orkestrel/terminal`'s `TerminalStoreInterface`, storing a database's config-only blueprint rather than a live handle. Every primitive is async; `delete` of an absent id is a no-op. |
222
+ | `DatabaseQueryInput` | interface | `{ conditions?, order?, limit?, offset? }` | Represents the serialized wire query a database-tool call carries — the parsed form of `queryShape`, which `normalizeQuery` normalizes into a live `@orkestrel/database` `QueryInput`. |
223
+ | `ClampedQuery` | interface | `{ query, limit }` | Represents the probe query and effective row limit `clampQuery` returns. |
224
+ | `DatabaseToolOptions` | interface | `{ name?, description?, databases?, store?, drivers?, generator?, limit?, timeout?, readonly? }` | Represents the options for `createDatabaseTool` — the live handles, definition store, driver registry, key generator, row cap, timeout, and readonly gate the tool composes. |
225
+ | `RelationToolOptions` | interface | `{ name?, description?, managers, limit?, depth? }` | Represents the options for `createRelationTool` — the required live `RelationManagerInterface` registry a call addresses, the row cap, and the `include` depth cap. |
226
+ | `InferToolOptions` | interface | `{ name?, description? }` | Represents the options for `createInferTool` — advertised name and description overrides only; `format` and `enum` are runtime call arguments (see `inferToolShape`), not construction-time options, because a model chooses them per call. |
227
+ | `EndpointHandler` | type | `(args: Readonly<Record<string, unknown>>, context: ToolContext) => Promise<unknown> \| unknown` | Represents the handler `EndpointDefinition.execute` implements — it mirrors `@orkestrel/tool`'s `ToolOptions.execute` signature exactly, so `createEndpointTool` forwards the execution context it receives to the handler unchanged and a handler that reads `context.signal` observes the caller's cancellation. |
228
+ | `EndpointDefinition` | interface | `{ name, description, samples, execute }` | Represents one concrete endpoint `createEndpointTool` wraps as an LLM-callable `ToolInterface` — the advertised identity, a non-empty set of example values its `parameters` are inferred from, and the local handler that runs a call. |
229
+ | `EndpointToolOptions` | interface | `{ format?, enum?, validate? }` | Represents the construction-time tuning for `createEndpointTool` — the inferred `parameters` schema's `format` and `enum` constraints, and whether that same schema is enforced at `execute` time. |
230
230
 
231
231
  ### Server routes
232
232
 
@@ -236,7 +236,7 @@ The POST endpoint takes `{ id, values }`, admits the body only when `id` is a no
236
236
 
237
237
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A `Shape` cell holds the constant's declared type.
238
238
 
239
- | API | Kind | Shape | Summary |
239
+ | Name | Kind | Signature | Summary |
240
240
  | ----------------------- | --------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
241
241
  | `createTerminalRoutes` | function | `(manager: TerminalManagerInterface, options?: TerminalRoutesOptions) => readonly TerminalRoute[]` | Builds the GET SSE stream and POST answer routes that bridge a terminal manager onto the wire. |
242
242
  | `TerminalRouteMethod` | type | `'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE' \| 'HEAD' \| 'OPTIONS'` | Represents the HTTP method literal a `TerminalRoute` declares — the same union `@orkestrel/router`'s `Method` type accepts. |
@@ -244,8 +244,8 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
244
244
  | `TerminalRoute` | interface | `{ method, path, handler }` | Represents one structural route record `createTerminalRoutes` returns — a plain `{ method, path, handler }` shape carrying no dependency on `@orkestrel/router`'s own `Route` type, so a consumer mounts it against any router that accepts a two-arg `(request, context) => Response \| Promise<Response>` handler keyed by `method` and `path`. |
245
245
  | `TerminalRoutesOptions` | interface | `{ path?, token?, keepalive?, timer?, limit? }` | Represents the options `createTerminalRoutes` takes — the shared route, authorization, keepalive, timer, and body-limit configuration both routes read. |
246
246
  | `TerminalToken` | type | `string \| ((value: string \| undefined) => boolean)` | Represents the `token` gate `TerminalRoutesOptions` may configure — a plain string compared for equality against the `x-orkestrel-token` header, or a validator function the consumer fully controls, enabling the expiry and rotation a fixed string cannot express (a JWT `exp` check, a revocation-list lookup, anything time-varying). `undefined` disables the auth check entirely. |
247
- | `TERMINAL_ROUTES_PATH` | const | `string` | Holds the default `:name`-templated path `createTerminalRoutes` mounts its GET (SSE) and POST (answer) routes under, `/terminals/:name`. |
248
- | `TERMINAL_KEEPALIVE_MS` | const | `number` | Holds the default SSE keepalive interval `createTerminalRoutes` arms per open connection, `15_000` ms — a `:` comment ping a conforming SSE parser ignores, keeping intermediary proxies from timing out an otherwise-idle stream. |
247
+ | `TERMINAL_ROUTES_PATH` | const | `"/terminals/:name"` | Holds the default `:name`-templated path `createTerminalRoutes` mounts its GET (SSE) and POST (answer) routes under, `/terminals/:name`. |
248
+ | `TERMINAL_KEEPALIVE_MS` | const | `15000` | Holds the default SSE keepalive interval `createTerminalRoutes` arms per open connection, `15_000` ms — a `:` comment ping a conforming SSE parser ignores, keeping intermediary proxies from timing out an otherwise-idle stream. |
249
249
 
250
250
  > A reconnecting SSE client replays every pending form from the top on every (re)connect (the GET handler's replay loop), so a raw `EventSource` (or any hand-rolled consumer that isn't `PromptClient`) must dedupe `pending` frames by their SSE `id` — the same form id may arrive more than once across a reconnect. `PromptClient` (`@orkestrel/terminal`) already does this; a consumer bypassing it does not get the dedupe for free.
251
251
  >