@contractspec/lib.ai-agent 5.0.4 → 6.0.0

package/dist/node/tools/operation-tool-handler.js

@@ -0,0 +1,35 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/tools/operation-tool-handler.ts
+function toolCtxToHandlerCtx(ctx) {
+  return {
+    traceId: ctx.metadata?.traceId,
+    organizationId: ctx.tenantId ?? null,
+    userId: ctx.actorId ?? null,
+    actor: ctx.actorId ? "user" : "anonymous",
+    channel: "agent",
+    roles: []
+  };
+}
+function createOperationToolHandler(registry, operationRef) {
+  return async (input, context) => {
+    const handlerCtx = toolCtxToHandlerCtx(context);
+    const result = await registry.execute(operationRef.key, operationRef.version, input ?? {}, handlerCtx);
+    return result;
+  };
+}
+export {
+  createOperationToolHandler
+};

package/dist/node/tools/subagent-tool.js

@@ -0,0 +1,95 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/tools/subagent-tool.ts
+import { readUIMessageStream, tool } from "ai";
+import { z } from "zod";
+function toReadableStream(iterable) {
+  if (iterable instanceof ReadableStream) {
+    return iterable;
+  }
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const chunk of iterable) {
+          controller.enqueue(chunk);
+        }
+      } finally {
+        controller.close();
+      }
+    }
+  });
+}
+function createSubagentTool(options) {
+  const {
+    subagent,
+    description = "Research a topic or question in depth.",
+    taskParam = "task",
+    toModelSummary = true,
+    passConversationHistory = false
+  } = options;
+  const inputSchema = z.object({
+    [taskParam]: z.string().describe("The research task to complete")
+  });
+  const execute = async function* (input, options2) {
+    const task = String(input[taskParam] ?? input.task ?? "");
+    const { abortSignal, messages } = options2 ?? {};
+    if (passConversationHistory && messages && messages.length > 0 && typeof subagent.generate === "function") {
+      const result2 = await subagent.generate({
+        messages: [...messages, { role: "user", content: task }],
+        abortSignal
+      });
+      yield { parts: [{ type: "text", text: result2.text }] };
+      return;
+    }
+    const result = await subagent.stream({
+      prompt: task,
+      abortSignal
+    });
+    const uiStream = result.toUIMessageStream();
+    const stream = toReadableStream(uiStream);
+    for await (const message of readUIMessageStream({
+      stream
+    })) {
+      yield message;
+    }
+  };
+  const toolOptions = {
+    description,
+    inputSchema,
+    execute,
+    ...toModelSummary && {
+      toModelOutput: ({
+        output
+      }) => {
+        const parts = output?.parts;
+        if (!Array.isArray(parts)) {
+          return { type: "text", value: "Task completed." };
+        }
+        const lastTextPart = [...parts].reverse().find((p) => p?.type === "text");
+        return {
+          type: "text",
+          value: lastTextPart?.text ?? "Task completed."
+        };
+      }
+    }
+  };
+  return tool(toolOptions);
+}
+var init_subagent_tool = () => {};
+init_subagent_tool();
+
+export {
+  createSubagentTool
+};

package/dist/node/tools/tool-adapter.js

@@ -2260,15 +2260,124 @@ function jsonSchemaToZodSafe(schema) {
 }
 var init_json_schema_to_zod = () => {};
 
