@orkestrel/agent 0.0.2 → 0.0.4

package/dist/src/core/index.cjs

@@ -120,64 +120,6 @@ var EXTENSION_TO_LANGUAGE = Object.freeze({
 	svg: "xml",
 	txt: "text"
 });
-/**
-* The name {@link import('./factories.js').createWorkspaceTool} advertises by default — the key a
-* model calls and the {@link import('./types.js').ToolManagerInterface} registers under.
-*/
-var WORKSPACE_TOOL_NAME = "workspace";
-/**
-* 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.
-*/
-var WORKSPACE_TOOL_EXAMPLE = Object.freeze({
-	operation: "write",
-	path: "notes.txt",
-	content: "hello"
-});
-/**
-* 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.
-*/
-var WORKSPACE_TOOL_DESCRIPTION = [
-	"Read and edit files in a workspace. Every call is ONE operation, chosen by the \"operation\" field.",
-	"All file operations act on the ACTIVE workspace; use \"workspaces\" then \"switch\" to move between workspaces.",
-	"",
-	"Operations (each takes the fields listed):",
-	"- read     { \"operation\": \"read\", \"path\": \"<file>\" } — return the file's text.",
-	"- list     { \"operation\": \"list\" } — list every file in the active workspace (path, state, size, lines, kind).",
-	"- has      { \"operation\": \"has\", \"path\": \"<file>\" } — whether the file exists.",
-	"- search   { \"operation\": \"search\", \"query\": \"<text>\", \"regex\"?: bool, \"exact\"?: bool, \"limit\"?: int } — find lines matching the query across all files.",
-	"- replace  { \"operation\": \"replace\", \"query\": \"<text>\", \"replacement\": \"<text>\", \"regex\"?: bool, \"exact\"?: bool, \"limit\"?: int } — replace matches across all files.",
-	"- write    { \"operation\": \"write\", \"path\": \"<file>\", \"content\": \"<text>\" } — create or overwrite the whole file.",
-	"- splice   { \"operation\": \"splice\", \"path\": \"<file>\", \"content\": \"<text>\", \"fromLine\": int, \"fromColumn\": int, \"toLine\": int, \"toColumn\": int } — replace a 1-based range (from inclusive, to exclusive) with content.",
-	"- prepend  { \"operation\": \"prepend\", \"path\": \"<file>\", \"content\": \"<text>\" } — add content to the start of the file.",
-	"- append   { \"operation\": \"append\", \"path\": \"<file>\", \"content\": \"<text>\" } — add content to the end of the file.",
-	"- move     { \"operation\": \"move\", \"from\": \"<file>\", \"to\": \"<file>\" } — rename / move a file.",
-	"- remove   { \"operation\": \"remove\", \"path\": \"<file>\" } — delete a file.",
-	"- workspaces { \"operation\": \"workspaces\" } — list the workspaces you can switch between (each id, file count, active).",
-	"- switch   { \"operation\": \"switch\", \"id\": \"<id>\" } — make the workspace with that id active (ids come from \"workspaces\").",
-	"",
-	"Notes: lines and columns are 1-based (column 1 is the first character). \"regex\" defaults to false (a literal substring), \"exact\" defaults to true (case-sensitive). \"search\"/\"replace\"/\"splice\" act only on text files. Editing with no active workspace auto-creates one.",
-	"",
-	"Example — write a file:",
-	JSON.stringify(WORKSPACE_TOOL_EXAMPLE)
-].join("\n");
 //#endregion
 //#region src/core/errors.ts
 /**
@@ -337,93 +279,6 @@ function isWorkspaceError(value) {
 	return value instanceof WorkspaceError;
 }
 //#endregion
-//#region src/core/shapers.ts
-/**
-* 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.
-*/
-var workspaceToolShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_contract.objectShape)({
-	operation: (0, _orkestrel_contract.literalShape)(["read"], { description: "Read a whole text file's text by path." }),
-	path: (0, _orkestrel_contract.stringShape)({ description: "The path of the file to read." })
-}), (0, _orkestrel_contract.objectShape)({ operation: (0, _orkestrel_contract.literalShape)(["list"], { description: "List every file in the workspace." }) }), (0, _orkestrel_contract.objectShape)({
-	operation: (0, _orkestrel_contract.literalShape)(["has"], { description: "Check whether a file exists at the path." }),
-	path: (0, _orkestrel_contract.stringShape)({ description: "The path to check for." })
-}), (0, _orkestrel_contract.objectShape)({
-	operation: (0, _orkestrel_contract.literalShape)(["search"], { description: "Search every text file for a query, returning each hit." }),
-	query: (0, _orkestrel_contract.stringShape)({ description: "The text (or regular-expression source) to search for." }),
-	regex: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Treat the query as a regular expression. Defaults to false (a literal substring)." })),
-	exact: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Match case-sensitively. Defaults to true (set false for case-insensitive)." })),
-	limit: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.integerShape)({
-		min: 1,
-		description: "Stop after this many matches across all files. Omitted means unlimited."
-	}))
-}), (0, _orkestrel_contract.objectShape)({
-	operation: (0, _orkestrel_contract.literalShape)(["replace"], { description: "Replace a query with a replacement across every text file." }),
-	query: (0, _orkestrel_contract.stringShape)({ description: "The text (or regular-expression source) to replace." }),
-	replacement: (0, _orkestrel_contract.stringShape)({ description: "The text to substitute for each match." }),
-	regex: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Treat the query as a regular expression. Defaults to false (a literal substring)." })),
-	exact: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Match case-sensitively. Defaults to true (set false for case-insensitive)." })),
-	limit: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.integerShape)({
-		min: 1,
-		description: "Stop after this many replacements across all files. Omitted means unlimited."
-	}))
-}), (0, _orkestrel_contract.objectShape)({
-	operation: (0, _orkestrel_contract.literalShape)(["write"], { description: "Create or overwrite a whole file with content." }),
-	path: (0, _orkestrel_contract.stringShape)({ description: "The path of the file to write." }),
-	content: (0, _orkestrel_contract.stringShape)({ description: "The full new contents of the file." })
-}), (0, _orkestrel_contract.objectShape)({
-	operation: (0, _orkestrel_contract.literalShape)(["splice"], { description: "Replace a 1-based range of an existing text file (from inclusive, to exclusive) with content." }),
-	path: (0, _orkestrel_contract.stringShape)({ description: "The path of the text file to edit." }),
-	content: (0, _orkestrel_contract.stringShape)({ description: "The text to splice in place of the range." }),
-	fromLine: (0, _orkestrel_contract.integerShape)({
-		min: 1,
-		description: "The 1-based start line of the range (inclusive)."
-	}),
-	fromColumn: (0, _orkestrel_contract.integerShape)({
-		min: 1,
-		description: "The 1-based start column of the range (inclusive; column 1 is the first character)."
-	}),
-	toLine: (0, _orkestrel_contract.integerShape)({
-		min: 1,
-		description: "The 1-based end line of the range (exclusive)."
-	}),
-	toColumn: (0, _orkestrel_contract.integerShape)({
-		min: 1,
-		description: "The 1-based end column of the range (exclusive)."
-	})
-}), (0, _orkestrel_contract.objectShape)({
-	operation: (0, _orkestrel_contract.literalShape)(["prepend"], { description: "Add content to the start of a file (creating it when absent)." }),
-	path: (0, _orkestrel_contract.stringShape)({ description: "The path of the file to prepend to." }),
-	content: (0, _orkestrel_contract.stringShape)({ description: "The text to add at the start of the file." })
-}), (0, _orkestrel_contract.objectShape)({
-	operation: (0, _orkestrel_contract.literalShape)(["append"], { description: "Add content to the end of a file (creating it when absent)." }),
-	path: (0, _orkestrel_contract.stringShape)({ description: "The path of the file to append to." }),
-	content: (0, _orkestrel_contract.stringShape)({ description: "The text to add at the end of the file." })
-}), (0, _orkestrel_contract.objectShape)({
-	operation: (0, _orkestrel_contract.literalShape)(["move"], { description: "Rename or move a file (overwriting an occupied target)." }),
-	from: (0, _orkestrel_contract.stringShape)({ description: "The current path of the file." }),
-	to: (0, _orkestrel_contract.stringShape)({ description: "The new path for the file." })
-}), (0, _orkestrel_contract.objectShape)({
-	operation: (0, _orkestrel_contract.literalShape)(["remove"], { description: "Delete a file from the workspace." }),
-	path: (0, _orkestrel_contract.stringShape)({ description: "The path of the file to remove." })
-}), (0, _orkestrel_contract.objectShape)({ operation: (0, _orkestrel_contract.literalShape)(["workspaces"], { description: "List the workspaces you can move between (each id, file count, and whether it is active), so you can pick an id to switch to." }) }), (0, _orkestrel_contract.objectShape)({
-	operation: (0, _orkestrel_contract.literalShape)(["switch"], { description: "Switch the active workspace to the one with this id (get ids from the \"workspaces\" operation). Edit and read operations then target it." }),
-	id: (0, _orkestrel_contract.stringShape)({ description: "The id of the workspace to make active (from the \"workspaces\" listing)." })
-}));
-//#endregion
 //#region src/core/conversations/Conversation.ts
 /**
 * A conversation grouping messages ABOVE a flat message store — a live uncompacted tail it
@@ -1372,10 +1227,10 @@ function spliceRange(text, range, replacement) {
 	return text.slice(0, start) + replacement + text.slice(end);
 }
 /**
-* 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
@@ -1604,7 +1459,9 @@ var InstructionManager = class {
 *   (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 →
@@ -1685,7 +1542,8 @@ var ToolManager = class {
 	}
 	#definition(tool) {
 		const definition = { name: tool.name };
-		if (tool.description !== void 0) definition.description = tool.description;
+		const description = tool.summary ?? tool.description;
+		if (description !== void 0) definition.description = description;
 		if (tool.parameters !== void 0) definition.parameters = tool.parameters;
 		return definition;
 	}
@@ -2709,11 +2567,13 @@ var AgentRegistry = class {
 	#tools;
 	#authorities;
 	#schedulers;
+	#store;
 	constructor(options) {
 		this.#providers = new Map(Object.entries(options.providers));
 		this.#tools = new Map(Object.entries(options.tools ?? {}));
 		this.#authorities = new Map(Object.entries(options.authorities ?? {}));
 		this.#schedulers = new Map(Object.entries(options.schedulers ?? {}));
+		this.#store = options.store;
 	}
 	provider(name) {
 		return this.#resolve(this.#providers, "provider", name);
@@ -2741,6 +2601,7 @@ var AgentRegistry = class {
 			budget: this.#budget(input.budget),
 			authority: input.authority === void 0 ? void 0 : this.authority(input.authority),
 			scheduler: input.scheduler === void 0 ? void 0 : this.scheduler(input.scheduler),
+			conversations: this.#store === void 0 ? void 0 : new ConversationManager({ store: this.#store }),
 			signal
 		};
 	}
@@ -3225,11 +3086,13 @@ var ThinkSplitter = class {
 var Tool = class {
 	name;
 	description;
+	summary;
 	parameters;
 	#execute;
 	constructor(options) {
 		this.name = options.name;
 		this.description = options.description;
+		this.summary = options.summary;
 		this.parameters = options.parameters;
 		this.#execute = options.execute;
 	}
@@ -4150,165 +4013,6 @@ function createDatabaseWorkspaceStore(driver = (0, _orkestrel_database.createMem
 function createWorkspaceManager(options) {
 	return new WorkspaceManager(options);
 }
-/**
-* 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
-* exactly like the analogous `createWorkflowTool` in `@orkestrel/workflow` (NOT a class). 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`
-* ```
-*/
-function createWorkspaceTool(manager, options) {
-	const contract = (0, _orkestrel_contract.createContract)(workspaceToolShape);
-	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
-	return createTool({
-		name: options?.name ?? "workspace",
-		description: options?.description ?? WORKSPACE_TOOL_DESCRIPTION,
-		parameters,
-		execute: (args) => {
-			const op = contract.parse(args);
-			if (op === void 0) throw new WorkspaceError("TOOL", `unknown or malformed operation`, { args });
-			if (op.operation === "workspaces") {
-				const activeId = manager.active?.id;
-				return manager.workspaces().map((workspace) => ({
-					id: workspace.id,
-					files: workspace.count,
-					active: workspace.id === activeId
-				}));
-			}
-			if (op.operation === "switch") {
-				const switched = manager.switch(op.id);
-				return switched === void 0 ? {
-					id: op.id,
-					switched: false
-				} : {
-					id: switched.id,
-					switched: true,
-					files: switched.count
-				};
-			}
-			const active = manager.active;
-			switch (op.operation) {
-				case "read": return active?.read(op.path);
-				case "list": return (active?.files() ?? []).map((file) => ({
-					path: file.path,
-					state: file.state,
-					size: file.size,
-					lines: file.lines,
-					kind: isText(file.content) ? "text" : "binary"
-				}));
-				case "has": return active?.has(op.path) ?? false;
-				case "search": return active?.search(op.query, {
-					regex: op.regex,
-					exact: op.exact,
-					limit: op.limit
-				}) ?? [];
-				case "replace": return (active ?? manager.add()).replace(op.query, op.replacement, {
-					regex: op.regex,
-					exact: op.exact,
-					limit: op.limit
-				});
-				case "write": {
-					const workspace = active ?? manager.add();
-					workspace.write(op.path, op.content);
-					return {
-						path: op.path,
-						state: workspace.file(op.path)?.state
-					};
-				}
-				case "splice": {
-					const workspace = active ?? manager.add();
-					workspace.write(op.path, op.content, rangeOf(op.fromLine, op.fromColumn, op.toLine, op.toColumn));
-					return {
-						path: op.path,
-						state: workspace.file(op.path)?.state
-					};
-				}
-				case "prepend": {
-					const workspace = active ?? manager.add();
-					workspace.prepend(op.path, op.content);
-					return {
-						path: op.path,
-						state: workspace.file(op.path)?.state
-					};
-				}
-				case "append": {
-					const workspace = active ?? manager.add();
-					workspace.append(op.path, op.content);
-					return {
-						path: op.path,
-						state: workspace.file(op.path)?.state
-					};
-				}
-				case "move": {
-					const workspace = active ?? manager.add();
-					return {
-						from: op.from,
-						to: op.to,
-						moved: workspace.move(op.from, op.to)
-					};
-				}
-				case "remove": {
-					const workspace = active ?? manager.add();
-					return {
-						path: op.path,
-						removed: workspace.remove(op.path)
-					};
-				}
-			}
-		}
-	});
-}
 //#endregion
 exports.Agent = Agent;
 exports.AgentContext = AgentContext;
