@orkestrel/scaffold 0.0.133 → 0.0.135
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.
- package/dist/agents/skills/orkestrel-dispatch/scripts/bench.js +61 -96
- package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +48 -76
- package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +27 -66
- package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +31 -64
- package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +43 -57
- package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +43 -86
- package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +68 -104
- package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +35 -69
- package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +47 -84
- package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +134 -116
- package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +38 -90
- package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +39 -103
- package/dist/agents/skills/orkestrel-harden/scripts/measure.js +40 -89
- package/dist/agents/skills/orkestrel-harden/scripts/titles.js +41 -87
- package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +43 -88
- package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1568 -213
- package/dist/agents/skills/orkestrel-publish/scripts/compare.js +40 -60
- package/dist/agents/skills/orkestrel-publish/scripts/pins.js +47 -81
- package/dist/agents/skills/orkestrel-publish/scripts/steps.js +66 -104
- package/dist/agents/skills/orkestrel-publish/scripts/swap.js +74 -88
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +387 -109
- package/dist/agents/skills/orkestrel-publish/scripts/window.js +55 -96
- package/dist/agents/skills/orkestrel-scout/scripts/map.js +54 -101
- package/dist/bin/main.js +275 -33
- package/dist/bin/main.js.map +1 -1
- package/dist/host/AGENTS.md +1 -1
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +81 -97
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +64 -72
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +41 -63
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +56 -79
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +61 -74
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +59 -89
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +87 -106
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +57 -76
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +73 -88
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +2 -2
- package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +167 -119
- package/dist/host/agents/skills/orkestrel-harden/references/methods.md +1 -1
- package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +58 -75
- package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +55 -99
- package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +59 -90
- package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +60 -80
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +71 -108
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1990 -274
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +28 -7
- package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
- package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
- package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
- package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +483 -127
- package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
- package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
- package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
- package/dist/host/claude/agents/orkestrel.md +16 -16
- package/dist/host/claude/rules/architecture.md +1 -1
- package/dist/host/claude/rules/documentation.md +1 -1
- package/dist/host/claude/rules/patterns.md +7 -4
- package/dist/host/claude/rules/styles.md +1 -1
- package/dist/host/claude/rules/tests.md +3 -3
- package/dist/host/claude/rules/workspace.md +50 -37
- package/dist/host/configs/helpers.ts +117 -71
- package/dist/host/dotfiles/oxlintrc.json +6 -0
- package/dist/host/guides/agent.md +989 -395
- package/dist/host/guides/database.md +357 -342
- package/dist/host/guides/form.md +79 -4
- package/dist/host/guides/middleware.md +5 -5
- package/dist/host/guides/ollama.md +41 -42
- package/dist/host/guides/scaffold.md +170 -70
- package/dist/host/guides/study.md +12 -12
- package/dist/host/guides/table.md +20 -6
- package/dist/host/guides/test.md +166 -52
- package/dist/host/guides/toolbox.md +127 -81
- package/dist/host/guides/workspace.md +21 -14
- package/dist/host/manifest.json +54 -54
- package/dist/host/tests/config.test.ts +251 -7
- package/dist/host/tests/policy.test.ts +14 -21
- package/dist/host/tests/setupPolicy.ts +43 -36
- package/dist/src/core/index.cjs +533 -139
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +223 -16
- package/dist/src/core/index.d.ts +223 -16
- package/dist/src/core/index.js +524 -139
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +23 -14
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +3 -2
- package/dist/src/server/index.d.ts +3 -2
- package/dist/src/server/index.js +24 -15
- package/dist/src/server/index.js.map +1 -1
- package/package.json +2 -2
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
The runtime supplies `ToolInterface`, registry execution, and result isolation; see [`tool.md`](tool.md). This package supplies the concrete behavior through one factory per tool.
|
|
6
6
|
|
|
7
|
-
`createWorkflowTool` and `createWorkspaceTool` own their full handler logic (the workflow authoring surface and the workspace editing surface respectively). The workflow tool composes opaque host `functions` plus raw live `agents` through `createWorkflowFunctions`, then forwards that frozen target registry and the optional `store` to `@orkestrel/workflow`, whose runner owns named-run drivability, checkpoint persistence, and `durable` / `fault`; the workspace tool retains its distinct manager/store composition. `createAgentTool` (sub-agent delegation over an `AgentRegistryInterface`) has its own `ConversationStoreInterface` persistence slot. The workflow, workspace, and agent tools additionally advertise a lean `summary` (`@orkestrel/tool`'s `ToolInterface.summary` / `ToolManagerInterface.definitions()` projection) in place of their full teaching `description`; `createDescribeTool` is the on-demand expansion seam. `createToolFunction` adapts an ordinary registered runtime tool, while `createAgentFunction` returns a frozen metadata-bearing adapter and uses Agent-owned `agentResultToJSON` for the exact result projection. The authoring umbrella (`WorkflowSteps` / `WorkflowDraft` shapes, `createWorkflowDraftContract`, lineage helpers, `expandSteps` / `completeDraft`, `summarizeWorkflow`, `MAX_WORKFLOW_CHAIN`) lets a small model author a whole recursion-safe tree in one call.
|
|
7
|
+
`createWorkflowTool` and `createWorkspaceTool` own their full handler logic (the workflow authoring surface and the workspace editing surface respectively). The workflow tool composes opaque host `functions` plus raw live `agents` through `createWorkflowFunctions`, then forwards that frozen target registry and the optional `store` to `@orkestrel/workflow`, whose runner owns named-run drivability, checkpoint persistence, and `durable` / `fault`; the workspace tool retains its distinct manager/store composition. `createAgentTool` (sub-agent delegation over an `AgentRegistryInterface`) takes a call's `task` alone, runs the sub-agent its options fix, and has its own `ConversationStoreInterface` persistence slot. The workflow, workspace, and agent tools additionally advertise a lean `summary` (`@orkestrel/tool`'s `ToolInterface.summary` / `ToolManagerInterface.definitions()` projection) in place of their full teaching `description`; `createDescribeTool` is the on-demand expansion seam. `createToolFunction` adapts an ordinary registered runtime tool, while `createAgentFunction` returns a frozen metadata-bearing adapter and uses Agent-owned `agentResultToJSON` for the exact result projection. The authoring umbrella (`WorkflowSteps` / `WorkflowDraft` shapes, `createWorkflowDraftContract`, lineage helpers, `expandSteps` / `completeDraft`, `summarizeWorkflow`, `MAX_WORKFLOW_CHAIN`) lets a small model author a whole recursion-safe tree in one call.
|
|
8
8
|
|
|
9
9
|
`createPromptTool` / `createAnswerTool` are the ask and answer halves of a terminal-mediated human-in-the-loop seam over a live `TerminalManagerInterface` (`@orkestrel/terminal`). One call asks a whole multi-field form, not a single question. `createPromptTool` takes `{ to, schema }` per call, parses the model-supplied `schema` with `@orkestrel/form`'s `parseForm`, constructs the live form with `createForm`, and blocks the calling agent turn until the addressed terminal answers (`from` fixed at construction) — resolving with one `FormValues` record keyed by field name, re-surfacing a prompt cycle as `DEADLOCK` and an unanswered expiry as `EXPIRE`. `createAnswerTool` lists the forms addressed to a fixed `to` terminal as `{ id, from, schema }` records and answers one by `{ id, values }`, narrowing the model-supplied `values` with `@orkestrel/form`'s `isFormValues` before applying it, re-surfacing a failed apply as `ANSWER`. `createTerminalRoutes` ([`src/server`](../src/server), the `@src/server` barrel) is the wire bridge for the same manager — structural `{ method, path, handler }` route records, a GET SSE stream and a POST answer over one shared `:name`-templated path, carrying no dependency on `@orkestrel/router`'s own `Route` type so a consumer mounts them against any router accepting that two-arg handler shape, and byte-compatible with `@orkestrel/terminal`'s own `PromptClient` (same GET url streams, same POST url answers, same `{ id, values }` body, same JSON answer `Result` body, same `x-orkestrel-token` header).
|
|
10
10
|
|
|
@@ -23,8 +23,8 @@ Source: [`src/core`](../src/core) (the tool factories) and [`src/server`](../src
|
|
|
23
23
|
| `createWorkflowFunctions` | function | `(runner: WorkflowRunnerInterface, options?: WorkflowToolOptions) => WorkflowRegistry` | Composes opaque host functions and raw agents into one immutable workflow registry. |
|
|
24
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
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
|
|
27
|
-
| `createAgentTool` | function | `(registry: AgentRegistryInterface, options
|
|
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 one workspace the call acts on, 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
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
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
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. |
|
|
@@ -94,7 +94,10 @@ Pure, side-effect-free, exhaustively unit-tested under AGENTS' export-and-test-r
|
|
|
94
94
|
| `requireToolCall` | function | `<T>(contract: ContractInterface<T>, value: unknown) => T` | Reads a call's arguments through a compiled contract, or refuses them with what to send. |
|
|
95
95
|
| `buildArgumentRefusal` | function | `(schema: JSONSchema, value: unknown, faults: readonly AuditFault[]) => ToolError` | Builds an argument refusal from the supplied faults, auditing the schema when no faults were supplied. |
|
|
96
96
|
| `resolveBound` | function | `(value: number \| undefined, fallback: number, subject: string) => number` | Picks the effective value of a positive numeric tool option: the configured value when it is a positive safe integer, and the fallback when it is omitted. |
|
|
97
|
-
| `
|
|
97
|
+
| `readToolCaller` | function | `(value: unknown) => AgentCaller \| undefined` | Reads the caller a workspace tool call carries as an owned `AgentCaller`, refusing a value that holds a `workspace` key and is not one. |
|
|
98
|
+
| `resolveToolWorkspace` | function | `(manager: WorkspaceManagerInterface, caller: AgentCaller \| undefined) => WorkspaceInterface \| undefined` | Resolves the workspace a workspace tool call acts on: the Agent caller's workspace when it is an instance the tool's manager holds, `undefined` for a run that shows none, and the manager's active workspace when no Agent caller is present. |
|
|
99
|
+
| `requireToolWorkspace` | function | `(workspace: WorkspaceInterface \| undefined, caller: AgentCaller \| undefined, operation: string) => WorkspaceInterface` | Returns the workspace an operation that needs one acts on, or refuses with what the caller can do. |
|
|
100
|
+
| `requireListedPath` | function | `(files: readonly string[] \| undefined, path: string) => void` | Refuses a path the caller's files list omits, with one text whether or not a file sits there. |
|
|
98
101
|
| `describeDefinitionRefusal` | function | `(id: string, faults: readonly AuditFault[]) => string` | Describes a stored definition this package refuses to read, naming its first fault and the remedy. |
|
|
99
102
|
| `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`. |
|
|
100
103
|
| `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). |
|
|
@@ -124,37 +127,37 @@ The `TableSpec` column DSL compiled into the live `@orkestrel/database` `TableMa
|
|
|
124
127
|
|
|
125
128
|
The shape values each `create*Tool` factory (and `createWorkflowDraftContract`) compiles into the lockstep guard / parser / JSON Schema outputs under AGENTS' narrow-untrusted-input-with-guards rule; `agentToolShape` agrees with the hand-written `AgentToolArguments`, the source of truth.
|
|
126
129
|
|
|
127
|
-
| Name | Kind | Signature | Summary
|
|
128
|
-
| ---------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
129
|
-
| `agentToolShape` | const | `import("@orkestrel/contract").ObjectShape<{ task: import("@orkestrel/contract").StringShape;
|
|
130
|
-
| `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.
|
|
131
|
-
| `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`.
|
|
132
|
-
| `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.
|
|
133
|
-
| `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`.
|
|
134
|
-
| `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 }] }`.
|
|
135
|
-
| `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
|
|
136
|
-
| `describeToolShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; }, false>` | Describes the shape of `DescribeToolArguments` — `createDescribeTool`'s advertised `parameters`.
|
|
137
|
-
| `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.
|
|
138
|
-
| `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.
|
|
139
|
-
| `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'`.
|
|
140
|
-
| `columnPrimitiveShape` | const | `import("@orkestrel/contract").LiteralShape<readonly ["string", "integer", "number", "boolean"]>` | Describes a `ColumnPrimitive` literal — the leaf `columnSpecShape` wraps.
|
|
141
|
-
| `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 }`.
|
|
142
|
-
| `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`.
|
|
143
|
-
| `primaryShape` | const | `import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").StringShape>` | Describes a `DatabaseDefinition`'s `primary` map — table name to its primary-key column.
|
|
144
|
-
| `indexesShape` | const | `import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>>>` | Describes a `DatabaseDefinition`'s `indexes` map — table name to its index column groups.
|
|
145
|
-
| `definitionShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; driver: 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>>; 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>` | Describes a stored `DatabaseDefinition` exactly: the owned record `DatabaseDefinitionStore` reads and writes.
|
|
146
|
-
| `definitionContract` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ id: string; driver: string; tables: { readonly [k: string]: Readonly<{ columns: { readonly [k: string]: "boolean" \| "integer" \| "number" \| "string" \| Readonly<{ primitive: "boolean" \| "integer" \| "number" \| "string"; } & { optional?: boolean; }>; }; } & {}>; }; } & { primary?: { readonly [k: string]: string; }; indexes?: { readonly [k: string]: readonly (readonly string[])[]; }; version?: number; }>>` | Holds the compiled `definitionShape`, whose `audit` fills the faults a refused stored definition carries.
|
|
147
|
-
| `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.
|
|
148
|
-
| `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.
|
|
149
|
-
| `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.
|
|
150
|
-
| `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.
|
|
151
|
-
| `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.
|
|
152
|
-
| `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.
|
|
153
|
-
| `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'`.
|
|
154
|
-
| `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.
|
|
155
|
-
| `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`.
|
|
156
|
-
| `managerShape` | const | `import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>` | Describes which registered relation manager to address — omitted resolves to the sole registered manager.
|
|
157
|
-
| `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.
|
|
130
|
+
| Name | Kind | Signature | Summary |
|
|
131
|
+
| ---------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
132
|
+
| `agentToolShape` | const | `import("@orkestrel/contract").ObjectShape<{ task: import("@orkestrel/contract").StringShape; }, false>` | Describes the shape of `AgentToolArguments` — `createAgentTool`'s advertised `parameters`. |
|
|
133
|
+
| `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. |
|
|
134
|
+
| `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`. |
|
|
135
|
+
| `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. |
|
|
136
|
+
| `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`. |
|
|
137
|
+
| `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 }] }`. |
|
|
138
|
+
| `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>]>` | Describes the shape of a `WorkspaceOperation` — a descriptive tagged union over the workspace edit and read 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`. |
|
|
139
|
+
| `describeToolShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; }, false>` | Describes the shape of `DescribeToolArguments` — `createDescribeTool`'s advertised `parameters`. |
|
|
140
|
+
| `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. |
|
|
141
|
+
| `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. |
|
|
142
|
+
| `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'`. |
|
|
143
|
+
| `columnPrimitiveShape` | const | `import("@orkestrel/contract").LiteralShape<readonly ["string", "integer", "number", "boolean"]>` | Describes a `ColumnPrimitive` literal — the leaf `columnSpecShape` wraps. |
|
|
144
|
+
| `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 }`. |
|
|
145
|
+
| `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`. |
|
|
146
|
+
| `primaryShape` | const | `import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").StringShape>` | Describes a `DatabaseDefinition`'s `primary` map — table name to its primary-key column. |
|
|
147
|
+
| `indexesShape` | const | `import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>>>` | Describes a `DatabaseDefinition`'s `indexes` map — table name to its index column groups. |
|
|
148
|
+
| `definitionShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; driver: 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>>; 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>` | Describes a stored `DatabaseDefinition` exactly: the owned record `DatabaseDefinitionStore` reads and writes. |
|
|
149
|
+
| `definitionContract` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ id: string; driver: string; tables: { readonly [k: string]: Readonly<{ columns: { readonly [k: string]: "boolean" \| "integer" \| "number" \| "string" \| Readonly<{ primitive: "boolean" \| "integer" \| "number" \| "string"; } & { optional?: boolean; }>; }; } & {}>; }; } & { primary?: { readonly [k: string]: string; }; indexes?: { readonly [k: string]: readonly (readonly string[])[]; }; version?: number; }>>` | Holds the compiled `definitionShape`, whose `audit` fills the faults a refused stored definition carries. |
|
|
150
|
+
| `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. |
|
|
151
|
+
| `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. |
|
|
152
|
+
| `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. |
|
|
153
|
+
| `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. |
|
|
154
|
+
| `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. |
|
|
155
|
+
| `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. |
|
|
156
|
+
| `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'`. |
|
|
157
|
+
| `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. |
|
|
158
|
+
| `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`. |
|
|
159
|
+
| `managerShape` | const | `import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>` | Describes which registered relation manager to address — omitted resolves to the sole registered manager. |
|
|
160
|
+
| `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. |
|
|
158
161
|
|
|
159
162
|
### Constants
|
|
160
163
|
|
|
@@ -162,8 +165,8 @@ The shape values each `create*Tool` factory (and `createWorkflowDraftContract`)
|
|
|
162
165
|
| ------------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
163
166
|
| `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. |
|
|
164
167
|
| `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. |
|
|
165
|
-
| `AGENT_TOOL_DESCRIPTION` | const | `string` | Holds the description `createAgentTool` advertises — a short guide covering the
|
|
166
|
-
| `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
|
|
168
|
+
| `AGENT_TOOL_DESCRIPTION` | const | `string` | Holds the description `createAgentTool` advertises — a short guide covering the one field a call sends, `task`, and that the host fixes the sub-agent. |
|
|
169
|
+
| `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 full description."` | 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 full description. |
|
|
167
170
|
| `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. |
|
|
168
171
|
| `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`. |
|
|
169
172
|
| `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 }] }`. |
|
|
@@ -173,7 +176,7 @@ The shape values each `create*Tool` factory (and `createWorkflowDraftContract`)
|
|
|
173
176
|
| `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. |
|
|
174
177
|
| `WORKSPACE_TOOL_EXAMPLE` | const | `WorkspaceOperation` | Holds a valid `WorkspaceOperation` object — the canonical example embedded verbatim in `WORKSPACE_TOOL_DESCRIPTION`. |
|
|
175
178
|
| `WORKSPACE_TOOL_DESCRIPTION` | const | `string` | Holds the description `createWorkspaceTool` advertises — the operation-keyed workspace protocol, all supported operations, and worked examples. |
|
|
176
|
-
| `WORKSPACE_TOOL_SUMMARY` | const | `"Read and edit files in a workspace \u2014 one operation per call (read, write, list, search, replace, splice, move, remove
|
|
179
|
+
| `WORKSPACE_TOOL_SUMMARY` | const | `"Read and edit files in a workspace \u2014 one operation per call (read, write, list, search, replace, splice, move, remove), 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. |
|
|
177
180
|
| `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. |
|
|
178
181
|
| `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. |
|
|
179
182
|
| `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. |
|
|
@@ -199,41 +202,41 @@ The shape values each `create*Tool` factory (and `createWorkflowDraftContract`)
|
|
|
199
202
|
|
|
200
203
|
### Types
|
|
201
204
|
|
|
202
|
-
| Name | Kind | Signature
|
|
203
|
-
| -------------------------- | --------- |
|
|
204
|
-
| `TaskDraft` | interface | `{ id?, name?, description?, behavior?, retries?, timeout? }`
|
|
205
|
-
| `PhaseDraft` | interface | `{ id?, name?, description?, tasks, concurrency?, bail? }`
|
|
206
|
-
| `WorkflowDraft` | interface | `{ id?, name?, description?, phases, bail? }`
|
|
207
|
-
| `WorkflowStep` | interface | `{ name }`
|
|
208
|
-
| `WorkflowSteps` | interface | `{ name?, steps }`
|
|
209
|
-
| `WorkflowToolResult` | interface | `{ status, count, durable?, fault? }`
|
|
210
|
-
| `WorkflowLineage` | type | `readonly string[]`
|
|
211
|
-
| `WorkflowAgents` | type | `Readonly<Record<string, AgentInterface>>`
|
|
212
|
-
| `AgentFunction` | type | `WorkflowFunction & { readonly category: 'agent'; readonly lineage: WorkflowLineage; }`
|
|
213
|
-
| `AgentFunctionOptions` | interface | `{ runner?, lineage?, functions?, agents?, store? }`
|
|
214
|
-
| `WorkflowToolOptions` | interface | `{ lineage?, functions?, agents?, store? }`
|
|
215
|
-
| `WorkspaceToolOptions` | interface | `{ name?, description?, manager?, store? }`
|
|
216
|
-
| `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; }
|
|
217
|
-
| `AgentToolOptions` | interface | `{ name?, description?, provider
|
|
218
|
-
| `AgentToolArguments` | interface | `{ task
|
|
219
|
-
| `ToolboxErrorCode` | type | `'TOOL' \| 'DEPTH' \| 'DEADLOCK' \| 'EXPIRE' \| 'ANSWER' \| 'DATABASE' \| 'RELATION'`
|
|
220
|
-
| `DescribeToolArguments` | interface | `{ name }`
|
|
221
|
-
| `PromptToolOptions` | interface | `{ manager, from, name?, description? }`
|
|
222
|
-
| `AnswerToolOptions` | interface | `{ manager, to, name?, description? }`
|
|
223
|
-
| `ColumnPrimitive` | type | `'string' \| 'integer' \| 'number' \| 'boolean'`
|
|
224
|
-
| `ColumnSpec` | type | `ColumnPrimitive \| Readonly<{ readonly primitive: ColumnPrimitive; readonly optional?: boolean; }>`
|
|
225
|
-
| `TableSpec` | type | `Readonly<Record<string, Readonly<{ readonly columns: Readonly<Record<string, ColumnSpec>>; }>>>`
|
|
226
|
-
| `DatabaseDefinition` | interface | `{ id, driver, tables, primary?, indexes?, version? }`
|
|
227
|
-
| `DatabaseDefinitionRow` | interface | `{ id, definition }`
|
|
228
|
-
| `DefinitionStoreInterface` | interface | `{ get(), set(), delete() }`
|
|
229
|
-
| `DatabaseQueryInput` | interface | `{ conditions?, order?, limit?, offset? }`
|
|
230
|
-
| `ClampedQuery` | interface | `{ query, limit }`
|
|
231
|
-
| `DatabaseToolOptions` | interface | `{ name?, description?, databases?, store?, drivers?, generator?, limit?, timeout?, readonly? }`
|
|
232
|
-
| `RelationToolOptions` | interface | `{ name?, description?, managers, limit?, depth? }`
|
|
233
|
-
| `InferToolOptions` | interface | `{ name?, description? }`
|
|
234
|
-
| `EndpointHandler` | type | `(args: Readonly<Record<string, unknown>>, context: ToolContext) => Promise<unknown> \| unknown`
|
|
235
|
-
| `EndpointDefinition` | interface | `{ name, description, samples, execute }`
|
|
236
|
-
| `EndpointToolOptions` | interface | `{ format?, enum?, strict? }`
|
|
205
|
+
| Name | Kind | Signature | Summary |
|
|
206
|
+
| -------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
207
|
+
| `TaskDraft` | interface | `{ id?, name?, description?, behavior?, retries?, timeout? }` | Represents a draft task — a `TaskDefinition` (`@orkestrel/workflow`) with optional `id` and `name`. |
|
|
208
|
+
| `PhaseDraft` | interface | `{ id?, name?, description?, tasks, concurrency?, bail? }` | Represents a draft phase — a `PhaseDefinition` (`@orkestrel/workflow`) with optional `id` and `name` and `TaskDraft` tasks. |
|
|
209
|
+
| `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. |
|
|
210
|
+
| `WorkflowStep` | interface | `{ name }` | Represents one flat step — `{ name }` — the building block of a `WorkflowSteps` blob. |
|
|
211
|
+
| `WorkflowSteps` | interface | `{ name?, steps }` | Represents the flat authoring blob `createWorkflowTool` advertises — `{ name?, steps }` — the simplest surface a small model can fill. |
|
|
212
|
+
| `WorkflowToolResult` | interface | `{ status, count, durable?, fault? }` | Represents the JSON-safe run summary returned by `createWorkflowTool`. |
|
|
213
|
+
| `WorkflowLineage` | type | `readonly string[]` | Represents one immutable workflow/agent call chain — strictly alternating tags, each unique, beginning with a workflow tag. |
|
|
214
|
+
| `WorkflowAgents` | type | `Readonly<Record<string, AgentInterface>>` | Represents raw live agents keyed by the workflow function names that invoke them. |
|
|
215
|
+
| `AgentFunction` | type | `WorkflowFunction & { readonly category: 'agent'; readonly lineage: WorkflowLineage; }` | Represents a contextual agent adapter carrying immutable metadata for Toolbox composition. |
|
|
216
|
+
| `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. |
|
|
217
|
+
| `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. |
|
|
218
|
+
| `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. |
|
|
219
|
+
| `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; }` | Represents one operation an agent invokes through `createWorkspaceTool` — a flat, descriptive tagged union over the workspace edit and read actions, discriminated by the `operation` literal (a discriminant is named for its axis — the action being performed — never `kind`). |
|
|
220
|
+
| `AgentToolOptions` | interface | `{ name?, description?, provider, tools?, system?, authority?, depth?, ancestry?, store? }` | Represents the options for `createAgentTool` — the sub-agent the tool delegates to, fixed by the host, the nesting-depth / cycle guard bookkeeping, and the advertised tool overrides. |
|
|
221
|
+
| `AgentToolArguments` | interface | `{ task }` | Represents the flat args `createAgentTool` accepts — the delegated `task` alone. |
|
|
222
|
+
| `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. |
|
|
223
|
+
| `DescribeToolArguments` | interface | `{ name }` | Represents the flat args `createDescribeTool` accepts — the registered tool `name` whose full `description` a model wants back. |
|
|
224
|
+
| `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. |
|
|
225
|
+
| `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. |
|
|
226
|
+
| `ColumnPrimitive` | type | `'string' \| 'integer' \| 'number' \| 'boolean'` | Represents one column's declared primitive — a shorthand, or `integer` for a whole-number `number`. |
|
|
227
|
+
| `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. |
|
|
228
|
+
| `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`. |
|
|
229
|
+
| `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. |
|
|
230
|
+
| `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. |
|
|
231
|
+
| `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. |
|
|
232
|
+
| `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`. |
|
|
233
|
+
| `ClampedQuery` | interface | `{ query, limit }` | Represents the probe query and effective row limit `clampQuery` returns. |
|
|
234
|
+
| `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. |
|
|
235
|
+
| `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. |
|
|
236
|
+
| `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. |
|
|
237
|
+
| `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. |
|
|
238
|
+
| `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. |
|
|
239
|
+
| `EndpointToolOptions` | interface | `{ format?, enum?, strict? }` | 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. |
|
|
237
240
|
|
|
238
241
|
### Server routes
|
|
239
242
|
|
|
@@ -336,19 +339,19 @@ Before shape branching or property reads, the handler snapshots untrusted `args`
|
|
|
336
339
|
|
|
337
340
|
6. **`createWorkflowTool` delegates composition and persistence without inventing identity.** Configured lineage/functions/agents registries are copied at construction. At invocation the strict target tag is appended, repeated ids and over-depth are rejected, and `createWorkflowFunctions` builds the contextual registry only when functions or agents were supplied. The resulting registry and optional store are forwarded to `runner.execute(target, { functions?, store? })`. The runner owns initial/attempt/settlement/final checkpoints, coalescing, restore-ready final snapshots, and persistence failures as data. `WorkflowToolResult` projects `{ status, count, durable?, fault? }`: `durable`/`fault` appear exactly when the native result supplies them. A flat authoring `name` is the deterministic workflow id; repeated runs with the same name address and replace the same store snapshot rather than minting a hidden id.
|
|
338
341
|
|
|
339
|
-
7. **`createWorkspaceTool`
|
|
342
|
+
7. **`createWorkspaceTool` acts on one workspace for each call, with a no-workspace ergonomic seam.** `options.manager` (drive directly) takes priority over `options.store` (build a fresh manager over it through `@orkestrel/workspace`'s `createWorkspaceManager`); neither given constructs a manager over `@orkestrel/workspace`'s in-memory default. The `store` slot deliberately diverges from invariant 6: the workspace tool's `store` only backs the constructed manager's `open` / `save` — the tool's edits are not auto-persisted (durability requires an explicit caller `save`), whereas the workflow tool forwards its store to native run-wide checkpoint persistence. The tool acts on one workspace for each call. Under `@orkestrel/agent` that is the workspace the run shows, read from `context.caller` and accepted only when it is the instance this tool's manager holds under its id; a run that shows none reads nothing and edits nothing. With no Agent caller it is `manager.active`, which the host alone moves through `manager.switch`. The tool holds no operation that lists or selects a workspace. Under an Agent caller that carries a `files` list, the tool reaches the listed paths alone: it refuses any other path with `'TOOL'`, whether or not a file sits there, lists the listed files, and limits `search` and `replace` to them through the `paths` option. A caller value that holds a `workspace` key, own or inherited, and is no `AgentCaller` refuses: an `AgentCaller` is a plain record that owns exactly `workspace` and `files`, so a class instance or a caller whose members sit on its prototype refuses too. The tool reads each member once into a frozen copy, so a member that answers differently on a later read is taken as that one reading. Register the tool over the agent's own registry, `createWorkspaceTool({ manager: agent.context.workspaces })`, because a workspace from another manager is never that instance; the handler reads the caller once for each call through `readToolCaller`, compares the workspace by identity in `resolveToolWorkspace`, and holds each path to the list through `requireListedPath`. With no Agent caller and no active workspace, an arm that can create the file it names (write / prepend / append) creates and activates one (`manager.add()`); every other edit, and every edit under an Agent caller that shows no workspace, refuses with a `TOOL` `ToolboxError` that says what to do and creates none (`requireToolWorkspace`); a pure-read arm (read / list / has / search) with no workspace returns the empty result, never creating one and never throwing. `read` returns `null` for a path that holds no text, because JSON tells that from an empty file. `path`, `query`, `from`, and `to` are nonempty; an empty `replacement` is a deletion. `search` / `replace` pass the workspace vocabulary through unchanged: `regex` chooses pattern-vs-literal matching, `sensitive` controls case sensitivity, and `limit` caps occurrences, counted within the listed files under a `files` list; `replace` returns the dependency's own `ReplaceResult` directly as `{ occurrences, files }`.
|
|
340
343
|
|
|
341
344
|
8. **`createAgentTool` carries its own `store` slot, composable with a registry-level store.** `AgentToolOptions.store` is an optional `ConversationStoreInterface` (`@orkestrel/agent`): when supplied, the handler `await`s `store.set(agent.context.conversations.active.snapshot())` after `agent.generate()` settles successfully, before returning — one snapshot per delegation (each `registry.build` mints a fresh conversation id through its seeded `add`, so a shared store never collides, it accumulates one snapshot per delegated call). A `store.set` failure propagates as the tool call's own failure (isolated by `ToolManagerInterface` into the canonical `error`, per invariant 2) — persistence is not best-effort. Omitted, the handler persists nothing from this tool. This composes with, and is independent of, `AgentRegistryOptions.store` (`@orkestrel/agent`): a registry built with its own `store` backs every agent it builds with a store-backed `ConversationManagerInterface`, including ones built through this tool — a caller may use either seam alone or both together.
|
|
342
345
|
|
|
343
346
|
9. **A delegated sub-agent's lifecycle is a single `generate()` call.** `createAgentTool`'s handler resolves a live agent through `registry.build`, awaits one `agent.generate()`, and returns its settled `content` — `AgentInterface` (`@orkestrel/agent`) exposes no teardown method, so there is nothing to release afterwards; the agent's state lives entirely in the resolved `AgentContextInterface`, owned by the caller's registry.
|
|
344
347
|
|
|
345
|
-
10. **Provider-agnostic delegation.** `createAgentTool` never imports or references a concrete `ProviderInterface` implementation — `options.provider`
|
|
348
|
+
10. **Provider-agnostic delegation, with the sub-agent fixed by the host.** `createAgentTool` never imports or references a concrete `ProviderInterface` implementation — `options.provider` is a registry key resolved by `registry.build`, so swapping the provider behind that key changes nothing about the tool. A call carries `task` alone: `AgentToolOptions` fixes the sub-agent's `provider`, `tools`, `system`, and `authority`, and `agentToolShape` is exact, so a call carrying `provider`, `tools`, `system`, or any other member refuses at the Tool door as a `ToolError` with code `ARGUMENTS` whose fault names that member, before any agent is built. A model therefore never chooses the provider, the tools, or the system text of the agent it delegates to. A non-empty `tools` list with no `authority` throws a `TOOL` `ToolboxError` at construction, because an agent with tools needs one, and its text says to set `authority` or set `tools: []`. A `depth` that is not a nonnegative safe integer throws `TOOL` at construction.
|
|
346
349
|
|
|
347
350
|
11. **`ToolboxError` owns Toolbox boundary failures; upstream errors own genuine domain failures.** It carries a machine-readable `ToolboxErrorCode` and an optional `context` and is always thrown, never returned as `{ error }`: `TOOL` covers missing tool bindings, invalid tool/agent JSON, a wrapped workflow the strict contract refuses, and the other package-owned resolution/configuration guards, while malformed call arguments are `@orkestrel/tool`'s `ToolError` with code `ARGUMENTS`; `DEPTH` covers Toolbox workflow/agent nesting refusal; the remaining codes retain their terminal/database/relation meanings. A genuine error thrown by an executed tool passes through unchanged. The native workflow runner's genuine `WorkflowError` also passes through unchanged, including `TRANSITION` for an unresolved named run; Toolbox never invents invalid workflow `TOOL`/`DEPTH` codes and never relabels runner errors. `WorkspaceError` similarly retains its upstream domain ownership. An in-process direct call can inspect typed codes/context; `ToolManagerInterface.execute` flattens the error to its message.
|
|
348
351
|
|
|
349
352
|
12. **The workflow-function adapters are opt-in and exact at the JSON boundary.** `createToolFunction(tools, name)` resolves the live tool, awaits `tool.execute(controller.input, { signal: controller.signal })` — the execution context carries the running task's own cancellation, so a handler that reads `context.signal` observes the run's cancellation rather than an uncancellable stand-in — then deep-gates the unknown return through `parseJSONValue`; a missing binding or non-JSON result throws `ToolboxError('TOOL')`, while a genuine tool throw passes through by identity, so a task input the tool does not declare surfaces as the tool door's `ToolError`. It rejects `name === WORKFLOW_TOOL_NAME` at construction so the reserved live workflow tool cannot be adapted back into a workflow registry. `createAgentFunction(agent, options?)` returns a frozen `AgentFunction` with frozen category/lineage metadata. It starts `agent.generate({ signal: controller.signal })` synchronously after any runner-bound tool installation, using Agent's native per-run cancellation seam: an already-aborted signal starts no provider call, and cancellation settles as a partial result. The full `AgentResult` is projected through Agent-owned `agentResultToJSON`; malformed structural results become `ToolboxError('TOOL')`. With a runner, an already-running real agent is rejected before its workflow-tool binding can be replaced, so another Toolbox branch observes the running state. Genuine agent/provider errors retain identity.
|
|
350
353
|
|
|
351
|
-
13. **The lean `summary` / full `description` split, and `createDescribeTool`'s expansion seam.** `createWorkflowTool`, `createWorkspaceTool`, and `createAgentTool` each set `ToolInterface.summary` (`@orkestrel/tool`) to a frozen one-sentence constant (`WORKFLOW_TOOL_SUMMARY` / `WORKSPACE_TOOL_SUMMARY` / `AGENT_TOOL_SUMMARY`) alongside their unchanged full teaching `description`; `ToolManagerInterface.definitions()` advertises `summary ?? description`, so a model sees the lean text by default. `createDescribeTool(tools)` is the on-demand expansion: given a registered `name`, it looks the tool up through `tools.tool(name)` and returns its full `tool.description` (falling back to `tool.summary`, then an explicit `null` when a tool has neither) — never truncated, never re-derived. An unknown `name` lists the registered names. Each summary's text points the model at `describe('<name>')` for the full schema.
|
|
354
|
+
13. **The lean `summary` / full `description` split, and `createDescribeTool`'s expansion seam.** `createWorkflowTool`, `createWorkspaceTool`, and `createAgentTool` each set `ToolInterface.summary` (`@orkestrel/tool`) to a frozen one-sentence constant (`WORKFLOW_TOOL_SUMMARY` / `WORKSPACE_TOOL_SUMMARY` / `AGENT_TOOL_SUMMARY`) alongside their unchanged full teaching `description`; `ToolManagerInterface.definitions()` advertises `summary ?? description`, so a model sees the lean text by default. `createDescribeTool(tools)` is the on-demand expansion: given a registered `name`, it looks the tool up through `tools.tool(name)` and returns its full `tool.description` (falling back to `tool.summary`, then an explicit `null` when a tool has neither) — never truncated, never re-derived. An unknown `name` lists the registered names. Each summary's text points the model at `describe('<name>')` for the full schema. An `@orkestrel/agent` host holds teaching text and tools back through Agent's skills and its `load` built-in instead, which shows a skill's text and releases its tools when the model asks for it; see [Agent](agent.md) § Enabling the built-in tools.
|
|
352
355
|
|
|
353
356
|
14. **`createDatabaseTool` and `createRelationTool` are single-tool-many-operations, matching `createWorkspaceTool`'s shape.** `createDatabaseTool` dispatches `create` / `tables` / `get` / `records` / `count` / `aggregate` / `add` / `set` / `update` / `remove` / `destroy` off `databaseToolShape`; `createRelationTool` dispatches `load` / `find` / `link` / `unlink` / `links` off `relationToolShape`. Both set `ToolInterface.summary` (`DATABASE_TOOL_SUMMARY` / `RELATION_TOOL_SUMMARY`) alongside their full teaching `description`, retrievable through `createDescribeTool`, per invariant 13. Every `'get'` / `'add'` / `'set'` / `'update'` / `'remove'` and `'load'` operation's `key` field takes either a single key or an array of keys (AGENTS' batch overload mold, with the array form resolving first); a single-key call returns a singular result field (`row` / `key` / `updated` / `removed`), an array-key call returns the plural (`rows` / `keys` / `updated` / `removed` as arrays). A row a `'get'` or `'load'` misses is an explicit `null` in either form, where JSON would otherwise drop the key.
|
|
354
357
|
|
|
@@ -464,9 +467,44 @@ const read = await tools.execute({
|
|
|
464
467
|
read.value // 'hello'
|
|
465
468
|
```
|
|
466
469
|
|
|
470
|
+
### Acting on the run's workspace and files list
|
|
471
|
+
|
|
472
|
+
Under `@orkestrel/agent`, each tool call's `context.caller` is an `AgentCaller`: the workspace the run shows and the files its scope lists. Register the tool over the agent's `context.workspaces`; the following fence hands a caller to the tool directly, as an agent run does, and reads what the tool reaches:
|
|
473
|
+
|
|
474
|
+
```ts
|
|
475
|
+
import { createWorkspaceManager } from '@orkestrel/workspace'
|
|
476
|
+
import { createWorkspaceTool } from '@orkestrel/toolbox'
|
|
477
|
+
|
|
478
|
+
const manager = createWorkspaceManager()
|
|
479
|
+
const orders = manager.add({ id: 'orders' })
|
|
480
|
+
const returns = manager.add({ id: 'returns' })
|
|
481
|
+
returns.write('notes.md', 'Refund noted.')
|
|
482
|
+
returns.write('secret.md', 'The vault code is 7731.')
|
|
483
|
+
const tool = createWorkspaceTool({ manager })
|
|
484
|
+
const signal = new AbortController().signal
|
|
485
|
+
|
|
486
|
+
// The run shows `returns`, and its scope lists `notes.md` alone.
|
|
487
|
+
const caller = { workspace: returns, files: ['notes.md'] }
|
|
488
|
+
await tool.execute({ operation: 'read', path: 'notes.md' }, { signal, caller }) // 'Refund noted.'
|
|
489
|
+
await tool.execute({ operation: 'search', query: 'code' }, { signal, caller }) // []
|
|
490
|
+
await tool.execute({ operation: 'read', path: 'secret.md' }, { signal, caller })
|
|
491
|
+
// throws ToolboxError ('TOOL'): path "secret.md" is outside the files this run reaches; ...
|
|
492
|
+
|
|
493
|
+
// A run that shows no workspace reads nothing.
|
|
494
|
+
const none = { workspace: undefined, files: undefined }
|
|
495
|
+
await tool.execute({ operation: 'read', path: 'notes.md' }, { signal, caller: none }) // null
|
|
496
|
+
|
|
497
|
+
// A workspace from another manager is never the instance this one holds.
|
|
498
|
+
const copy = createWorkspaceManager().add({ id: 'returns' })
|
|
499
|
+
await tool.execute({ operation: 'list' }, { signal, caller: { workspace: copy, files: undefined } })
|
|
500
|
+
// throws ToolboxError ('TOOL'): the run's workspace is not one this tool's manager holds; ...
|
|
501
|
+
|
|
502
|
+
manager.active === orders // true
|
|
503
|
+
```
|
|
504
|
+
|
|
467
505
|
### Delegating to a sub-agent through the agent tool
|
|
468
506
|
|
|
469
|
-
Register the agent tool over a seeded registry and delegate one task
|
|
507
|
+
Register the agent tool over a seeded registry with the sub-agent's provider fixed, and delegate one task; the call sends `task` alone:
|
|
470
508
|
|
|
471
509
|
```ts
|
|
472
510
|
import { createAgentTool } from '@orkestrel/toolbox'
|
|
@@ -920,10 +958,13 @@ import {
|
|
|
920
958
|
isPrimaryMap,
|
|
921
959
|
isTableSpec,
|
|
922
960
|
limitRefusal,
|
|
961
|
+
readToolCaller,
|
|
923
962
|
renderCandidates,
|
|
924
|
-
|
|
963
|
+
requireListedPath,
|
|
925
964
|
requireToolCall,
|
|
965
|
+
requireToolWorkspace,
|
|
926
966
|
resolveBound,
|
|
967
|
+
resolveToolWorkspace,
|
|
927
968
|
} from '@orkestrel/toolbox'
|
|
928
969
|
|
|
929
970
|
isTableSpec({ items: { columns: { id: 'string' } } }) // true
|
|
@@ -949,7 +990,12 @@ resolveBound(25, 100, 'database limit') // 25
|
|
|
949
990
|
|
|
950
991
|
const manager = createWorkspaceManager()
|
|
951
992
|
const workspace = manager.add()
|
|
952
|
-
|
|
993
|
+
resolveToolWorkspace(manager, undefined) === workspace // true
|
|
994
|
+
requireToolWorkspace(workspace, undefined, 'remove') === workspace // true
|
|
995
|
+
readToolCaller({ subject: 'reader' }) // undefined
|
|
996
|
+
readToolCaller({ workspace: 'returns' }) // throws ToolboxError ('TOOL')
|
|
997
|
+
requireListedPath(['notes.md'], 'notes.md') // returns
|
|
998
|
+
requireListedPath(['notes.md'], 'secret.md') // throws ToolboxError ('TOOL')
|
|
953
999
|
|
|
954
1000
|
describeDefinitionRefusal('shop', [{ reason: 'extra', path: ['keys'] }])
|
|
955
1001
|
// 'database "shop" holds a definition this version refuses (extra key "keys" at the root; ...'
|
|
@@ -1113,9 +1159,9 @@ the signal only where it has cancellable work to abandon.
|
|
|
1113
1159
|
## Tests
|
|
1114
1160
|
|
|
1115
1161
|
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` and `src/server` bijection (value and type exports, spanning both barrels), this guide's `## Patterns` fences resolving to real exports (per-specifier) with resolving imports, the `DefinitionStoreInterface` and `DatabaseResolver` method bijections, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Authoring and running a workflow through the tool with a real ToolManager` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences and asserts the values their comments claim.
|
|
1116
|
-
- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — every factory returning a working instance or value; workflow coverage composes real runners, agents, tools, stores, and scripted providers across direct roots, top-level authoring tools, opaque-leaf propagation, frozen null-prototype registry isolation/collisions, inherited-name `TRANSITION` refusals, explicitly registered dangerous own keys, depth 8/9 boundaries, repeated workflow ids, bound no-arg cycle refusal, self-recursion, A→B→A, same-agent concurrency, native per-run cancellation (including already-aborted provider exclusion),
|
|
1162
|
+
- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — every factory returning a working instance or value; workflow coverage composes real runners, agents, tools, stores, and scripted providers across direct roots, top-level authoring tools, opaque-leaf propagation, frozen null-prototype registry isolation/collisions, inherited-name `TRANSITION` refusals, explicitly registered dangerous own keys, depth 8/9 boundaries, repeated workflow ids, bound no-arg cycle refusal, self-recursion, A→B→A, same-agent concurrency, native per-run cancellation (including already-aborted provider exclusion), untrusted argument containment before runner/store entry, Agent-owned projection, malformed structural results, genuine error identity, and deterministic named-store replacement. Database coverage includes every operation, frozen readonly-mutation membership, persistence-before-cache publication through a real failing database store, timeout validation, query truncation, and typed failures. Creation and resolver coverage prove `primary` / `indexes` reach real memory-driver metadata and `version` is stamped after first use. Terminal coverage drives a real `TerminalManagerInterface` through the ask/answer pair: a multi-field schema parking once and settling into one values record, the pending listing carrying `{ id, from, schema }`, a schema `parseForm` refuses (an unknown control, duplicate field names, missing or non-array choices) throwing typed `TOOL` with nothing parked, the fixed `from` surviving a spoofing attempt, and the `DEADLOCK` / `EXPIRE` (injected timer) / unknown-terminal / unknown-id classifications. Workspace caller coverage drives every operation on a two-workspace desk under an Agent caller: the caller's workspace acted on and accepted by identity alone, the active workspace kept with no Agent caller, a run that shows none reading and editing nothing, a malformed caller refused, and every operation held to the caller's files list, a path that only resembles a listed one (a leading `./` or `../`, a trailing slash, a fullwidth letter, a longer path it prefixes, another letter case) refused or left out of `list`. A real agent with the built-in `switch` then edits the workspace each run shows across one conversation, two conversations, the run option, the host's move, one turn in each call order, and the ceiling, and a hidden file stays out of every request and tool message.
|
|
1117
1163
|
- [`tests/src/core/databases/DatabaseResolver.test.ts`](../tests/src/core/databases/DatabaseResolver.test.ts) — caller-map isolation, explicit cache operations, stored-definition construction and reuse, and the typed unknown-database failure.
|
|
1118
|
-
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — the reusable workflow, terminal, database, and relation helpers; lineage coverage proves copy/freeze isolation, extension, and zero-based depth derivation. Database coverage includes `normalizeQuery` connector defaults, `resolveLimit` clamping a request to the cap and flooring a negative one at `0`, and `clampQuery` probe limits. Door coverage holds `requireToolCall` and `buildArgumentRefusal` to a named refusal for a form or an operation, and `resolveBound
|
|
1164
|
+
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — the reusable workflow, terminal, database, and relation helpers; lineage coverage proves copy/freeze isolation, extension, and zero-based depth derivation. Database coverage includes `normalizeQuery` connector defaults, `resolveLimit` clamping a request to the cap and flooring a negative one at `0`, and `clampQuery` probe limits. Door coverage holds `requireToolCall` and `buildArgumentRefusal` to a named refusal for a form or an operation, and `resolveBound` and `describeDefinitionRefusal` to what each says. Workspace caller coverage holds `readToolCaller` to an owned, frozen copy read once, a member that changes on a later read taken as its one reading, and to one refusal for every malformed, unreadable, class-instance, or inherited caller, `resolveToolWorkspace` to identity with the manager's own workspaces, `requireToolWorkspace` to the text each path gives, and `requireListedPath` to a bounded refusal that names the path and the listed paths.
|
|
1119
1165
|
- [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — every guard at its untrusted boundary: `isWorkflowLineage` alternating/nonempty/unique validation and hostile-boundary totality, `isAgentFunction` metadata narrowing, `isColumnPrimitive` and `isColumnSpec` over the column DSL, and strict `isDatabaseDefinition` validation for `primary` / `indexes` / finite `version` with obsolete-field rejection, exact on owned keys and in lockstep with `definitionContract` over every fixture in both directions.
|
|
1120
1166
|
- [`tests/src/core/compilers.test.ts`](../tests/src/core/compilers.test.ts) — the `TableSpec` column DSL compiled through a real `createContract` gate: every `ColumnPrimitive` accepting its own values and rejecting the others, `optional: true` admitting an absent column, `optional: false` staying required, integer separated from number, and multiple tables compiled independently.
|
|
1121
1167
|
- [`tests/src/core/shapers.test.ts`](../tests/src/core/shapers.test.ts) — every advertised shape, including valid samples of every database operation arm, create-time `primary` / `indexes` / `version`, query inputs, single/array row-key forms, and malformed metadata rejection.
|