+// src/tools/operation-tool-handler.ts
+function toolCtxToHandlerCtx(ctx) {
+  return {
+    traceId: ctx.metadata?.traceId,
+    organizationId: ctx.tenantId ?? null,
+    userId: ctx.actorId ?? null,
+    actor: ctx.actorId ? "user" : "anonymous",
+    channel: "agent",
+    roles: []
+  };
+}
+function createOperationToolHandler(registry, operationRef) {
+  return async (input, context) => {
+    const handlerCtx = toolCtxToHandlerCtx(context);
+    const result = await registry.execute(operationRef.key, operationRef.version, input ?? {}, handlerCtx);
+    return result;
+  };
+}
+
+// src/tools/subagent-tool.ts
+import { readUIMessageStream, tool } from "ai";
+import { z as z2 } from "zod";
+function toReadableStream(iterable) {
+  if (iterable instanceof ReadableStream) {
+    return iterable;
+  }
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const chunk of iterable) {
+          controller.enqueue(chunk);
+        }
+      } finally {
+        controller.close();
+      }
+    }
+  });
+}
+function createSubagentTool(options) {
+  const {
+    subagent,
+    description = "Research a topic or question in depth.",
+    taskParam = "task",
+    toModelSummary = true,
+    passConversationHistory = false
+  } = options;
+  const inputSchema = z2.object({
+    [taskParam]: z2.string().describe("The research task to complete")
+  });
+  const execute = async function* (input, options2) {
+    const task = String(input[taskParam] ?? input.task ?? "");
+    const { abortSignal, messages } = options2 ?? {};
+    if (passConversationHistory && messages && messages.length > 0 && typeof subagent.generate === "function") {
+      const result2 = await subagent.generate({
+        messages: [...messages, { role: "user", content: task }],
+        abortSignal
+      });
+      yield { parts: [{ type: "text", text: result2.text }] };
+      return;
+    }
+    const result = await subagent.stream({
+      prompt: task,
+      abortSignal
+    });
+    const uiStream = result.toUIMessageStream();
+    const stream = toReadableStream(uiStream);
+    for await (const message of readUIMessageStream({
+      stream
+    })) {
+      yield message;
+    }
+  };
+  const toolOptions = {
+    description,
+    inputSchema,
+    execute,
+    ...toModelSummary && {
+      toModelOutput: ({
+        output
+      }) => {
+        const parts = output?.parts;
+        if (!Array.isArray(parts)) {
+          return { type: "text", value: "Task completed." };
+        }
+        const lastTextPart = [...parts].reverse().find((p) => p?.type === "text");
+        return {
+          type: "text",
+          value: lastTextPart?.text ?? "Task completed."
+        };
+      }
+    }
+  };
+  return tool(toolOptions);
+}
+var init_subagent_tool = () => {};
+
 // src/tools/tool-adapter.ts
