@orkestrel/scaffold 0.0.136 → 0.0.138
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/bin/main.js +11 -11
- package/dist/host/agents/skills/orkestrel-journey/SKILL.md +33 -27
- package/dist/host/agents/skills/orkestrel-journey/references/captures.md +37 -16
- package/dist/host/agents/skills/orkestrel-polish/references/capture-harness.md +5 -0
- package/dist/host/claude/agents/orkestrel.md +54 -54
- package/dist/host/claude/rules/typescript.md +4 -1
- package/dist/host/claude/rules/workspace.md +6 -4
- package/dist/host/guides/agent.md +3 -1
- package/dist/host/guides/brief.md +16 -16
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/capture.md +442 -313
- package/dist/host/guides/database.md +14 -11
- package/dist/host/guides/process.md +139 -53
- package/dist/host/guides/reason.md +1 -1
- package/dist/host/guides/scaffold.md +33 -21
- package/dist/host/guides/test.md +353 -232
- package/dist/host/guides/tool.md +2 -1
- package/dist/host/guides/toolbox.md +44 -44
- package/dist/host/guides/workflow.md +2 -2
- package/dist/host/manifest.json +20 -20
- package/dist/host/tests/config.test.ts +19 -27
- package/dist/src/core/index.cjs +144 -65
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +1 -1
- package/dist/src/core/index.d.ts +1 -1
- package/dist/src/core/index.js +144 -65
- package/dist/src/core/index.js.map +1 -1
- package/package.json +11 -11
package/dist/host/guides/tool.md
CHANGED
|
@@ -411,8 +411,9 @@ raw stay by reference. So `{ type: 'object' }` gives a null-prototype copy of th
|
|
|
411
411
|
values by reference, and `parameters: {}` or a root `$ref` gives a plain top-level copy with nested
|
|
412
412
|
values by reference.
|
|
413
413
|
|
|
414
|
-
The
|
|
414
|
+
The door admits through `repairValue` from `@orkestrel/contract`, which repairs a lossless leaf: it accepts `'30'` as `30`, `'true'`
|
|
415
415
|
as `true`, and a finite number as its string. It refuses `'30.0'`, which changes the supplied text.
|
|
416
|
+
A model sends the arguments, so state the repair in the description of every tool that keeps the door, which every tool but a `strict: false` one does.
|
|
416
417
|
The handler receives the admitted value without another parse. The argument snapshot remains
|
|
417
418
|
in this package, and a union may retain that snapshot or its nested values by identity.
|
|
418
419
|
`anyOf: [T, { type: 'null' }]` and `type: [T, 'null']` convert to a nullable rather than a union, so `'5'` reaches the handler
|
|
@@ -161,44 +161,44 @@ The shape values each `create*Tool` factory (and `createWorkflowDraftContract`)
|
|
|
161
161
|
|
|
162
162
|
### Constants
|
|
163
163
|
|
|
164
|
-
| Name | Kind | Signature
|
|
165
|
-
| ------------------------------ | ----- |
|
|
166
|
-
| `AGENT_TOOL_NAME` | const | `"agent"`
|
|
167
|
-
| `AGENT_TOOL_DEPTH` | const | `8`
|
|
168
|
-
| `AGENT_TOOL_DESCRIPTION` | const | `string`
|
|
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."`
|
|
170
|
-
| `MAX_WORKFLOW_CHAIN` | const | `8`
|
|
171
|
-
| `WORKFLOW_TOOL_NAME` | const | `"workflow"`
|
|
172
|
-
| `WORKFLOW_TOOL_FLAT_EXAMPLE` | const | `WorkflowSteps`
|
|
173
|
-
| `WORKFLOW_TOOL_NESTED_EXAMPLE` | const | `WorkflowDefinition`
|
|
174
|
-
| `WORKFLOW_TOOL_DESCRIPTION` | const | `string`
|
|
175
|
-
| `WORKFLOW_TOOL_SUMMARY` | const | `"Author and run a multi-phase workflow in one call \u2014 phases run in sequence, tasks within a phase run concurrently. Call describe('workflow') for the full authoring schema and examples."`
|
|
176
|
-
| `WORKSPACE_TOOL_NAME` | const | `"workspace"`
|
|
177
|
-
| `WORKSPACE_TOOL_EXAMPLE` | const | `WorkspaceOperation`
|
|
178
|
-
| `WORKSPACE_TOOL_DESCRIPTION` | const | `string`
|
|
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."`
|
|
180
|
-
| `DESCRIBE_TOOL_NAME` | const | `"describe"`
|
|
181
|
-
| `DESCRIBE_TOOL_SUMMARY` | const | `"Return the full description of a named registered tool."`
|
|
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)."`
|
|
183
|
-
| `PROMPT_TOOL_NAME` | const | `"ask"`
|
|
184
|
-
| `PROMPT_TOOL_SUMMARY` | const | `"Ask another terminal a multi-field form and BLOCK until it answers; the call resolves with the values record. Call describe('ask') for the schema."`
|
|
185
|
-
| `PROMPT_TOOL_DESCRIPTION` | const | `string`
|
|
186
|
-
| `ANSWER_TOOL_NAME` | const | `"answer"`
|
|
187
|
-
| `ANSWER_TOOL_SUMMARY` | const | `"List forms addressed to this terminal, or answer one by id with a values record. Call describe('answer') for the required fields."`
|
|
188
|
-
| `ANSWER_TOOL_DESCRIPTION` | const | `string`
|
|
189
|
-
| `DATABASE_TOOL_NAME` | const | `"database"`
|
|
190
|
-
| `DATABASE_TOOL_SUMMARY` | const | `"Create and query a database \u2014 one operation per call (create, tables, get, records, count, aggregate, add, set, update, remove, destroy), chosen by the 'operation' field. Call describe('database') for the full operation list, the query form, and the column DSL."` | Holds the lean `ToolInterface.summary` `createDatabaseTool` advertises in place of `DATABASE_TOOL_DESCRIPTION` — one sentence offering the `operation`-keyed database call and pointing at `describe` for the operation list, the query form, and the column DSL. |
|
|
191
|
-
| `DATABASE_TOOL_DESCRIPTION` | const | `string`
|
|
192
|
-
| `DATABASE_TOOL_LIMIT` | const | `1000`
|
|
193
|
-
| `DATABASE_TOOL_MUTATIONS` | const | `readonly string[]`
|
|
194
|
-
| `RELATION_TOOL_NAME` | const | `"relation"`
|
|
195
|
-
| `RELATION_TOOL_SUMMARY` | const | `"Traverse and edit relationships between database rows \u2014 one operation per call (load, find, link, unlink, links), chosen by the 'operation' field. Call describe('relation') for the include-path syntax."`
|
|
196
|
-
| `RELATION_TOOL_DESCRIPTION` | const | `string`
|
|
197
|
-
| `RELATION_TOOL_LIMIT` | const | `1000`
|
|
198
|
-
| `RELATION_TOOL_DEPTH` | const | `3`
|
|
199
|
-
| `INFER_TOOL_NAME` | const | `"infer"`
|
|
200
|
-
| `INFER_TOOL_SUMMARY` | const | `"Infer a JSON Schema (as advertised tool parameters) from one or more example values. Call describe('infer') for the required fields."`
|
|
201
|
-
| `INFER_TOOL_DESCRIPTION` | const | `string`
|
|
164
|
+
| Name | Kind | Signature | Summary |
|
|
165
|
+
| ------------------------------ | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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`. |
|
|
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
|
+
| `WORKFLOW_TOOL_NESTED_EXAMPLE` | const | `WorkflowDefinition` | Holds a minimal nested authoring example — the advanced escape-hatch form a model can use instead of the flat shape: a full `WorkflowDefinition` (`@orkestrel/workflow`). |
|
|
174
|
+
| `WORKFLOW_TOOL_DESCRIPTION` | const | `string` | Holds the description `createWorkflowTool` advertises — the flat authoring form, its worked example, and the advanced nested definition form. |
|
|
175
|
+
| `WORKFLOW_TOOL_SUMMARY` | const | `"Author and run a multi-phase workflow in one call \u2014 phases run in sequence, tasks within a phase run concurrently. Call describe('workflow') for the full authoring schema and examples."` | Holds the lean `ToolInterface.summary` `createWorkflowTool` advertises in place of `WORKFLOW_TOOL_DESCRIPTION` — one sentence offering multi-phase authoring and pointing at `describe` for the authoring schema and its examples. |
|
|
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. |
|
|
177
|
+
| `WORKSPACE_TOOL_EXAMPLE` | const | `WorkspaceOperation` | Holds a valid `WorkspaceOperation` object — the canonical example embedded verbatim in `WORKSPACE_TOOL_DESCRIPTION`. |
|
|
178
|
+
| `WORKSPACE_TOOL_DESCRIPTION` | const | `string` | Holds the description `createWorkspaceTool` advertises — the operation-keyed workspace protocol, all supported operations, and worked examples. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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). Arguments admit lossless repair alone: a text field accepts a finite number; any other mismatch is refused, and the refusal names every fault."` | Holds the description `createDescribeTool` advertises — the registered tool `name` it requires, and the full description of that tool it returns. |
|
|
183
|
+
| `PROMPT_TOOL_NAME` | const | `"ask"` | Holds the name `createPromptTool` advertises by default, `'ask'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
|
|
184
|
+
| `PROMPT_TOOL_SUMMARY` | const | `"Ask another terminal a multi-field form and BLOCK until it answers; the call resolves with the values record. Call describe('ask') for the schema."` | Holds the lean `ToolInterface.summary` `createPromptTool` advertises in place of `PROMPT_TOOL_DESCRIPTION` — one sentence offering the blocking multi-field ask and pointing at `describe` for the schema. |
|
|
185
|
+
| `PROMPT_TOOL_DESCRIPTION` | const | `string` | Holds the form protocol `createPromptTool` advertises — the required `to` and `schema`, how a field declares its control and its rules, and a worked example. |
|
|
186
|
+
| `ANSWER_TOOL_NAME` | const | `"answer"` | Holds the name `createAnswerTool` advertises by default, `'answer'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
|
|
187
|
+
| `ANSWER_TOOL_SUMMARY` | const | `"List forms addressed to this terminal, or answer one by id with a values record. Call describe('answer') for the required fields."` | Holds the lean `ToolInterface.summary` `createAnswerTool` advertises in place of `ANSWER_TOOL_DESCRIPTION` — one sentence offering the pending listing and the answer call, and pointing at `describe` for the fields each takes. |
|
|
188
|
+
| `ANSWER_TOOL_DESCRIPTION` | const | `string` | Holds the protocol `createAnswerTool` advertises — the `pending` and `answer` operations and the `values` record an answer supplies, each with a worked example. |
|
|
189
|
+
| `DATABASE_TOOL_NAME` | const | `"database"` | Holds the name `createDatabaseTool` advertises by default, `'database'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
|
|
190
|
+
| `DATABASE_TOOL_SUMMARY` | const | `"Create and query a database \u2014 one operation per call (create, tables, get, records, count, aggregate, add, set, update, remove, destroy), chosen by the 'operation' field. Every row and query value must match its column's declared type, and a refusal names every fault. Call describe('database') for the full operation list, the query form, and the column DSL."` | Holds the lean `ToolInterface.summary` `createDatabaseTool` advertises in place of `DATABASE_TOOL_DESCRIPTION` — one sentence offering the `operation`-keyed database call and pointing at `describe` for the operation list, the query form, and the column DSL. |
|
|
191
|
+
| `DATABASE_TOOL_DESCRIPTION` | const | `string` | Holds the description `createDatabaseTool` advertises — a multi-line guide that teaches a small model the operation list, the serialized query form, and the `TableSpec` column DSL. |
|
|
192
|
+
| `DATABASE_TOOL_LIMIT` | const | `1000` | Holds the default cap on rows a `records` call returns when the caller omits `query.limit`, `1000` — the database tool's default row ceiling. |
|
|
193
|
+
| `DATABASE_TOOL_MUTATIONS` | const | `readonly string[]` | Lists the runtime-frozen database-tool mutation names disabled by `DatabaseToolOptions.readonly`. |
|
|
194
|
+
| `RELATION_TOOL_NAME` | const | `"relation"` | Holds the name `createRelationTool` advertises by default, `'relation'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
|
|
195
|
+
| `RELATION_TOOL_SUMMARY` | const | `"Traverse and edit relationships between database rows \u2014 one operation per call (load, find, link, unlink, links), chosen by the 'operation' field. Call describe('relation') for the include-path syntax."` | Holds the lean `ToolInterface.summary` `createRelationTool` advertises in place of `RELATION_TOOL_DESCRIPTION` — one sentence offering the `operation`-keyed relationship traversal and pointing at `describe` for the include-path syntax. |
|
|
196
|
+
| `RELATION_TOOL_DESCRIPTION` | const | `string` | Holds the description `createRelationTool` advertises — a multi-line guide that teaches a small model the operation list and the flat dot-path `include` syntax. |
|
|
197
|
+
| `RELATION_TOOL_LIMIT` | const | `1000` | Holds the default cap on rows a `find` or `links` call returns when the caller omits `limit`, `1000` — the relation tool's default row ceiling. |
|
|
198
|
+
| `RELATION_TOOL_DEPTH` | const | `3` | Holds the default cap on how many `include` path segments deep a `load` or `find` call may traverse, `3` — the relation tool's default include-depth ceiling. |
|
|
199
|
+
| `INFER_TOOL_NAME` | const | `"infer"` | Holds the name `createInferTool` advertises by default, `'infer'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under. |
|
|
200
|
+
| `INFER_TOOL_SUMMARY` | const | `"Infer a JSON Schema (as advertised tool parameters) from one or more example values. Call describe('infer') for the required fields."` | Holds the lean `ToolInterface.summary` `createInferTool` advertises in place of `INFER_TOOL_DESCRIPTION` — one sentence offering schema inference from example values and pointing at `describe` for the fields it takes. |
|
|
201
|
+
| `INFER_TOOL_DESCRIPTION` | const | `string` | Holds the schema-inference protocol `createInferTool` advertises — the required `samples`, the optional `format`, `enum`, and `candidates` arguments, and a worked example of the bare return and of the `candidates`-wrapped return. |
|
|
202
202
|
|
|
203
203
|
### Types
|
|
204
204
|
|
|
@@ -329,7 +329,7 @@ These invariants hold across `src/core` ↔ `toolbox.md`:
|
|
|
329
329
|
|
|
330
330
|
2. **One tool = one behavior; the runtime supplies the envelope, this package supplies the handler.** Each `create*Tool` factory returns a plain `ToolInterface` (`@orkestrel/tool`). Under AGENTS' narrow-untrusted-input-with-guards rule, malformed model-supplied `args` refuse before the handler acts, as a `ToolError` with code `ARGUMENTS` whose text says what to send and whose `context.faults` lists every fault (see [`tool.md`](tool.md)). The handler reads a typed value from the compiled [contract](contract.md), dispatches, and either returns a plain value on success or throws a typed error on every failure path — it never builds a `ToolResult` itself. Every refusal a model can read names the subject, what to send, and the candidates where there are some, encodes each untrusted identifier and candidate through `preview` (`renderCandidates`), and stays within 2048 characters: where a message joins parts this package cannot bound one by one, a head beside a report or an upstream error's text, `limitRefusal` caps the whole. A `WorkspaceError`, `WorkflowError`, or `AgentError` that passes through by identity carries its owner's text. The runtime supplies registry execution and result isolation; see [`tool.md`](tool.md). Through that registry, a failure's flattened message text appears exactly once, identically, over both the agent loop and MCP.
|
|
331
331
|
|
|
332
|
-
3. **Contract-compiled schemas throughout.** The workspace, answer, database, relation, agent, describe, prompt, and infer tools pass their shapes through `contract`, so the Tool door enforces the advertised schema. A union value selecting one operation reports that arm's faults and admits lossless leaf repairs: `find` with `limit: '5'` reaches the handler as `5`, while `'many'` names `limit` and `'0x10'` refuses. A value selecting no arm receives a bounded summary of alternatives. Handlers use `requireToolCall` to type the parsed arguments. The workflow tool advertises its flat schema through `parameters` and uses `strict: false` because its handler accepts several authoring forms; `resolveWorkflowTarget` applies the matching contract through `requireToolCall`.
|
|
332
|
+
3. **Contract-compiled schemas throughout.** The workspace, answer, database, relation, agent, describe, prompt, and infer tools pass their shapes through `contract`, so the Tool door enforces the advertised schema. A union value selecting one operation reports that arm's faults and admits lossless leaf repairs: `find` with `limit: '5'` reaches the handler as `5`, while `'many'` names `limit` and `'0x10'` refuses. A value selecting no arm receives a bounded summary of alternatives. Handlers use `requireToolCall` to type the parsed arguments; it admits through `@orkestrel/contract`'s `repairValue`, so it keeps the same lossless leaf repairs, and each tool description built on it states them. The workflow tool advertises its flat schema through `parameters` and uses `strict: false` because its handler accepts several authoring forms; `resolveWorkflowTarget` applies the matching contract through `requireToolCall`.
|
|
333
333
|
|
|
334
334
|
4. **Workflow/agent recursion is lineage-derived and contextually composed.** `WorkflowLineage` is a copied, frozen chain of nonempty unique tags, strictly alternating `workflow:` then `agent:`. Malformed configured lineage or a factory-incompatible final tag throws `ToolboxError('TOOL')`; runtime workflow mismatch, repeated workflow/agent id, or over-depth target throws `ToolboxError('DEPTH')` before agent, tool, or runner activity. Depth is zero-based and derived only from workflow-tag count minus one (empty/root is `0`): root plus eight nested workflows is allowed, the ninth nested workflow is rejected. `createWorkflowFunctions` is the sole composition engine: it snapshots opaque `functions`, rejects a marked `AgentFunction` supplied through that opaque channel, rejects function/agent key collisions, and contextually adapts raw `agents` for the exact target lineage. Its frozen registry has a null prototype, so the workflow runner's native bracket lookup cannot resolve unregistered inherited names such as `toString`, `constructor`, `valueOf`, `hasOwnProperty`, or `__proto__`; those remain genuine native `WorkflowError('TRANSITION')` failures. Opaque wrappers or spoofed metadata that hide their real agent behavior are not covered; hosts must not use them to share one live agent concurrently.
|
|
335
335
|
|
|
@@ -353,7 +353,7 @@ Before shape branching or property reads, the handler snapshots untrusted `args`
|
|
|
353
353
|
|
|
354
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.
|
|
355
355
|
|
|
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`
|
|
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`), and an array-key call returns the plural (`rows` / `keys` / `updated` as arrays). `'remove'` replies `{ removed }` in either form, one boolean that is `true` only when every listed key held a row, because `Table.remove` reports the batch as one boolean. A row a `'get'` or `'load'` misses is an explicit `null` in either form, where JSON would otherwise drop the key. The database tool's values stay strict: each value in a `row`, in `changes`, and in a condition's `values` must match its column's declared type, as `'tables'` reports, so `'36'` never fills an integer column. The database refuses a nonconforming write or query with `VALIDATION`, which the tool forwards as a `DATABASE` `ToolboxError` carrying `context.code`, and the message names every fault. The tool's descriptions state that strictness, and the `like` and `glob` wildcards.
|
|
357
357
|
|
|
358
358
|
15. **The database tool's query form is serialized, never fluent.** `databaseToolShape`'s `query` is a flat object — `{ conditions?: [{ column, operator, values, connector? }], order?, limit?, offset? }` — where `values` is always an array, even for a single-value operator (`{ column: 'age', operator: 'from', values: [18] }`), so a small model never chains method calls or guesses arity. `normalizeQuery` normalizes the parsed form into a live `@orkestrel/database` `QueryInput`, defaulting an omitted condition `connector` to `'and'` (the wire form lets a caller drop `connector` on the last condition, because it joins nothing forward).
|
|
359
359
|
|
|
@@ -885,10 +885,10 @@ restored?.id // 'audit'
|
|
|
885
885
|
|
|
886
886
|
Register a live relation manager and load a row with a nested dot-path `include` list:
|
|
887
887
|
|
|
888
|
-
The tool opens no transaction. `unlink` removes
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
888
|
+
The tool opens no transaction. `unlink` removes the pair's one junction row, the row `link` wrote
|
|
889
|
+
under the pair's computed key, through the manager's bound storage. A failed removal leaves the pair
|
|
890
|
+
linked, and `links` still lists the target. Repeat `unlink` to complete removal. To unlink several
|
|
891
|
+
pairs as one unit, build the manager with `createRelationManager({ storage, relations })`
|
|
892
892
|
inside the host's `database.transaction(async (storage) => ...)` callback and use its tool only
|
|
893
893
|
within that scope. Let the failure propagate out of the callback so the transaction rolls back.
|
|
894
894
|
|
|
@@ -890,7 +890,7 @@ result.workflow.results() // every settled task's TaskResult, lineage-navigable
|
|
|
890
890
|
|
|
891
891
|
A run refuses what it cannot do before any task starts, and the promise rejects with a `SCHEDULE` `WorkflowError`. The definition door refuses a key the contract does not declare, so a misspelt `behaviour` reports an `extra` fault at `phases.0.tasks.0.behaviour` in `context.faults` instead of running a no-op. A tree with no task refuses too: `createWorkflow({ id: 'w', name: 'W', phases: [] })` still builds so a caller can `add` to it, and a refused live workflow stays unclaimed, so a corrected call can drive the same object. The same door guards `createWorkflow` and `WorkflowManager.add`, which throw, and a live `add`, which returns a `MUTATION` failure. One refusal lists every fault and every undeclared key, and a definition whose reads change refuses as unreadable.
|
|
892
892
|
|
|
893
|
-
The door repairs a leaf the way `parse` does, so a definition's `timeout: '5'` enters as `5`. A run option is not a definition and gets no repair, so `execute(definition, { timeout: '5' })` refuses the same value.
|
|
893
|
+
The definition door admits through the `repairValue` function, which repairs a lossless leaf the way `parse` does, so a definition's `timeout: '5'` enters as `5`. A run option is not a definition and gets no repair, so `execute(definition, { timeout: '5' })` refuses the same value.
|
|
894
894
|
|
|
895
895
|
### The `bail` policy — graceful vs halt
|
|
896
896
|
|
|
@@ -1086,7 +1086,7 @@ phase.patch({ concurrency: 2 }) // throws MUTATION unless this phase is `pending
|
|
|
1086
1086
|
|
|
1087
1087
|
Every one of these is refused gracefully (a `MUTATION` `Result` failure, never a throw) when a definition or a patch fails its contract or a patch is empty, each with `context.faults` listing every fault, when the container is terminal / `destroyed`, the target does not exist or is not `pending`, or the position falls outside the pending suffix; a `running` phase accepts an `add` only as a pure append — a live runner subscribed to that phase's own `add` event picks the new task up for same-run execution.
|
|
1088
1088
|
|
|
1089
|
-
|
|
1089
|
+
The patch door admits through the `repairValue` function, as the definition door does, so a lossless type repair enters repaired: `workflow.update(phase.id, { concurrency: '4' })` applies `concurrency: 4`, so the phase's `concurrency` reads `4` afterwards. An undeclared key, a lossy repair such as `'4.5'` for an integer, and a value that cannot be read refuse with their faults.
|
|
1090
1090
|
|
|
1091
1091
|
### Building the live tree by hand — `append`
|
|
1092
1092
|
|
package/dist/host/manifest.json
CHANGED
|
@@ -346,7 +346,7 @@
|
|
|
346
346
|
"storage": "agents/skills/orkestrel-journey/SKILL.md",
|
|
347
347
|
"destination": ".agents/skills/orkestrel-journey/SKILL.md",
|
|
348
348
|
"executable": false,
|
|
349
|
-
"digest": "
|
|
349
|
+
"digest": "80b4a58b50b070fa6083fe3ff4ca14ef8d22f202c15f1c0ce2be75905993c4b6"
|
|
350
350
|
},
|
|
351
351
|
{
|
|
352
352
|
"storage": "agents/skills/orkestrel-journey/agents/openai.yaml",
|
|
@@ -358,7 +358,7 @@
|
|
|
358
358
|
"storage": "agents/skills/orkestrel-journey/references/captures.md",
|
|
359
359
|
"destination": ".agents/skills/orkestrel-journey/references/captures.md",
|
|
360
360
|
"executable": false,
|
|
361
|
-
"digest": "
|
|
361
|
+
"digest": "87f87c8532871867948a3b45ec3717b835cbca168e36d82392e7760311d210c3"
|
|
362
362
|
},
|
|
363
363
|
{
|
|
364
364
|
"storage": "agents/skills/orkestrel-journey/references/decide.md",
|
|
@@ -460,7 +460,7 @@
|
|
|
460
460
|
"storage": "agents/skills/orkestrel-polish/references/capture-harness.md",
|
|
461
461
|
"destination": ".agents/skills/orkestrel-polish/references/capture-harness.md",
|
|
462
462
|
"executable": false,
|
|
463
|
-
"digest": "
|
|
463
|
+
"digest": "9e6dda1a3be870271723863f180a9fd5933953ea35c9a92524905766af25b828"
|
|
464
464
|
},
|
|
465
465
|
{
|
|
466
466
|
"storage": "agents/skills/orkestrel-publish/SKILL.md",
|
|
@@ -628,7 +628,7 @@
|
|
|
628
628
|
"storage": "claude/agents/orkestrel.md",
|
|
629
629
|
"destination": ".claude/agents/orkestrel.md",
|
|
630
630
|
"executable": false,
|
|
631
|
-
"digest": "
|
|
631
|
+
"digest": "9889130ed94124fe0f23edcc9ea27b3a2a3a03c8d685fabf72d9bf8d6649b88d"
|
|
632
632
|
},
|
|
633
633
|
{
|
|
634
634
|
"storage": "claude/agents/planner.md",
|
|
@@ -730,13 +730,13 @@
|
|
|
730
730
|
"storage": "claude/rules/typescript.md",
|
|
731
731
|
"destination": ".claude/rules/typescript.md",
|
|
732
732
|
"executable": false,
|
|
733
|
-
"digest": "
|
|
733
|
+
"digest": "25ed2168c556f5addf446731424395aa91d8eb7b0eb92b6edef7cff9651a6570"
|
|
734
734
|
},
|
|
735
735
|
{
|
|
736
736
|
"storage": "claude/rules/workspace.md",
|
|
737
737
|
"destination": ".claude/rules/workspace.md",
|
|
738
738
|
"executable": false,
|
|
739
|
-
"digest": "
|
|
739
|
+
"digest": "a6cb8abb75e63dfd7ea26b502f9aec6a9c80205e1c44c336c1c8cc6c540dd375"
|
|
740
740
|
},
|
|
741
741
|
{
|
|
742
742
|
"storage": "claude/rules/writing.md",
|
|
@@ -994,19 +994,19 @@
|
|
|
994
994
|
"storage": "guides/agent.md",
|
|
995
995
|
"destination": "guides/agent.md",
|
|
996
996
|
"executable": false,
|
|
997
|
-
"digest": "
|
|
997
|
+
"digest": "9985c8acc0c7debf976280b98735e7e071e49d9d8a248828e80223b20613e5f2"
|
|
998
998
|
},
|
|
999
999
|
{
|
|
1000
1000
|
"storage": "guides/brief.md",
|
|
1001
1001
|
"destination": "guides/brief.md",
|
|
1002
1002
|
"executable": false,
|
|
1003
|
-
"digest": "
|
|
1003
|
+
"digest": "86170e867caf9d33f06e6f8a734329ae38ef9ef1585606dc493f269be0658959"
|
|
1004
1004
|
},
|
|
1005
1005
|
{
|
|
1006
1006
|
"storage": "guides/browser.md",
|
|
1007
1007
|
"destination": "guides/browser.md",
|
|
1008
1008
|
"executable": false,
|
|
1009
|
-
"digest": "
|
|
1009
|
+
"digest": "cb79077f8e0df55e3eed41eb6636bcc732cb25b0e0e8be79f63a05c72445864c"
|
|
1010
1010
|
},
|
|
1011
1011
|
{
|
|
1012
1012
|
"storage": "guides/budget.md",
|
|
@@ -1018,7 +1018,7 @@
|
|
|
1018
1018
|
"storage": "guides/capture.md",
|
|
1019
1019
|
"destination": "guides/capture.md",
|
|
1020
1020
|
"executable": false,
|
|
1021
|
-
"digest": "
|
|
1021
|
+
"digest": "aa14ae83360a535e25d30356b5b8500ec0a7538b23726079cbd1a60a8479be06"
|
|
1022
1022
|
},
|
|
1023
1023
|
{
|
|
1024
1024
|
"storage": "guides/codec.md",
|
|
@@ -1048,7 +1048,7 @@
|
|
|
1048
1048
|
"storage": "guides/database.md",
|
|
1049
1049
|
"destination": "guides/database.md",
|
|
1050
1050
|
"executable": false,
|
|
1051
|
-
"digest": "
|
|
1051
|
+
"digest": "f6e19ac07185cab14342702d4e128d60e1bab85d593311af1045a1ab7b8b498a"
|
|
1052
1052
|
},
|
|
1053
1053
|
{
|
|
1054
1054
|
"storage": "guides/emitter.md",
|
|
@@ -1150,7 +1150,7 @@
|
|
|
1150
1150
|
"storage": "guides/process.md",
|
|
1151
1151
|
"destination": "guides/process.md",
|
|
1152
1152
|
"executable": false,
|
|
1153
|
-
"digest": "
|
|
1153
|
+
"digest": "a3271f4fae8bed6c35e3a3b66c7d657d4f86dcd22ea06c8e9448cb6c79a0b676"
|
|
1154
1154
|
},
|
|
1155
1155
|
{
|
|
1156
1156
|
"storage": "guides/program.md",
|
|
@@ -1180,7 +1180,7 @@
|
|
|
1180
1180
|
"storage": "guides/reason.md",
|
|
1181
1181
|
"destination": "guides/reason.md",
|
|
1182
1182
|
"executable": false,
|
|
1183
|
-
"digest": "
|
|
1183
|
+
"digest": "768ee916f2931219be0e8d69610d4037530b7edbbf33f5a77aa3e4b4bcb816cb"
|
|
1184
1184
|
},
|
|
1185
1185
|
{
|
|
1186
1186
|
"storage": "guides/relation.md",
|
|
@@ -1198,7 +1198,7 @@
|
|
|
1198
1198
|
"storage": "guides/scaffold.md",
|
|
1199
1199
|
"destination": "guides/scaffold.md",
|
|
1200
1200
|
"executable": false,
|
|
1201
|
-
"digest": "
|
|
1201
|
+
"digest": "98457f674dafe966f7d53bd525a74014496c4f5410f5a1fde0607ca1fc47e7a6"
|
|
1202
1202
|
},
|
|
1203
1203
|
{
|
|
1204
1204
|
"storage": "guides/sea.md",
|
|
@@ -1252,7 +1252,7 @@
|
|
|
1252
1252
|
"storage": "guides/test.md",
|
|
1253
1253
|
"destination": "guides/test.md",
|
|
1254
1254
|
"executable": false,
|
|
1255
|
-
"digest": "
|
|
1255
|
+
"digest": "25654abd6d15895a4298d49159dc775272dd2d93e02f76bbced6c89fb9bfd061"
|
|
1256
1256
|
},
|
|
1257
1257
|
{
|
|
1258
1258
|
"storage": "guides/timeout.md",
|
|
@@ -1264,13 +1264,13 @@
|
|
|
1264
1264
|
"storage": "guides/tool.md",
|
|
1265
1265
|
"destination": "guides/tool.md",
|
|
1266
1266
|
"executable": false,
|
|
1267
|
-
"digest": "
|
|
1267
|
+
"digest": "1a6baa0dbd4bf96d676a54820e168b04d605acf10f7cd494c66e645085f4f648"
|
|
1268
1268
|
},
|
|
1269
1269
|
{
|
|
1270
1270
|
"storage": "guides/toolbox.md",
|
|
1271
1271
|
"destination": "guides/toolbox.md",
|
|
1272
1272
|
"executable": false,
|
|
1273
|
-
"digest": "
|
|
1273
|
+
"digest": "220541231fd071268ab3d58c1a83ccbbd06f35fa3574007bce2239724f258e9d"
|
|
1274
1274
|
},
|
|
1275
1275
|
{
|
|
1276
1276
|
"storage": "guides/websocket.md",
|
|
@@ -1288,7 +1288,7 @@
|
|
|
1288
1288
|
"storage": "guides/workflow.md",
|
|
1289
1289
|
"destination": "guides/workflow.md",
|
|
1290
1290
|
"executable": false,
|
|
1291
|
-
"digest": "
|
|
1291
|
+
"digest": "325bb83cf2a30b3189703d26695f73ab5f3aebd074e1f8002af6a2d58b2af60f"
|
|
1292
1292
|
},
|
|
1293
1293
|
{
|
|
1294
1294
|
"storage": "guides/workspace.md",
|
|
@@ -1336,7 +1336,7 @@
|
|
|
1336
1336
|
"storage": "tests/config.test.ts",
|
|
1337
1337
|
"destination": "tests/config.test.ts",
|
|
1338
1338
|
"executable": false,
|
|
1339
|
-
"digest": "
|
|
1339
|
+
"digest": "2fdde0aa178e50cf03838ecd3516a58ca642dbb8c2fc59ddc2cf54be0a3b1a42"
|
|
1340
1340
|
},
|
|
1341
1341
|
{
|
|
1342
1342
|
"storage": "tests/policy.test.ts",
|
|
@@ -1417,5 +1417,5 @@
|
|
|
1417
1417
|
"scripts"
|
|
1418
1418
|
],
|
|
1419
1419
|
"surface": [],
|
|
1420
|
-
"digest": "
|
|
1420
|
+
"digest": "08d965160483170e4db000763be59daf7a99380f106bc5bda8c7c5d5541d7e49"
|
|
1421
1421
|
}
|
|
@@ -451,12 +451,14 @@ describe('selected faces', () => {
|
|
|
451
451
|
loaded.config.test.projects.length === 0
|
|
452
452
|
)
|
|
453
453
|
throw new Error('Missing journey projects')
|
|
454
|
-
// Each
|
|
454
|
+
// Each project appends the variant it provides and the variants it declares. The capture
|
|
455
|
+
// wrapper factory returns each project as configuration; a project factory is awaited.
|
|
455
456
|
const provided: Array<{ readonly variant: string; readonly names: readonly string[] }> = []
|
|
456
|
-
for (const
|
|
457
|
-
if (typeof factory !== 'function') throw new Error('Missing journey factory')
|
|
457
|
+
for (const entry of loaded.config.test.projects) {
|
|
458
458
|
const project = readConfigRecord(
|
|
459
|
-
|
|
459
|
+
typeof entry === 'function'
|
|
460
|
+
? await Reflect.apply(entry, undefined, [{ command: 'serve', mode: application }])
|
|
461
|
+
: entry,
|
|
460
462
|
)
|
|
461
463
|
const test = readConfigRecord(project.test)
|
|
462
464
|
expect(test.include).toEqual([`tests/app/${application}/integration.test.ts`])
|
|
@@ -525,17 +527,12 @@ describe('selected faces', () => {
|
|
|
525
527
|
if (!Array.isArray(projects) || projects.length === 0)
|
|
526
528
|
throw new Error('Missing journey projects')
|
|
527
529
|
for (const project of projects) {
|
|
528
|
-
|
|
530
|
+
const resolved: unknown =
|
|
531
|
+
typeof project === 'function'
|
|
532
|
+
? await Reflect.apply(project, undefined, [{ command: 'serve', mode: application }])
|
|
533
|
+
: project
|
|
529
534
|
const held = readConfigRecord(
|
|
530
|
-
readConfigRecord(
|
|
531
|
-
readConfigRecord(
|
|
532
|
-
readConfigRecord(
|
|
533
|
-
await Reflect.apply(project, undefined, [
|
|
534
|
-
{ command: 'serve', mode: application },
|
|
535
|
-
]),
|
|
536
|
-
).test,
|
|
537
|
-
).browser,
|
|
538
|
-
).commands,
|
|
535
|
+
readConfigRecord(readConfigRecord(readConfigRecord(resolved).test).browser).commands,
|
|
539
536
|
)
|
|
540
537
|
for (const commands of registered) {
|
|
541
538
|
for (const [key, command] of Object.entries(commands)) expect(held[key]).toBe(command)
|
|
@@ -546,23 +543,19 @@ describe('selected faces', () => {
|
|
|
546
543
|
const factory = factories.appJourney
|
|
547
544
|
if (typeof factory !== 'function') throw new Error('Missing application journey')
|
|
548
545
|
expect(() =>
|
|
549
|
-
Reflect.apply(factory, undefined, [
|
|
550
|
-
{ name: 'desktop', width: 1280, height: 800 },
|
|
551
|
-
[],
|
|
552
|
-
'absent',
|
|
553
|
-
]),
|
|
546
|
+
Reflect.apply(factory, undefined, [{ name: 'desktop', width: 1280, height: 800 }, 'absent']),
|
|
554
547
|
).toThrow('not declared')
|
|
555
548
|
// The record names an application exactly when its exact-case entry exists.
|
|
556
549
|
const variant = { name: 'desktop', width: 1280, height: 800 }
|
|
557
550
|
for (const application of applications) {
|
|
558
551
|
expect(
|
|
559
552
|
readConfigRecord(
|
|
560
|
-
readConfigRecord(Reflect.apply(factory, undefined, [variant,
|
|
553
|
+
readConfigRecord(Reflect.apply(factory, undefined, [variant, application])).test,
|
|
561
554
|
).include,
|
|
562
555
|
).toStrictEqual([`tests/app/${application}/integration.test.ts`])
|
|
563
556
|
}
|
|
564
557
|
for (const application of candidates.filter((name) => !applications.includes(name))) {
|
|
565
|
-
expect(() => Reflect.apply(factory, undefined, [variant,
|
|
558
|
+
expect(() => Reflect.apply(factory, undefined, [variant, application])).toThrow(
|
|
566
559
|
'not declared',
|
|
567
560
|
)
|
|
568
561
|
}
|
|
@@ -1291,12 +1284,11 @@ describe('root configuration', () => {
|
|
|
1291
1284
|
throw new Error(`${wrapper} carries no journey projects`)
|
|
1292
1285
|
}
|
|
1293
1286
|
const tests: object[] = []
|
|
1294
|
-
for (const
|
|
1295
|
-
|
|
1296
|
-
|
|
1297
|
-
|
|
1298
|
-
|
|
1299
|
-
])
|
|
1287
|
+
for (const entry of projects) {
|
|
1288
|
+
const project: unknown =
|
|
1289
|
+
typeof entry === 'function'
|
|
1290
|
+
? await Reflect.apply(entry, undefined, [{ command: 'serve', mode }])
|
|
1291
|
+
: entry
|
|
1300
1292
|
if (typeof project !== 'object' || project === null)
|
|
1301
1293
|
throw new Error('A journey project is not a configuration')
|
|
1302
1294
|
const test: unknown = Object.getOwnPropertyDescriptor(project, 'test')?.value
|