@orkestrel/agent 0.0.3 → 0.0.4

package/dist/src/core/index.d.ts

@@ -1,21 +1,14 @@
-import { BooleanShape } from '@orkestrel/contract';
 import { BudgetInterface } from '@orkestrel/budget';
 import { DriverInterface } from '@orkestrel/database';
 import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
-import { LiteralShape } from '@orkestrel/contract';
-import { NumberShape } from '@orkestrel/contract';
-import { ObjectShape } from '@orkestrel/contract';
-import { OptionalShape } from '@orkestrel/contract';
 import { QueueInterface } from '@orkestrel/queue';
 import { QueueStoreInterface } from '@orkestrel/queue';
 import { RunnerInterface } from '@orkestrel/workflow';
 import { SchedulerInterface } from '@orkestrel/workflow';
-import { StringShape } from '@orkestrel/contract';
 import { TableInterface } from '@orkestrel/database';
 import { TokenUsage } from '@orkestrel/budget';
-import { UnionShape } from '@orkestrel/contract';
 
 /**
  * The agent loop — composes a {@link ProviderInterface}, an {@link AgentContext}, and
@@ -716,13 +709,21 @@ export declare interface AgentRegistryInterface {
  * `providers` is required (a job always names a provider); `tools` / `authorities` /
  * `schedulers` are optional pools, each an entity-keyed record (§8) mapping a registry
  * name to its live object. A name absent from its pool throws when resolved (see
- * {@link AgentRegistryInterface}).
+ * {@link AgentRegistryInterface}). `store` is the durable {@link ConversationStoreInterface}
+ * every agent this registry builds carries: each built agent gets its OWN store-backed
+ * {@link ConversationManagerInterface} over THIS shared store — a fresh conversation id per
+ * build (minted by the seeded `add`), so concurrent builds never collide, and the store
+ * simply accumulates one snapshot per built agent that later calls `save`. Persistence
+ * stays caller-triggered (`open` / `save`) — `build` never hydrates, so `build` stays
+ * SYNCHRONOUS. Omitted ⇒ every built agent gets a registry-only manager, byte-identical
+ * to today.
  */
 export declare interface AgentRegistryOptions {
     readonly providers: Readonly<Record<string, ProviderInterface>>;
     readonly tools?: Readonly<Record<string, ToolInterface>>;
     readonly authorities?: Readonly<Record<string, AuthorityInterface>>;
     readonly schedulers?: Readonly<Record<string, SchedulerInterface>>;
+    readonly store?: ConversationStoreInterface;
 }
 
 /**
@@ -2529,68 +2530,6 @@ export declare function createWorkspace(options?: WorkspaceOptions): WorkspaceIn
  */
 export declare function createWorkspaceManager(options?: WorkspaceManagerOptions): WorkspaceManagerInterface;
 