-import { tool } from "ai";
-function specToolToAISDKTool(specTool, handler, context = {}) {
+import { tool as tool2 } from "ai";
+function isAsyncGenerator(value) {
+  return typeof value === "object" && value !== null && typeof value.next === "function" && typeof value[Symbol.asyncIterator] === "function";
+}
+function specToolToAISDKTool(specTool, handler, context = {}, effectiveInputSchema, operationSpec) {
   let lastInvocationAt;
-  return tool({
+  const inputSchema = effectiveInputSchema ?? jsonSchemaToZodSafe(specTool.schema);
+  const buildContext = (signal) => ({
+    agentId: context.agentId ?? "unknown",
+    sessionId: context.sessionId ?? "unknown",
+    tenantId: context.tenantId,
+    actorId: context.actorId,
+    locale: context.locale,
+    metadata: context.metadata,
+    signal
+  });
+  return tool2({
     description: specTool.description ?? specTool.name,
-    inputSchema: jsonSchemaToZodSafe(specTool.schema),
+    inputSchema,
     needsApproval: specTool.requiresApproval ?? !specTool.automationSafe,
-    execute: async (input) => {
+    execute: async function* (input, options) {
       const now = Date.now();
       const cooldownMs = normalizeDuration(specTool.cooldownMs);
       if (cooldownMs && lastInvocationAt !== undefined) {
@@ -2279,19 +2388,20 @@ function specToolToAISDKTool(specTool, handler, context = {}) {
         }
       }
       const timeoutMs = normalizeDuration(specTool.timeoutMs);
-      const { signal, dispose } = createTimeoutSignal(context.signal, timeoutMs);
+      const signal = options?.abortSignal ?? context.signal;
+      const { signal: timeoutSignal, dispose } = createTimeoutSignal(signal, timeoutMs);
       try {
-        const execution = handler(input, {
-          agentId: context.agentId ?? "unknown",
-          sessionId: context.sessionId ?? "unknown",
-          tenantId: context.tenantId,
-          actorId: context.actorId,
-          locale: context.locale,
-          metadata: context.metadata,
-          signal
-        });
-        const result = timeoutMs ? await withTimeout(execution, timeoutMs, specTool.name) : await execution;
-        return typeof result === "string" ? result : JSON.stringify(result);
+        const execution = handler(input, buildContext(timeoutSignal));
+        if (isAsyncGenerator(execution)) {
+          for await (const raw of execution) {
+            const wrapped = wrapToolOutputForRendering(specTool, raw, operationSpec);
+            yield typeof wrapped === "string" ? wrapped : wrapped;
+          }
+        } else {
+          const raw = timeoutMs ? await withTimeout(Promise.resolve(execution), timeoutMs, specTool.name) : await Promise.resolve(execution);
+          const wrapped = wrapToolOutputForRendering(specTool, raw, operationSpec);
+          yield typeof wrapped === "string" ? wrapped : wrapped;
+        }
       } finally {
         dispose();
         lastInvocationAt = Date.now();
@@ -2299,27 +2409,83 @@ function specToolToAISDKTool(specTool, handler, context = {}) {
     }
   });
 }
-function specToolsToAISDKTools(specTools, handlers, context = {}) {
+function specToolsToAISDKTools(specTools, handlers, context = {}, options) {
   const tools = {};
   for (const specTool of specTools) {
-    const handler = handlers.get(specTool.name);
-    if (!handler) {
-      throw new Error(createAgentI18n(context.locale).t("error.missingToolHandler", {
-        name: specTool.name
-      }));
+    if (specTool.subagentRef && options?.subagentRegistry) {
+      const subagent = options.subagentRegistry.get(specTool.subagentRef.agentId);
+      if (!subagent) {
+        throw new Error(`Subagent not found: ${specTool.subagentRef.agentId}. Register it in subagentRegistry.`);
+      }
+      if (specTool.requiresApproval === true || specTool.automationSafe === false) {
+        console.warn(`[ContractSpec] Subagent tool "${specTool.name}" cannot use needsApproval. ` + `requiresApproval and automationSafe are ignored for subagent tools (AI SDK limitation). ` + `See https://ai-sdk.dev/docs/agents/subagents#no-tool-approvals-in-subagents`);
+      }
+      tools[specTool.name] = createSubagentTool({
+        subagent,
+        description: specTool.description ?? specTool.name,
+        toModelSummary: specTool.subagentRef.toModelSummary ?? true,
+        passConversationHistory: specTool.subagentRef.passConversationHistory
+      });
+      continue;
     }
-    tools[specTool.name] = specToolToAISDKTool(specTool, handler, context);
+    let handler;
+    let effectiveInputSchema;
+    let op;
+    if (specTool.operationRef && options?.operationRegistry) {
+      op = options.operationRegistry.get(specTool.operationRef.key, specTool.operationRef.version);
+      if (!op) {
+        throw new Error(`Operation not found: ${specTool.operationRef.key}${specTool.operationRef.version ? `.v${specTool.operationRef.version}` : ""}`);
+      }
+      handler = createOperationToolHandler(options.operationRegistry, specTool.operationRef);
+      effectiveInputSchema = op.io.input?.getZod?.();
+    } else {
+      const manualHandler = handlers.get(specTool.name);
+      if (!manualHandler) {
+        if (specTool.subagentRef) {
+          throw new Error(`Subagent tool "${specTool.name}" requires subagentRegistry. Pass subagentRegistry in ContractSpecAgentConfig.`);
+        }
+        throw new Error(createAgentI18n(context.locale).t("error.missingToolHandler", {
+          name: specTool.name
+        }));
+      }
+      handler = manualHandler;
+    }
+    tools[specTool.name] = specToolToAISDKTool(specTool, handler, context, effectiveInputSchema, op);
   }
   return tools;
 }
 function createToolHandler(handler) {
-  return async (input, context) => {
+  return (input, context) => {
     return handler(input, context);
   };
 }
 function buildToolHandlers(handlersObj) {
   return new Map(Object.entries(handlersObj));
 }
+function wrapToolOutputForRendering(specTool, result, operationSpec) {
+  const presentation = specTool.outputPresentation ?? operationSpec?.outputPresentation;
+  const form = specTool.outputForm ?? operationSpec?.outputForm;
+  const dataView = specTool.outputDataView ?? operationSpec?.outputDataView;
+  if (presentation) {
+    return {
+      presentationKey: presentation.key,
+      data: result
+    };
+  }
+  if (form) {
+    return {
+      formKey: form.key,
+      defaultValues: typeof result === "object" && result !== null ? result : {}
+    };
+  }
+  if (dataView) {
+    return {
+      dataViewKey: dataView.key,
+      items: Array.isArray(result) ? result : result != null ? [result] : []
+    };
+  }
+  return result;
+}
 function normalizeDuration(value) {
   if (value === undefined) {
     return;
@@ -2381,6 +2547,7 @@ function createToolExecutionError(message, code, retryAfterMs) {
 var init_tool_adapter = __esm(() => {
   init_json_schema_to_zod();
   init_i18n();
+  init_subagent_tool();
 });
 init_tool_adapter();
 

package/dist/providers/claude-agent-sdk/adapter.js

@@ -2156,6 +2156,17 @@ function defineAgent(spec) {
       }));
     }
     toolNames.add(tool.name);
+    if (tool.subagentRef && tool.operationRef) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" cannot have both subagentRef and operationRef. Use one.`);
+    }
+    const outputRefCount = [
+      tool.outputPresentation,
+      tool.outputForm,
+      tool.outputDataView
+    ].filter(Boolean).length;
+    if (outputRefCount > 1) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" has multiple output refs (outputPresentation, outputForm, outputDataView). Use at most one.`);
+    }
   }
   return Object.freeze(spec);
 }

package/dist/providers/claude-agent-sdk/index.js

@@ -2156,6 +2156,17 @@ function defineAgent(spec) {
       }));
     }
     toolNames.add(tool.name);
+    if (tool.subagentRef && tool.operationRef) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" cannot have both subagentRef and operationRef. Use one.`);
+    }
+    const outputRefCount = [
+      tool.outputPresentation,
+      tool.outputForm,
+      tool.outputDataView
+    ].filter(Boolean).length;
+    if (outputRefCount > 1) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" has multiple output refs (outputPresentation, outputForm, outputDataView). Use at most one.`);
+    }
   }
   return Object.freeze(spec);
 }

