@aigne/afs-agent 1.11.0-beta.13

package/dist/index.d.mts

@@ -0,0 +1,754 @@
+import { AFSAccessMode, AFSExecResult, AFSListResult, AFSModuleLoadParams, AFSRoot, AFSStatResult, ProviderManifest, SpaceResolver } from "@aigne/afs";
+import { ToolEntry } from "@aigne/afs-ash";
+import { AFSBaseProvider, RouteContext } from "@aigne/afs/provider";
+
+//#region src/observability.d.ts
+interface BaseEvent {
+  seq: number;
+  ts: number;
+}
+interface RunStartEvent extends BaseEvent {
+  type: "run.start";
+  runId: string;
+  blockletId: string | null;
+  userDid: string | null;
+  sessionId: string | null;
+  input: {
+    task: string;
+    model: string;
+    tools: Array<{
+      path: string;
+      ops: string[];
+    }>;
+    budget: Record<string, unknown>;
+    systemPrompt?: string;
+  };
+  /** Ownership routing telemetry (Phase 3c). Records the derived persistence
+   *  class + resolved sink so observe-only migration can spot misrouted or
+   *  dropped runs. Absent on legacy runtimes that don't inject the capability. */
+  ownership?: {
+    persistenceClass: "user" | "instance" | "ephemeral";
+    agentRunOrigin: "interactive" | "system";
+    ownershipRoutingMode: "observe-only" | "strict-user" | "strict-all";
+    instanceDid: string | null;
+    sinkKind: "afs" | "legacy-current-afs" | "none";
+    /** Why this sink was chosen — e.g. `user-direct-write`, or
+     *  `user-missing:instanceDid …` when observe-only fell through to legacy
+     *  probing. Lets migration spot misrouted runs without a drop (Phase 3e). */
+    sinkReason: string;
+  };
+}
+interface MessageEvent extends BaseEvent {
+  type: "message";
+  role: string;
+  content: unknown;
+  toolCalls?: unknown[];
+  callId?: string;
+  thoughts?: string;
+}
+interface TurnEvent extends BaseEvent {
+  type: "turn";
+  round: number;
+  model: string | null;
+  hub: string | null;
+  tokensIn: number;
+  tokensOut: number;
+  /** Prompt tokens served from the provider's cache for this round
+   *  (Anthropic `cache_read_input_tokens`). 0 when caching wasn't hit
+   *  or wasn't reported by the provider. */
+  tokensCached: number;
+  cost: number;
+  durationMs: number;
+  status: "ok" | "error";
+  errorMessage: string | null;
+}
+interface ToolEvent extends BaseEvent {
+  type: "tool";
+  round: number;
+  callId: string;
+  name: string;
+  path: string;
+  op: string;
+  args: unknown;
+  result: unknown;
+  status: "ok" | "error";
+  errorMessage: string | null;
+  durationMs: number;
+}
+interface CompressEvent extends BaseEvent {
+  type: "compress";
+  round: number;
+  compressed_messages: Array<Record<string, unknown>>;
+  archived_count: number;
+  before_tokens: number;
+  after_tokens: number;
+}
+interface RunEndEvent extends BaseEvent {
+  type: "run.end";
+  runId: string;
+  durationMs: number;
+  status: "ok" | "budget_exhausted" | "error";
+  result: {
+    data: unknown;
+    errorMessage: string | null;
+  };
+  totals: {
+    rounds: number;
+    totalTokensIn: number;
+    totalTokensOut: number;
+    totalCost: number;
+    modelsUsed: string[];
+    hubsUsed: string[];
+    toolsUsed: string[];
+  };
+}
+type LogEvent = RunStartEvent | MessageEvent | TurnEvent | ToolEvent | CompressEvent | RunEndEvent;
+//#endregion
+//#region src/agent-run.d.ts
+interface AgentRunParams {
+  task: string;
+  model: string;
+  tools: ToolEntry[];
+  budget?: {
+    max_rounds?: number;
+    actions_per_round?: number;
+    total_tokens?: number; /** Model context window size (tokens). Used for compression threshold. */
+    context_window?: number; /** Max LLM call retry attempts on transient failures (default 3). */
+    max_retries?: number;
+  };
+  system?: string;
+  session?: string;
+  /** Skill directories to scan for SKILL.md files (e.g. ["/program/skills", "/data/skills"]) */
+  skillPaths?: string[];
+  /** Constrain LLM tool selection. "auto" (default) | "none" | "required" | <tool-name>.
+   *  Mirrors aigne-framework's Router pattern; passed verbatim to the LLM. */
+  toolChoice?: string;
+  /** Extra args forwarded verbatim to every `callLLM` invocation. Used to pass
+   *  AI Device routing hints (policy, requirements, exclusions, session, etc.)
+   *  through to `/dev/ai/.actions/chat` without baking that vocabulary into
+   *  agent-run itself. Keys collide-last with ash's own llmArgs (messages,
+   *  tools, toolChoice, responseFormat, _onChunk) — those can't be overridden. */
+  modelArgs?: Record<string, unknown>;
+  /** AFS exec path (or { path, ...extraArgs }) for sending intermediate progress messages. */
+  onProgress?: string | {
+    path: string;
+    [key: string]: unknown;
+  };
+  /** In-process callback fired after each tool call with structured progress data. */
+  onToolProgress?: (event: ToolProgressEvent) => void;
+  /** AFS path to a JSON Schema file. When set, a `respond` tool is injected and the LLM's
+   *  structured call to it becomes the result (as an object instead of a string). */
+  responseSchema?: string;
+  /** Shared execution context automatically merged into nested `args` of every exec tool call.
+   *  Provides defaults for downstream actions (e.g. scheduler dispatch) without requiring
+   *  the LLM to copy caller context manually. LLM-provided values always take priority. */
+  execContext?: Record<string, unknown>;
+  /** Parent session ID — when set, this run is a child of the given session.
+   *  Used for session hierarchy derivation (S3). */
+  parentSession?: string;
+  /** Spawn chain — list of ancestor session IDs from root to current.
+   *  Used for depth enforcement (S3). */
+  chain?: string[];
+  /** Parent proc ID from the calling blocklet — registers this run as a child of that proc. */
+  parentProcId?: string;
+  /** Parent agent info for template `$parent` variable (S4). */
+  parentAgentInfo?: {
+    name: string;
+    type: string;
+    session: string;
+  };
+  /** Abort signal from parent budget tracker. Checked at the start of each round;
+   *  when aborted, the loop returns immediately preserving completed work. (S11) */
+  abortSignal?: AbortSignal;
+  /** When true, suppress the built-in AFS Discovery Protocol hint (which tells
+   *  the LLM to "Start with `read /.knowledge`"). Use this for narrow-scope
+   *  agents whose system prompt already specifies exact paths to read — the
+   *  generic /.knowledge advice wastes rounds exploring the framework instead
+   *  of following the agent's own instructions. */
+  skipAfsHint?: boolean;
+  /** Memory configuration. When set, recall is injected into the system message and
+   *  memory tools are exposed to the LLM for active memory operations. */
+  memory?: {
+    /** AFS exec path for recall (e.g. "/modules/memory/.actions/recall"). */recallPath: string; /** Max tokens for memory injection into system message. Default: 2000. */
+    maxTokens?: number; /** Domain filter passed to recall. */
+    domain?: string;
+    /** AFS path pattern for memory tools (e.g. "/modules/memory/.actions/*").
+     *  When set, memory actions (recall, remember, boost, feedback) are exposed as tools. */
+    toolsPath?: string;
+    /** AFS exec path for session archive (e.g. "/modules/memory/.actions/archive").
+     *  When set, the conversation is archived to memory on completion. */
+    archivePath?: string;
+  };
+  /** Index configuration. When `scope` is set, agent-run auto-grants
+   *  list+read on `/<mount-root>/domains/<scope>` so the agent can
+   *  observe what's indexed (parallel to the memory.domain auto-grant).
+   *  Mount root is derived from `queryPath` by stripping `/.actions/query`. */
+  index?: {
+    /** AFS exec path for query (e.g. "/modules/index/.actions/query"). */queryPath: string; /** Domain/scope for inspection grants. Without this, no auto-grant fires. */
+    scope?: string;
+  };
+}
+interface ToolProgressEvent {
+  type: "tool_start" | "tool_result" | "thinking" | "llm_start" | "llm_result" | "llm_delta" | "thinking_delta" | "summary" | "warning" | "compress_start" | "compress_result" | "subAgentMetadata";
+  round: number;
+  /** Nesting depth: 0 = root, 1 = child, 2 = grandchild, etc. (S9) */
+  depth: number;
+  /** Ancestor session chain from root to current run. (S9) */
+  chain: string[];
+  /** For tool_start/tool_result: array of tool calls in this batch. */
+  calls?: Array<{
+    id: string;
+    tool: string;
+    path: string;
+    status: "pending" | "ok" | "error";
+    error?: string;
+    args?: Record<string, unknown>;
+    result?: string;
+  }>;
+  /** For thinking: LLM's intermediate text. */
+  text?: string;
+  /** Resolved model name (llm_start, llm_result, summary). */
+  model?: string;
+  /** Retry attempt number, 1-based (llm_result on failure). */
+  attempt?: number;
+  /** Max retry attempts (llm_result). */
+  maxAttempts?: number;
+  /** Error message on LLM retry failure (llm_result). */
+  llmError?: string;
+  /** Delay before the next retry in milliseconds (llm_result on retryable failure). */
+  retryDelayMs?: number;
+  /** Accumulated token/cost totals (summary). */
+  tokens?: {
+    input: number;
+    output: number;
+    cached?: number;
+    cost?: number;
+  };
+  /** Context compression stats (compress_start, compress_result). */
+  compress?: {
+    phase: "triggered" | "summarizing" | "done" | "failed";
+    beforeTokens: number;
+    contextWindow: number;
+    compressedMessages: number;
+    keptMessages: number;
+    afterTokens?: number;
+    error?: string;
+  };
+  /** Sub-agent metadata extracted from child .actions/run result (subAgentMetadata). */
+  subAgentMeta?: Record<string, unknown>;
+}
+interface TraceEntry {
+  round: number;
+  tool_calls: Array<{
+    id: string;
+    name: string;
+    path: string;
+    status: "ok" | "error" | "circuit_breaker";
+    error?: string;
+  }>;
+  tokens: {
+    input: number;
+    output: number;
+  };
+}
+interface AgentRunResult {
+  status: "completed" | "budget_exhausted" | "error";
+  result?: string | Record<string, unknown>;
+  error?: string;
+  /** Detailed diagnostics when status is "error" (request summary + last response). */
+  detail?: {
+    request?: unknown;
+    lastResponse?: unknown;
+  };
+  rounds: number;
+  total_actions: number;
+  total_tokens: number;
+  /** B4 — count of successful nested .actions/run dispatches from this run. */
+  sub_runs: number;
+  trace: TraceEntry[];
+  /** Final accumulator snapshot (rounds, tokens, cost, models/hubs/tools used).
+   *  Used by orchestration.ts to populate run.end event totals. */
+  totals?: TotalsSnapshot;
+}
+interface TotalsSnapshot {
+  rounds: number;
+  totalTokensIn: number;
+  totalTokensOut: number;
+  /** Sum of `usage.cacheReadInputTokens` across all rounds. Reflects how
+   *  many prompt tokens were served from cache (Anthropic/etc. discount
+   *  these). Surfaced in run.end totals so observability can show "X cache
+   *  tokens reused" without re-walking turn events. */
+  totalCachedTokens: number;
+  totalCost: number;
+  modelsUsed: string[];
+  hubsUsed: string[];
+  toolsUsed: string[];
+}
+/** Message types for JSONL history (OpenAI canonical snake_case format) */
+interface HistoryToolCall {
+  id: string;
+  type: "function";
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+type HistoryMessage = {
+  role: "user";
+  content: string;
+  createdAt?: string;
+} | {
+  role: "assistant";
+  content: string;
+  tool_calls?: HistoryToolCall[];
+  createdAt?: string;
+  durationMs?: number;
+} | {
+  role: "tool";
+  tool_call_id: string;
+  content: string | unknown[];
+  createdAt?: string;
+  durationMs?: number;
+};
+interface AgentRunDeps {
+  callLLM: (args: Record<string, unknown>) => Promise<AFSExecResult>;
+  runAsh: (source: string, args: Record<string, unknown>) => Promise<AFSExecResult>;
+  callAFS: (op: string, path: string, args?: Record<string, unknown>) => Promise<AFSExecResult>;
+  /** Test seam for retry backoff; production uses abort-aware setTimeout. */
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+  loadHistory?: (sessionPath: string) => Promise<HistoryMessage[]>;
+  /** Append new messages to working history (history.jsonl). */
+  appendHistory?: (sessionPath: string, messages: HistoryMessage[]) => Promise<void>;
+  /** Rewrite working history with compressed messages (called only on compression). */
+  rewriteHistory?: (sessionPath: string, messages: HistoryMessage[]) => Promise<void>;
+  /** Archive compressed messages to a timestamped file (called only on compression). */
+  archiveHistory?: (sessionPath: string, messages: HistoryMessage[]) => Promise<void>;
+  /** Observability: emit a single jsonl event to the run's log file.
+   *  Provided by orchestration.ts; absent when no log destination is wired up
+   *  (e.g. CLI direct call without `_scope_afs`). */
+  emit?: (event: LogEvent) => Promise<void>;
+  /** Observability: per-run monotonic seq counter. Owned by orchestration.ts. */
+  nextSeq?: () => number;
+}
+declare function computeLLMRetryDelayMs(error: string, failedAttempt: number): number;
+declare function runAgentLoop(params: AgentRunParams, deps: AgentRunDeps): Promise<AgentRunResult>;
+//#endregion
+//#region src/ash-generator.d.ts
+/**
+ * ASH source generator for agent-run.
+ *
+ * Converts validated tool_calls into a single ASH program
+ * with @caps scoped to the exact paths in this round's calls.
+ */
+interface ValidatedToolCall {
+  id: string;
+  op: "read" | "list" | "exec";
+  path: string;
+  args: Record<string, unknown>;
+}
+/**
+ * Generate a complete ASH program from validated tool calls.
+ *
+ * Each call becomes a separate pipeline within a single job.
+ * The program is scoped with @caps derived from actual paths.
+ */
+declare function generateAsh(calls: ValidatedToolCall[], round: number): string;
+//#endregion
+//#region src/context.d.ts
+interface ContextMemoryOptions {
+  /** AFS exec path for recall (e.g. "/modules/memory/.actions/recall"). */
+  recallPath: string;
+  /** Max tokens for memory injection into system message. Default: 2000. */
+  maxTokens?: number;
+  /** Domain filter passed to recall. */
+  domain?: string;
+}
+interface ContextOptions {
+  /** Current user input / task. */
+  task: string;
+  /** System prompt (role, persona, instructions). */
+  system?: string;
+  /** Conversation history messages (passed through as-is). */
+  history?: Array<Record<string, unknown>>;
+  /** Memory recall configuration. Omit to disable memory. */
+  memory?: ContextMemoryOptions;
+  /** Additional directives appended to system message (e.g. STOP_DIRECTIVE, AFS_HINT). */
+  directives?: string[];
+}
+interface MemoryTraceEntry {
+  tokens: number;
+  entries: number;
+  sources: string[];
+}
+interface ContextManifest {
+  memory: {
+    selected: string[];
+    query?: string;
+    available?: number;
+  };
+  history: {
+    keptTurns: number;
+    truncatedTurns: number;
+    compressed: boolean;
+  };
+  tools: {
+    included: string[];
+  };
+}
+interface ContextTrace {
+  system: {
+    tokens: number;
+  };
+  memory: MemoryTraceEntry | null;
+  history: {
+    tokens: number;
+    messages: number;
+  };
+  user: {
+    tokens: number;
+  };
+  total: number;
+  manifest?: ContextManifest;
+}
+interface ContextResult {
+  messages: Array<{
+    role: string;
+    content: string;
+    [key: string]: unknown;
+  }>;
+  trace: ContextTrace;
+}
+/**
+ * Assemble a messages array for LLM calls.
+ *
+ * Output order: [system, ...history, user]
+ *
+ * System message = system prompt + memory recall + directives.
+ * Without memory, output is identical to agent-run's current hand-assembled messages.
+ * Memory failures silently fall back to the no-memory path.
+ */
+declare function buildContext(afs: AFSRoot, opts: ContextOptions): Promise<ContextResult>;
+//#endregion
+//#region src/context-compress.d.ts
+/**
+ * Check if messages need compression and compress if necessary.
+ *
+ * Returns the original messages array (same reference) if no compression is needed,
+ * or a new array with compressed messages if compression was performed.
+ *
+ * Compression is best-effort: if callLLM fails, returns original messages unchanged.
+ * When compression succeeds, calls `onCompressed` with the new messages for history rewrite.
+ *
+ * Note: compression LLM call token usage is NOT counted toward agent-run's total_tokens budget.
+ * This is intentional — compression is a meta-operation, not a user-facing LLM interaction.
+ */
+/** Progress info emitted during compression. */
+interface CompressProgress {
+  phase: "triggered" | "summarizing" | "done" | "skipped" | "failed";
+  /** Estimated tokens before compression. */
+  beforeTokens: number;
+  /** Context window size. */
+  contextWindow: number;
+  /** Number of messages being compressed (triggered/summarizing/done). */
+  compressedMessages?: number;
+  /** Number of messages kept (triggered/summarizing/done). */
+  keptMessages?: number;
+  /** Estimated tokens after compression (done only). */
+  afterTokens?: number;
+  /** Error message (failed only). */
+  error?: string;
+}
+declare function maybeCompress(messages: Array<Record<string, unknown>>, opts: {
+  contextWindow?: number;
+  /**
+   * Anchor message that must be preserved verbatim across compressions
+   * (typically the current user task). Identified by object reference.
+   * If the anchor falls in the compress zone, it is excluded from the
+   * summary and re-inserted between the system message and the summary
+   * so the LLM always sees a clear "what the user asked" anchor.
+   */
+  pinMessage?: Record<string, unknown>;
+  callLLM: (args: Record<string, unknown>) => Promise<AFSExecResult>;
+  onCompressed?: (compressedMessages: Array<Record<string, unknown>>, archivedMessages: Array<Record<string, unknown>>) => Promise<void>;
+  onProgress?: (info: CompressProgress) => void;
+}): Promise<Array<Record<string, unknown>>>;
+//#endregion
+//#region src/messages-log.d.ts
+/**
+ * Append-only JSONL message log for inter-agent communication (L3).
+ *
+ * Provider internal: direct fs calls are allowed here (see CLAUDE.md).
+ */
+interface MessageEntry {
+  message_id: string;
+  from: string;
+  to: string;
+  kind: string;
+  ts: string;
+  seq: number;
+  body: unknown;
+}
+declare function appendMessage(filePath: string, from: string, to: string, body: unknown, kind?: string): MessageEntry;
+declare function readMessages(filePath: string, options?: {
+  since?: string;
+  limit?: number;
+}): MessageEntry[];
+declare function resetSeqCounter(): void;
+//#endregion
+//#region src/observability-routing.d.ts
+type OwnershipRoutingMode = "observe-only" | "strict-user" | "strict-all";
+//#endregion
+//#region src/orchestration.d.ts
+/**
+ * Resolve a user-provided model identifier into an absolute AFS path.
+ *
+ * - `/foo/bar` → verbatim (after `..` / `.` normalization, rejected if
+ *   any path segment is `.` or `..`).
+ * - `gpt-4o` → `/dev/ai/hubs/aignehub/models/gpt-4o`.
+ *
+ * The returned path may either point at a model NODE (e.g.
+ * `/dev/ai/hubs/aignehub/models/gpt-4o`) or directly at a chat-action
+ * leaf (e.g. `/dev/ai/.actions/chat`). The caller distinguishes via
+ * regex on `/.actions/(chat|embed|image|video)$`.
+ */
+declare function resolveAgentModelPath(model: string): string;
+/**
+ * Normalize tool calls to AIGNE format: { id, type: "function", function: { name, arguments } }.
+ *
+ * Accepts Vercel AI SDK ({ toolCallId, toolName, args }),
+ * OpenAI ({ id, type, function: { name, arguments: string } }),
+ * or already-normalized AIGNE format.
+ */
+declare function normalizeToolCallsToAIGNE(toolCalls: Array<Record<string, unknown>>): Array<Record<string, unknown>>;
+/**
+ * Runtime-supplied observability capability, injected into `AFSAgent` at
+ * construction by the host runtime (Node / CF) as an *object capability*.
+ *
+ * Crucially this is NEVER serialized into the JSON `AFSContext`, the agent's
+ * LLM-visible args, or any client-facing response. The `spaceResolver` handle
+ * lets the writer (Phase 3c) resolve a per-principal trace sink without the
+ * caller being able to name or forge a space.
+ */
+interface ObservabilityRuntime {
+  /** Space selector for per-principal trace sinks (Phase 2 contract). Absent
+   *  ⇒ user-class writes fail-closed in Phase 3c (no `/instance` fallback). */
+  spaceResolver?: SpaceResolver;
+  /** Where anonymous interactive runs persist: `"instance"` (Node — lands in
+   *  the instance slice) or `"ephemeral"` (CF — not persisted). */
+  anonymousInteractivePersistence: "instance" | "ephemeral";
+  /** Fail-closed stage (Phase 3e). Defaults to `"observe-only"` when absent. */
+  ownershipRoutingMode?: OwnershipRoutingMode;
+}
+interface ExecuteAgentRunOptions {
+  /** AFS root used for stat / exec / read / write. Defaults to the
+   *  caller-supplied `_scope_afs` arg if present, else `globalAfs`. */
+  globalAfs?: AFSRoot;
+  /** AFS path under which the ash provider is mounted. The `runAsh` dep
+   *  uses `${ashMountPath}/.actions/run` to delegate ash DSL execution.
+   *  Default: `/ash`. */
+  ashMountPath?: string;
+  /** Trusted caller context from RouteContext.context (AFSContext, populated
+   *  server-side in Phase 3a — never client-forgeable). As of Phase 3c it
+   *  DRIVES ownership routing: `caller.did` (userId = legacy mirror) →
+   *  persistence class, `instanceDid` → the DID-Space column, `agentRunOrigin`
+   *  → system vs interactive. `blockletId`/`sessionId` enrich the trace record
+   *  and the legacy instance-class probing. */
+  callerContext?: {
+    userId?: string;
+    blockletId?: string;
+    sessionId?: string;
+    caller?: {
+      did?: string | null;
+    } | null;
+    instanceDid?: string;
+    agentRunOrigin?: "interactive" | "system";
+    [key: string]: unknown;
+  };
+  /** Observability runtime capability (Phase 3b). Injected by the host at
+   *  provider construction and threaded here so the writer (Phase 3c) can
+   *  resolve per-principal trace sinks. Object capability — never serialized
+   *  into JSON context or LLM-visible args. Unconsumed in 3b (capability
+   *  injection only); the writer wires it in 3c. */
+  observabilityRuntime?: ObservabilityRuntime;
+}
+/**
+ * The full args → result pipeline. Same contract as the legacy
+ * `executeAgentRunImpl` method that used to live on AFSAsh, but as a
+ * standalone function with explicit deps.
+ *
+ * Does NOT enqueue on a session queue — that's the caller's job (see
+ * AFSAgent). Throws on validation failures (bad task / bad model)
+ * and returns an `AFSExecResult` envelope on runtime failures.
+ */
+declare function executeAgentRun(args: Record<string, unknown>, options?: ExecuteAgentRunOptions): Promise<AFSExecResult>;
+//#endregion
+//#region src/provider.d.ts
+interface AFSAgentOptions {
+  name?: string;
+  description?: string;
+  /**
+   * AFS path under which the ash provider is mounted. The `runAsh` dep
+   * inside agent-run delegates ash DSL execution to
+   * `${ashMountPath}/.actions/run`. Default `/ash` matches the canonical
+   * system mount.
+   */
+  ashMountPath?: string;
+  /**
+   * Maximum queued agent-run calls per session. Default 20.
+   */
+  maxSessionQueueDepth?: number;
+  /**
+   * Observability runtime capability (Phase 3b). The host runtime injects a
+   * `SpaceResolver` + anonymous-persistence policy here at construction so the
+   * writer (Phase 3c) can route each run's trace to the correct owning
+   * principal's space. This is an *object capability*: it is never read from
+   * the config JSON (`load`/`manifest.schema` ignore it) and never serialized
+   * into any client-visible context or LLM args.
+   */
+  observabilityRuntime?: ObservabilityRuntime;
+}
+declare class AFSAgent extends AFSBaseProvider {
+  static manifest(): ProviderManifest;
+  static load({
+    config
+  }?: AFSModuleLoadParams): Promise<AFSAgent>;
+  readonly name: string;
+  readonly description?: string;
+  readonly accessMode: AFSAccessMode;
+  private readonly ashMountPath;
+  private readonly sessionQueue;
+  private readonly observabilityRuntime?;
+  private afsRoot?;
+  constructor(options?: AFSAgentOptions);
+  onMount(afs: AFSRoot): void;
+  destroy(): void;
+  statRoot(_ctx: RouteContext): Promise<AFSStatResult>;
+  statRunAction(_ctx: RouteContext): Promise<AFSStatResult>;
+  listRootActions(_ctx: RouteContext): Promise<AFSListResult>;
+  execRootAction(ctx: RouteContext<{
+    action: string;
+  }>, args: Record<string, unknown>): Promise<AFSExecResult>;
+  /**
+   * Handler for the test-only `__debug-runtime` action (Phase 3b). Returns a
+   * boolean/string projection of the injected `observabilityRuntime` so E2E
+   * tests can assert the capability reached `/dev/agent` — but it deliberately
+   * omits the `spaceResolver` handle itself (object capability must not leave
+   * the host). Outside `AFS_TEST_MODE` it refuses with `AFS_PERMISSION` so
+   * production never exposes runtime wiring.
+   */
+  private execDebugRuntime;
+}
+//#endregion
+//#region src/scratchpad.d.ts
+/**
+ * Scratchpad provisioning — allocates per-run scratch directories under
+ * a session-scoped memory path.
+ *
+ * Provider internal: direct fs calls are allowed here (see CLAUDE.md).
+ */
+interface ScratchLayout {
+  basePath: string;
+  stateYml: string;
+  messagesJsonl: string;
+  eventsJsonl: string;
+  historyJsonl: string;
+}
+type ScratchRetention = "run" | "session" | "forever";
+declare function allocateScratch(memoryBasePath: string, session: string, runId: string): ScratchLayout;
+declare function getStateProxy(layout: ScratchLayout): Record<string, any>;
+declare function teardownSession(memoryBasePath: string, session: string, retention?: ScratchRetention): void;
+//#endregion
+//#region src/session-queue.d.ts
+/**
+ * Per-key Promise chain queue for serializing async operations.
+ *
+ * Used by ASHProvider to ensure same-session agent-run calls execute
+ * sequentially, preventing history file race conditions.
+ */
+declare function deriveChildSession(parentSessionId: string): string;
+declare function createSessionQueue(maxDepth?: number): {
+  queues: Map<string, Promise<unknown>>;
+  depths: Map<string, number>;
+  /**
+   * Enqueue an async function for serial execution within a session.
+   *
+   * - If session is undefined, executes directly (no queuing).
+   * - If the session queue is full, throws an Error with message starting with "QUEUE_FULL".
+   * - Otherwise, chains onto the session's Promise tail and awaits the result.
+   */
+  enqueue<T>(session: string | undefined, fn: () => Promise<T>): Promise<T>; /** Clear all queue state. Does not await in-progress executions. */
+  destroy(): void;
+};
+//#endregion
+//#region src/spawn-depth.d.ts
+declare function checkSpawnDepth(chain: string[], manifestMax?: number): void;
+//#endregion
+//#region src/token-estimator.d.ts
+/**
+ * Lightweight token estimation based on character types.
+ *
+ * Uses empirical heuristics for CJK characters, English words, and other characters
+ * to approximate token counts without requiring an external tokenizer.
+ */
+/**
+ * Estimate token count for a text string.
+ *
+ * Uses character-type-aware heuristics:
+ * - CJK characters: ~1.5 chars per token
+ * - English words: ~1 token per word
+ * - Other characters (punctuation, digits, whitespace): ~1 char per token
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * Estimate total tokens for an array of messages (OpenAI format).
+ *
+ * Handles:
+ * - `content` (string) — text tokens, capped per message
+ * - `toolCalls` / `tool_calls` — function name + arguments + structure overhead
+ *
+ * @param singleMessageLimit - Max tokens counted per individual message content
+ *   (prevents a single huge tool result from dominating the estimate)
+ */
+declare function estimateMessagesTokens(messages: Array<Record<string, unknown>>, singleMessageLimit?: number): number;
+//#endregion
+//#region src/tool-schema.d.ts
+interface OpenAITool {
+  type: "function";
+  function: {
+    name: string;
+    description: string;
+    parameters: {
+      type: "object";
+      properties: Record<string, Record<string, unknown>>;
+      required: string[];
+    };
+  };
+}
+/** Discovered action schema from startup discovery phase. */
+interface ActionSchema {
+  actionName: string;
+  description: string;
+  pathPattern: string;
+  inputSchema?: {
+    type?: string;
+    properties?: Record<string, Record<string, unknown> & {
+      type: string;
+      description?: string;
+    }>;
+    required?: string[];
+  };
+}
+/**
+ * Build OpenAI function-calling tools from ToolEntry declarations.
+ *
+ * Deduplicates operations across entries — one tool per unique op.
+ * Each tool's path description lists all allowed patterns for that op.
+ *
+ * When actionSchemas are provided (from startup discovery), generates
+ * per-action tools (afs_action_{name}) with explicit typed parameters
+ * so LLMs know exactly what fields each action requires.
+ */
+declare function buildToolSchema(tools: ToolEntry[], actionSchemas?: ActionSchema[]): OpenAITool[];
+//#endregion
+export { AFSAgent, type AFSAgentOptions, type ActionSchema, type AgentRunDeps, type AgentRunParams, type AgentRunResult, type ContextManifest, type ContextMemoryOptions, type ContextOptions, type ExecuteAgentRunOptions, type HistoryMessage, type HistoryToolCall, type MemoryTraceEntry, type MessageEntry, type ScratchLayout, type ScratchRetention, type ToolProgressEvent, type TraceEntry, type ValidatedToolCall, allocateScratch, appendMessage, buildContext, buildToolSchema, checkSpawnDepth, computeLLMRetryDelayMs, createSessionQueue, deriveChildSession, estimateMessagesTokens, estimateTokens, executeAgentRun, generateAsh, getStateProxy, maybeCompress, normalizeToolCallsToAIGNE, readMessages, resetSeqCounter, resolveAgentModelPath, runAgentLoop, teardownSession };
+//# sourceMappingURL=index.d.mts.map