@@ -4339,9 +4043,6 @@ exports.ThinkSplitter = ThinkSplitter;
 exports.Tool = Tool;
 exports.ToolManager = ToolManager;
 exports.WORKSPACE_SECTION_HEADER = WORKSPACE_SECTION_HEADER;
-exports.WORKSPACE_TOOL_DESCRIPTION = WORKSPACE_TOOL_DESCRIPTION;
-exports.WORKSPACE_TOOL_EXAMPLE = WORKSPACE_TOOL_EXAMPLE;
-exports.WORKSPACE_TOOL_NAME = WORKSPACE_TOOL_NAME;
 exports.Workspace = Workspace;
 exports.WorkspaceError = WorkspaceError;
 exports.WorkspaceManager = WorkspaceManager;
@@ -4374,7 +4075,6 @@ exports.createTool = createTool;
 exports.createToolManager = createToolManager;
 exports.createWorkspace = createWorkspace;
 exports.createWorkspaceManager = createWorkspaceManager;
-exports.createWorkspaceTool = createWorkspaceTool;
 exports.decodedSize = decodedSize;
 exports.escapeRegExp = escapeRegExp;
 exports.estimateMessages = estimateMessages;
@@ -4401,6 +4101,5 @@ exports.rangeOf = rangeOf;
 exports.settleAgentJob = settleAgentJob;
 exports.sliceRange = sliceRange;
 exports.spliceRange = spliceRange;
-exports.workspaceToolShape = workspaceToolShape;
 
 //# sourceMappingURL=index.cjs.map