package/dist/providers/index.js

@@ -2156,6 +2156,17 @@ function defineAgent(spec) {
       }));
     }
     toolNames.add(tool.name);
+    if (tool.subagentRef && tool.operationRef) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" cannot have both subagentRef and operationRef. Use one.`);
+    }
+    const outputRefCount = [
+      tool.outputPresentation,
+      tool.outputForm,
+      tool.outputDataView
+    ].filter(Boolean).length;
+    if (outputRefCount > 1) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" has multiple output refs (outputPresentation, outputForm, outputDataView). Use at most one.`);
+    }
   }
   return Object.freeze(spec);
 }

package/dist/providers/opencode-sdk/adapter.js

@@ -2156,6 +2156,17 @@ function defineAgent(spec) {
       }));
     }
     toolNames.add(tool.name);
+    if (tool.subagentRef && tool.operationRef) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" cannot have both subagentRef and operationRef. Use one.`);
+    }
+    const outputRefCount = [
+      tool.outputPresentation,
+      tool.outputForm,
+      tool.outputDataView
+    ].filter(Boolean).length;
+    if (outputRefCount > 1) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" has multiple output refs (outputPresentation, outputForm, outputDataView). Use at most one.`);
+    }
   }
   return Object.freeze(spec);
 }

package/dist/providers/opencode-sdk/index.js

@@ -2156,6 +2156,17 @@ function defineAgent(spec) {
       }));
     }
     toolNames.add(tool.name);