-/**
- * Wrap a {@link WorkspaceManagerInterface} as an LLM-callable {@link ToolInterface} — it ADVERTISES
- * the `operation`-discriminated 13-op union ({@link import('./shapers.js').workspaceToolShape}) as
- * its `parameters`, and its handler PARSES the model-supplied args against that contract and
- * DISPATCHES the matched operation against the manager's ACTIVE workspace (the registry ops drive
- * the manager itself), returning the plain result (throwing a typed {@link WorkspaceError} on
- * failure).
- *
- * @remarks
- * MANAGER-DRIVEN: every edit / read op (read / list / has / search / replace / write / splice /
- * prepend / append / move / remove) targets `manager.active`, so the model edits whichever workspace
- * is active and a host can re-point it ({@link WorkspaceManagerInterface.switch}) between turns —
- * wire the agent's registry in via `createWorkspaceTool(agent.context.workspaces)`. Two REGISTRY ops
- * make the model self-sufficient: `workspaces` LISTS the registered workspaces (each
- * `{ id, files, active }`) so it can discover an id, and `switch` re-points the active workspace by
- * id (lenient — an unknown id is a no-op reporting `switched: false`, never a throw).
- *
- * NO-ACTIVE RULE (the ergonomic seam): a WRITING op (write / splice / prepend / append / move /
- * remove / replace) run when `manager.active` is `undefined` AUTO-CREATES + activates a default
- * workspace (`manager.add()`) so the model can just start writing; a pure-READ op (read / list / has
- * / search) against no active workspace returns the EMPTY result (`undefined` / `[]` / `false`),
- * never creating one and never throwing.
- *
- * A plain {@link ToolManagerInterface}-compatible tool (so `createMCPServer` / `createMCPRoutes`
- * expose it over MCP for free — nothing MCP is wired here), built as a factory + dispatch closure
- * in the same consumer-edge style as `createWorkflowTool` in `@orkestrel/workflow` (NOT a class —
- * their signatures differ; the shared idea is that concrete tools live at the factories edge over
- * a pure tool runtime). The
- * contract is compiled ONCE and its JSON Schema is narrowed to the open
- * `Readonly<Record<string, unknown>>` a tool advertises via the shared
- * {@link schemaToParameters} contracts helper, never an assertion
- * (§14) — a compiled contract schema is always a record, so it passes; the `undefined` fallback only
- * satisfies the type's optionality.
- *
- * The handler conforms to the universal tool-handler contract (AGENTS §14): it `contract.parse`s the
- * args, THROWS a `TOOL` {@link WorkspaceError} when no operation arm matched (a malformed / unknown
- * operation), else `switch`es on `op.operation` and RETURNS the plain result — letting a
- * `WorkspaceError` raised by the live workspace (`MODALITY` / `PATTERN` / `RANGE`) PROPAGATE
- * unCAUGHT. The {@link import('./tools/ToolManager.js').ToolManager} performs the ONE
- * canonical wrap (`{ id, name, value }` on a return; `{ id, name, error }` on a throw, ISOLATED so
- * nothing escapes the run), so the outcome appears EXACTLY ONCE over BOTH the agent loop and MCP (a
- * throw → MCP `isError: true`). There is no `{ ok, output, duration }` envelope. The range edit is
- * the FLAT `'splice'` op: its four flat caret integers are reassembled into a {@link import('./types.js').Range}
- * by {@link rangeOf} and fed to the workspace's ranged `write`.
- *
- * @param manager - The workspace registry the tool reads + edits (its ACTIVE workspace; closed over by the handler)
- * @param options - Optional advertised `name` / `description` overrides (see {@link WorkspaceToolOptions})
- * @returns A {@link ToolInterface} (named {@link import('./constants.js').WORKSPACE_TOOL_NAME} by
- *   default) whose `parameters` advertise the `operation`-discriminated union schema
- *
- * @example
- * ```ts
- * import { createWorkspaceManager, createWorkspaceTool, createToolManager } from '@src/core'
- *
- * const manager = createWorkspaceManager()
- * const tool = createWorkspaceTool(manager) // edits the manager's ACTIVE workspace
- * const tools = createToolManager()
- * tools.add(tool) // a model can now read + edit the active workspace by calling `workspace`
- * ```
- */
-export declare function createWorkspaceTool(manager: WorkspaceManagerInterface, options?: WorkspaceToolOptions): ToolInterface;
-
 /**
  * A {@link ConversationStoreInterface} backed by one table of the `databases` layer — a
  * conversation's durable state IS a row, so persistence reduces to keyed point-access (`get` / `set`
@@ -3877,10 +3816,10 @@ export declare interface Range {
 }
 
 /**
- * Assemble a 1-based nested {@link Range} from the four FLAT caret integers of the workspace tool's
- * `'splice'` operation — the bridge from the small-model FLAT surface
- * ({@link import('./types.js').WorkspaceOperation}) back to the nested {@link Range} the
- * {@link import('./workspaces/Workspace.js').Workspace} edit surface speaks.
+ * Assemble a 1-based nested {@link Range} from four FLAT caret integers — the bridge a
+ * workspace-editing tool (see `@orkestrel/tool`) uses from its small-model FLAT surface back to the
+ * nested {@link Range} the {@link import('./workspaces/Workspace.js').Workspace} edit surface
+ * speaks. Published as a public helper for that consumer.
  *
  * @remarks
  * Pairs `(fromLine, fromColumn)` into `start` and `(toLine, toColumn)` into `end` verbatim — a pure
@@ -4434,6 +4373,7 @@ export declare class Tool implements ToolInterface {
     #private;
     readonly name: string;
     readonly description?: string;
+    readonly summary?: string;
     readonly parameters?: Readonly<Record<string, unknown>>;
     constructor(options: ToolOptions);
     execute(args: Readonly<Record<string, unknown>>): Promise<unknown> | unknown;
@@ -4490,6 +4430,12 @@ export declare interface ToolDefinition {
  * (§14), never assert; the manager isolates a throw into a {@link ToolResult} `error`.
  */
 export declare interface ToolInterface extends ToolDefinition {
+    /**
+     * A one-or-two-sentence concise description advertised to the model IN PLACE of the
+     * full `description` (which stays on the tool for on-demand retrieval, e.g. a
+     * describe tool); absent ⇒ the full `description` is advertised exactly as today.
+     */
+    readonly summary?: string;
     /**
      * Run the tool. `args` is the model-supplied `unknown` JSON object — narrow it
      * inside (§14); the manager isolates a throw into a {@link ToolResult} `error`.
@@ -4511,7 +4457,9 @@ export declare interface ToolInterface extends ToolDefinition {
  *   (last write wins). `count` is the map size, `tool(name)` looks one up, `tools()`
  *   lists them in insertion order, and `definitions()` maps each to a plain
  *   {@link ToolDefinition} (`name` / `description?` / `parameters?`, the `execute`
- *   handler stripped) — exactly what a provider advertises to the model.
+ *   handler stripped) — exactly what a provider advertises to the model, with
+ *   `tool.summary ?? tool.description` advertised as `description` (a lean `summary`
+ *   stands in for the full text when set).
  * - **Per-call error isolation (the load-bearing part).** `execute` resolves a
  *   {@link ToolCall}'s tool by name and ALWAYS resolves a {@link ToolResult}: an
  *   unknown name → `{ id, name, error: 'tool not found: <name>' }`; a successful run →
@@ -4555,7 +4503,9 @@ export declare class ToolManager implements ToolManagerInterface {
  * - **Registry.** `add` registers one tool or a batch (§9.2), keyed by `tool.name`
  *   (a re-`add` of the same name overwrites — last write wins); `count` is the number
  *   registered. `tool(name)` looks one up; `tools()` lists them in insertion order;
- *   `definitions()` strips each to a plain {@link ToolDefinition} for the provider.
+ *   `definitions()` strips each to a plain {@link ToolDefinition} for the provider,
+ *   advertising `tool.summary ?? tool.description` in the definition's `description`
+ *   field — a lean `summary` stands in for the full `description` when set.
  * - **Per-call error isolation.** `execute` resolves a {@link ToolCall}'s tool by name
  *   and runs it, ALWAYS resolving a {@link ToolResult}: a success carries `value`, a
  *   handler throw is caught into `error`, and an unknown name becomes a not-found
@@ -4586,12 +4536,16 @@ export declare interface ToolManagerInterface {
  * @remarks
  * `name` is required (it keys the tool in a {@link ToolManagerInterface} and is what
  * the model calls); `description` and `parameters` are the optional JSON-Schema the
- * provider advertises (forwarded verbatim). `execute` receives the model-supplied
- * arguments record and returns the tool's result (sync or async).
+ * provider advertises (forwarded verbatim). `summary`, when set, is a lean
+ * one-or-two-sentence advertisement used IN PLACE of `description` in a
+ * {@link ToolManagerInterface.definitions} listing — `description` stays available on
+ * the tool for on-demand retrieval. `execute` receives the model-supplied arguments
+ * record and returns the tool's result (sync or async).
  */
 export declare interface ToolOptions {
     readonly name: string;
     readonly description?: string;
+    readonly summary?: string;
     readonly parameters?: Readonly<Record<string, unknown>>;
     readonly execute: (args: Readonly<Record<string, unknown>>) => Promise<unknown> | unknown;
 }
@@ -4699,40 +4653,6 @@ export declare class Workspace implements WorkspaceInterface {
  */
 export declare const WORKSPACE_SECTION_HEADER = "## Workspace";
 
-/**
- * The DESCRIPTION {@link import('./factories.js').createWorkspaceTool} advertises — a multi-line
- * guide that teaches a small model how to drive a workspace through the single `operation`-keyed
- * tool.
- *
- * @remarks
- * Mirrors the analogous `WORKFLOW_TOOL_DESCRIPTION` in `@orkestrel/workflow`'s teaching style:
- * names the `operation` discriminant field, enumerates all 13 operations with their FLAT fields,
- * gives a worked example for the common ones (read / write / search / replace / splice), and embeds
- * {@link WORKSPACE_TOOL_EXAMPLE} verbatim (pinned by a parity test). The range edit is the FLAT
- * `'splice'` op — four positive-integer caret components, NOT a nested range — the ergonomic lever
- * a 2B model can fill. The edit / read ops target the ACTIVE workspace (one is auto-created on the
- * first edit when none is active); the `workspaces` / `switch` ops let the model move between
- * workspaces.
- */
-export declare const WORKSPACE_TOOL_DESCRIPTION: string;
-
-/**
- * A valid {@link WorkspaceOperation} object — the canonical example embedded VERBATIM in
- * {@link WORKSPACE_TOOL_DESCRIPTION} and pinned by a parity test (it must satisfy the compiled
- * contract's `is`), so the doc example can never drift from a real, contract-valid operation.
- *
- * @remarks
- * A `'write'` op (the most common authoring action): create or overwrite `notes.txt` with
- * `hello`. Frozen so it cannot be mutated in place.
- */
-export declare const WORKSPACE_TOOL_EXAMPLE: WorkspaceOperation;
-
-/**
- * The name {@link import('./factories.js').createWorkspaceTool} advertises by default — the key a
- * model calls and the {@link import('./types.js').ToolManagerInterface} registers under.
- */
-export declare const WORKSPACE_TOOL_NAME = "workspace";
-
 /**
  * An error thrown by the in-memory {@link import('./workspaces/Workspace.js').Workspace} edit
  * surface.
@@ -4758,10 +4678,10 @@ export declare class WorkspaceError extends Error {
  * - `MODALITY` — a text-only op (ranged read/write, `prepend`, `append`) was aimed at a binary file.
  * - `PATTERN` — a `search` / `replace` `query` was an invalid regular expression (with `regex: true`).
  * - `RANGE` — a ranged `write` got a structurally invalid {@link Range} (inverted, or a sub-1 line/column).
- * - `TOOL` — a handler-level validation fault from {@link import('./factories.js').createWorkspaceTool}:
- *   the agent-supplied args were a malformed / unknown {@link WorkspaceOperation} (none of the 13 arms
- *   matched). Distinct from the surface faults above (which the live workspace raises) — this is the
- *   tool boundary rejecting an un-parseable operation before any workspace call.
+ * - `TOOL` — a handler-level validation fault raised by a workspace-editing tool boundary (see
+ *   `@orkestrel/tool`) when the agent-supplied args were malformed / unknown. Distinct from the
+ *   surface faults above (which the live workspace raises) — this is the tool boundary rejecting an
+ *   un-parseable operation before any workspace call.
  */
 export declare type WorkspaceErrorCode = 'MODALITY' | 'PATTERN' | 'RANGE' | 'TOOL';
 
@@ -5017,124 +4937,6 @@ export declare interface WorkspaceManagerOptions {
     readonly store?: WorkspaceStoreInterface;
 }
 
-/**
- * One operation an agent invokes through {@link import('./factories.js').createWorkspaceTool} — a
- * FLAT, descriptive tagged union over the 13 workspace edit / read / navigation actions,
- * discriminated by the `operation` literal (AGENTS §4.8: a discriminant is named for its axis — the
- * action being performed — NEVER `kind`).
- *
- * @remarks
- * This is the SOURCE OF TRUTH the tool contract is typed to ({@link import('./shapers.js').workspaceToolShape}
- * compiles to a structurally-identical guard / parser / JSON Schema). Every field is FLAT (no nested
- * objects) — the small-model ergonomic lever: a range edit is the four flat integers of the
- * `'splice'` arm (`fromLine` / `fromColumn` / `toLine` / `toColumn`), reassembled into a 1-based
- * {@link Range} by {@link import('./helpers.js').rangeOf}, never a nested `{ start, end }`. Each EDIT
- * / READ arm maps onto exactly one {@link WorkspaceInterface} call against the manager's ACTIVE
- * workspace; the two REGISTRY arms (`switch` / `workspaces`) drive the
- * {@link WorkspaceManagerInterface} pointer instead — `workspaces` LISTS the workspaces the model
- * can move between, and `switch` re-points which one the edit / read arms target.
- */
-export declare type WorkspaceOperation = 
-/** Read a whole text file's text by `path` from the ACTIVE workspace (a binary / absent path — or no active workspace — yields no content). */
-    {
-    readonly operation: 'read';
-    readonly path: string;
-}
-/** List every file in the ACTIVE workspace (path / state / size / lines / kind summaries); `[]` when no workspace is active. */
-| {
-    readonly operation: 'list';
-}
-/** Whether a file exists at `path` in the ACTIVE workspace (`false` when no workspace is active). */
-| {
-    readonly operation: 'has';
-    readonly path: string;
-}
-/**
-* Scan every text file for `query`, returning each hit (path + 1-based line / column + the line).
-*
-* @remarks
-* `regex` treats `query` as a regular-expression source (default `false` — a literal substring);
-* `exact` matches case-sensitively (default `true`); `limit` caps the total hits returned.
-*/
-| {
-    readonly operation: 'search';
-    readonly query: string;
-    readonly regex?: boolean;
-    readonly exact?: boolean;
-    readonly limit?: number;
-}
-/**
-* Replace `query` with `replacement` across every text file, returning the tally.
-*
-* @remarks
-* Same matching axes as `search`: `regex` (default `false`), `exact` (default `true`), `limit`
-* (cap the total replacements).
-*/
-| {
-    readonly operation: 'replace';
-    readonly query: string;
-    readonly replacement: string;
-    readonly regex?: boolean;
-    readonly exact?: boolean;
-    readonly limit?: number;
-}
-/** Write (create or overwrite) the whole file at `path` with `content`. */
-| {
-    readonly operation: 'write';
-    readonly path: string;
-    readonly content: string;
-}
-/**
-* Splice `content` into an existing text file, replacing the 1-based range
-* `(fromLine, fromColumn)` (INCLUSIVE) → `(toLine, toColumn)` (EXCLUSIVE).
-*
-* @remarks
-* The FLAT range edit — the four positive-integer caret components reassemble into a {@link Range}
-* ({@link import('./helpers.js').rangeOf}). An empty span (`from === to`) inserts; a span past the
-* end is clamped. An inverted / sub-1 range throws `RANGE`; a binary target throws `MODALITY`.
-*/
-| {
-    readonly operation: 'splice';
-    readonly path: string;
-    readonly content: string;
-    readonly fromLine: number;
-    readonly fromColumn: number;
-    readonly toLine: number;
-    readonly toColumn: number;
-}
-/** Prepend `content` to the start of the file at `path` (creating it when absent). */
-| {
-    readonly operation: 'prepend';
-    readonly path: string;
-    readonly content: string;
-}
-/** Append `content` to the end of the file at `path` (creating it when absent). */
-| {
-    readonly operation: 'append';
-    readonly path: string;
-    readonly content: string;
-}
-/** Re-key the file `from` → `to` (overwriting an occupied target). */
-| {
-    readonly operation: 'move';
-    readonly from: string;
-    readonly to: string;
-}
-/** Remove the file at `path` from the workspace. */
-| {
-    readonly operation: 'remove';
-    readonly path: string;
-}
-/** List the workspaces the model can move between — each `{ id, files, active }` — so it can choose an `id` to `switch` to. */
-| {
-    readonly operation: 'workspaces';
-}
-/** Re-point the manager's ACTIVE workspace to the one with `id` (an unknown `id` is a lenient no-op). The edit / read arms target the active workspace from then on. */
-| {
-    readonly operation: 'switch';
-    readonly id: string;
-};
-
 /**
  * Options for {@link import('./factories.js').createWorkspace} / the
  * {@link import('./workspaces/Workspace.js').Workspace} constructor.
@@ -5240,91 +5042,4 @@ export declare interface WorkspaceStoreInterface {
     delete(id: string): Promise<void>;
 }
 
-/**
- * Options for {@link import('./factories.js').createWorkspaceTool} — optional overrides of the
- * advertised tool `name` / `description`.
- *
- * @param options - The workspace-tool options
- *
- * @remarks
- * - `name` — the advertised tool name a model calls; defaults to {@link import('./constants.js').WORKSPACE_TOOL_NAME} (`'workspace'`).
- * - `description` — the model-facing description; defaults to {@link import('./constants.js').WORKSPACE_TOOL_DESCRIPTION} (the operation guide). Deliberately minimal (AGENTS §21) — the tool needs no depth / ancestry (it has no recursion).
- */
-export declare interface WorkspaceToolOptions {
-    readonly name?: string;
-    readonly description?: string;
-}
-
-/**
- * The shape of a {@link import('./types.js').WorkspaceOperation} — a descriptive tagged union over
- * the 13 workspace edit / read / navigation operations, discriminated by the `operation` literal
- * (never a bare `kind`; AGENTS §4.8). Each variant leads with its `operation` discriminant then its
- * FLAT fields, every field via `stringShape` / `optionalShape` / `integerShape({ min: 1 })` /
- * `booleanShape`, each carrying a strong field-level `description`.
- *
- * @remarks
- * The union compiles to an `anyOf` JSON Schema + a `unionOf` guard + a first-match parser
- * automatically ({@link import('./factories.js').createWorkspaceTool} types the result to the
- * hand-written `WorkspaceOperation`). `limit` and the four `'splice'` caret components are POSITIVE
- * integers (`integerShape({ min: 1 })`); `regex` / `exact` are `optionalShape(booleanShape(...))`.
- * The two REGISTRY arms — `workspaces` (list the workspaces the model can move between) and `switch`
- * (re-point the active one by `id`) — let a model DISCOVER then CHOOSE which workspace the edit /
- * read arms target. The descriptions are the small-model ergonomic lever — they ride into the
- * advertised schema so a model authoring an operation gets per-field guidance.
- */
-export declare const workspaceToolShape: UnionShape<[ ObjectShape<{
-    operation: LiteralShape<readonly ["read"]>;
-    path: StringShape;
-}>, ObjectShape<{
-    operation: LiteralShape<readonly ["list"]>;
-}>, ObjectShape<{
-    operation: LiteralShape<readonly ["has"]>;
-    path: StringShape;
-}>, ObjectShape<{
-    operation: LiteralShape<readonly ["search"]>;
-    query: StringShape;
-    regex: OptionalShape<BooleanShape>;
-    exact: OptionalShape<BooleanShape>;
-    limit: OptionalShape<NumberShape>;
-}>, ObjectShape<{
-    operation: LiteralShape<readonly ["replace"]>;
-    query: StringShape;
-    replacement: StringShape;
-    regex: OptionalShape<BooleanShape>;
-    exact: OptionalShape<BooleanShape>;
-    limit: OptionalShape<NumberShape>;
-}>, ObjectShape<{
-    operation: LiteralShape<readonly ["write"]>;
-    path: StringShape;
-    content: StringShape;
-}>, ObjectShape<{
-    operation: LiteralShape<readonly ["splice"]>;
-    path: StringShape;
-    content: StringShape;
-    fromLine: NumberShape;
-    fromColumn: NumberShape;
-    toLine: NumberShape;
-    toColumn: NumberShape;
-}>, ObjectShape<{
-    operation: LiteralShape<readonly ["prepend"]>;
-    path: StringShape;
-    content: StringShape;
-}>, ObjectShape<{
-    operation: LiteralShape<readonly ["append"]>;
-    path: StringShape;
-    content: StringShape;
-}>, ObjectShape<{
-    operation: LiteralShape<readonly ["move"]>;
-    from: StringShape;
-    to: StringShape;
-}>, ObjectShape<{
-    operation: LiteralShape<readonly ["remove"]>;
-    path: StringShape;
-}>, ObjectShape<{
-    operation: LiteralShape<readonly ["workspaces"]>;
-}>, ObjectShape<{
-    operation: LiteralShape<readonly ["switch"]>;
-    id: StringShape;
-}>]>;
-
 export { }