+    if (tool.subagentRef && tool.operationRef) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" cannot have both subagentRef and operationRef. Use one.`);
+    }
+    const outputRefCount = [
+      tool.outputPresentation,
+      tool.outputForm,
+      tool.outputDataView
+    ].filter(Boolean).length;
+    if (outputRefCount > 1) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" has multiple output refs (outputPresentation, outputForm, outputDataView). Use at most one.`);
+    }
   }
   return Object.freeze(spec);
 }

package/dist/spec/index.js

@@ -2156,6 +2156,17 @@ function defineAgent(spec) {
       }));
     }
     toolNames.add(tool.name);
+    if (tool.subagentRef && tool.operationRef) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" cannot have both subagentRef and operationRef. Use one.`);
+    }
+    const outputRefCount = [
+      tool.outputPresentation,
+      tool.outputForm,
+      tool.outputDataView
+    ].filter(Boolean).length;
+    if (outputRefCount > 1) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" has multiple output refs (outputPresentation, outputForm, outputDataView). Use at most one.`);
+    }
   }
   return Object.freeze(spec);
 }

package/dist/spec/spec.d.ts

@@ -1,4 +1,5 @@
 import type { OwnerShipMeta } from '@contractspec/lib.contracts-spec/ownership';
+import type { DataViewRef, FormRef, PresentationRef } from '@contractspec/lib.contracts-spec/features';
 import type { KnowledgeCategory } from '@contractspec/lib.contracts-spec/knowledge/spec';
 import type { PolicyRef } from '@contractspec/lib.contracts-spec/policy/spec';
 /**
@@ -30,15 +31,51 @@ export interface AgentRuntimeConfig {
     capabilities?: AgentRuntimeCapabilities;
     ports?: AgentRuntimePorts;
 }
+/**
+ * Reference to a ContractSpec operation that backs an agent tool.
+ * When set, the tool is a projection of the operation (one contract → REST, GraphQL, MCP, agent).
+ */
+export interface OperationRef {
+    /** Operation key (e.g., "knowledge.search") */
+    key: string;
+    /** Optional specific version; defaults to latest when omitted */
+    version?: string;
+}
+/**
+ * Reference to a subagent that backs an agent tool.
+ * When set, the tool delegates to the subagent; mutually exclusive with operationRef and manual handler.
+ */
+export interface SubagentRef {
+    /** Subagent identifier (resolved from subagent registry) */
+    agentId: string;
+    /** Whether to extract summary for toModelOutput (default: true) */
+    toModelSummary?: boolean;
+    /**
+     * Pass full conversation history to subagent (opt-in).
+     * Defeats context isolation; use sparingly. Requires subagent to support generate({ messages }).
+     * Streaming is disabled when history is passed.
+     */
+    passConversationHistory?: boolean;
+}
 /**
  * Configuration for a tool that an agent can use.
  */
 export interface AgentToolConfig {
     /** Tool name (unique within the agent) */
     name: string;
+    /**
+     * Reference to a ContractSpec operation. When set, the tool is backed by the operation:
+     * schema and handler are derived from the operation; no manual handler needed.
+     */
+    operationRef?: OperationRef;
+    /**
+     * Reference to a subagent. When set, the tool delegates to the subagent.
+     * Mutually exclusive with operationRef; requires subagentRegistry in agent config.
+     */
+    subagentRef?: SubagentRef;
     /** Human-readable description for the LLM */
     description?: string;
-    /** JSON Schema fragment for tool parameters */
+    /** JSON Schema fragment for tool parameters (fallback when no operationRef) */
     schema?: Record<string, unknown>;
     /** Optional cooldown in milliseconds between invocations */
     cooldownMs?: number;
@@ -50,6 +87,21 @@ export interface AgentToolConfig {
     requiresApproval?: boolean;
     /** Optional policy guard that must evaluate to allow the tool call */
     policy?: PolicyRef;
+    /**
+     * When set, wrap raw output as { presentationKey, data } for ToolResultRenderer.
+     * At most one of outputPresentation, outputForm, outputDataView per tool.
+     */
+    outputPresentation?: PresentationRef;
+    /**
+     * When set, wrap raw output as { formKey, defaultValues } for ToolResultRenderer.
+     * At most one of outputPresentation, outputForm, outputDataView per tool.
+     */
+    outputForm?: FormRef;
+    /**
+     * When set, wrap raw output as { dataViewKey, items } for ToolResultRenderer.
+     * At most one of outputPresentation, outputForm, outputDataView per tool.
+     */
+    outputDataView?: DataViewRef;
 }
 /**
  * Reference to a knowledge space that the agent can access.
@@ -79,6 +131,20 @@ export interface AgentMemoryConfig {
     /** Whether to persist to long-term storage */
     persistLongTerm?: boolean;
 }
+/**
+ * Memory tools config — model-accessible CRUD (Anthropic memory, custom).
+ * Distinct from AgentMemoryConfig (session summarization).
+ *
+ * @see https://ai-sdk.dev/docs/agents/memory
+ */
+export interface AgentMemoryToolsConfig {
+    /** Provider: anthropic uses memory_20250818; custom uses operationRef. */
+    provider: 'anthropic' | 'custom';
+    /** Storage adapter key when using knowledge-backed storage (e.g. ephemeral space) */
+    storageAdapter?: string;
+    /** Ephemeral KnowledgeSpaceSpec key when using knowledge-backed storage */
+    spaceKey?: string;
+}
 /**
  * Confidence policy for agent responses.
  */
@@ -127,6 +193,8 @@ export interface AgentSpec {
     tools: AgentToolConfig[];
     /** Memory/session configuration */
     memory?: AgentMemoryConfig;
+    /** Memory tools (model-accessible CRUD) — Anthropic or custom operation-backed */
+    memoryTools?: AgentMemoryToolsConfig;
     /** Knowledge spaces the agent can access */
     knowledge?: AgentKnowledgeRef[];
     /** Policy configuration */

package/dist/spec/spec.js

@@ -2156,6 +2156,17 @@ function defineAgent(spec) {
       }));
     }
     toolNames.add(tool.name);
+    if (tool.subagentRef && tool.operationRef) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" cannot have both subagentRef and operationRef. Use one.`);
+    }
+    const outputRefCount = [
+      tool.outputPresentation,
+      tool.outputForm,
+      tool.outputDataView
+    ].filter(Boolean).length;
+    if (outputRefCount > 1) {
+      throw new Error(`Agent ${spec.meta.key} tool "${tool.name}" has multiple output refs (outputPresentation, outputForm, outputDataView). Use at most one.`);
+    }
   }
   return Object.freeze(spec);
 }

package/dist/tools/agent-memory-store.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Storage interface for agent memory tools (model-accessible CRUD).
+ *
+ * Used by Anthropic memory tool and custom memory tools. Distinct from
+ * AgentMemoryManager (session summarization). Storage backend can be
+ * in-memory, filesystem, or ephemeral knowledge space.
+ *
+ * @see https://ai-sdk.dev/docs/agents/memory
+ * @see https://console.anthropic.com/docs/en/agents-and-tools/tool-use/memory-tool
+ */
+export interface AgentMemoryStore {
+    /** View directory contents or file contents. Path must be under /memories. */
+    view(path: string, viewRange?: [number, number]): Promise<string>;
+    /** Create a new file. Path must be under /memories. */
+    create(path: string, fileText: string): Promise<string>;
+    /** Replace old_str with new_str in file. */
+    strReplace(path: string, oldStr: string, newStr: string): Promise<string>;
+    /** Insert text at line. insertLine is 0-indexed (0 = before first line). */
+    insert(path: string, insertLine: number, insertText: string): Promise<string>;
+    /** Delete file or directory recursively. */
+    delete(path: string): Promise<string>;
+    /** Rename/move file or directory. */
+    rename(oldPath: string, newPath: string): Promise<string>;
+}
+/** Validates path is under /memories and prevents traversal. */
+export declare function validateMemoryPath(path: string): void;