@zaly/agent 0.0.3

package/dist/index.d.mts

@@ -0,0 +1,1605 @@
+import { p as SessionOptions, t as Session } from "./session-Ds5nJz5A.mjs";
+import { Emitter, Envelope, MaybeGetter } from "@zaly/shared";
+import { BaseCollection } from "@zaly/shared/collection";
+import { AnyKey } from "@zaly/shared/registry";
+import { AiError, AnyPart, AnyType, AssistantMessage, CollectOptions, Content, FinishReason, Message, MetaOf, MetaPart, Model, ParamsOf, ReasoningEffort, Role, StreamEvent, StreamOptions, TokenCount as TokenCount$1, Tool, ToolCallPart, ToolContext, ToolResult, ToolResultPart, Usage } from "@zaly/ai";
+import { Logger } from "@zaly/shared/logger";
+import { ArgsOpts, ArgsResult } from "@zaly/shared/args";
+//#region src/events.d.ts
+/** Status of an agent session — at most one transition per moment.
+ *  `paused` covers both explicit pause and post-error states; the
+ *  `lastError` field on the session disambiguates. */
+type AgentStatus = "idle" | "streaming" | "running-tools" | "compacting" | "paused";
+/** Reason the loop stopped this turn. Distinct from the provider's
+ *  `finishReason` (which describes why one round-trip ended). */
+type AgentStopKind = "natural" | "max-steps" | "token-budget" | "loop-detected" | "max-tool-errors" | "context-overflow" | "paused" | "aborted" | "error";
+/** Outcome kind of a single step (one provider round-trip + tool batch).
+ *  Returned from `step()` so custom drivers can interleave their own
+ *  logic between steps. */
+type StepKind = "natural" | "tool-calls" | "context-overflow" | "error";
+type AgentStop = {
+  kind: AgentStopKind;
+  reason?: string;
+  error?: Error;
+};
+/** Events emitted by an `Agent` as the loop runs. Listeners fire
+ *  synchronously; a throw inside a listener is caught and routed to
+ *  `onEmitError` so the loop keeps running.
+ *
+ *  Conversation-shape events (new message committed, head moved, …)
+ *  live on the `Session`, not here — subscribe via `agent.session.on(…)`. */
+type AgentEvents = {
+  status: {
+    status: AgentStatus;
+  };
+  start: {};
+  "stream-event": {
+    event: StreamEvent;
+  };
+  "tool-call": {
+    call: ToolCallPart;
+  };
+  "tool-calls": {
+    calls: ToolCallPart[];
+  };
+  "tool-result": {
+    call: ToolCallPart;
+    result: ToolResult;
+  };
+  "step-start": {
+    step: number;
+  };
+  "step-end": {
+    step: number;
+    outcome: StepKind;
+  };
+  "turn-start": {
+    turn: number;
+  };
+  "turn-end": {
+    turn: number;
+    outcome: AgentStopKind;
+    reason?: string;
+  };
+  stop: AgentStop & {
+    usage: TokenCount$1;
+    status: AgentStatus;
+  };
+  context: {
+    prompt: string[];
+    tools: Tool[];
+    messages: Message[];
+  };
+  pending: {
+    messages: Message[];
+  };
+};
+//#endregion
+//#region src/masker.d.ts
+/** Top-level masking config. */
+type MaskerOptions = {
+  enabled?: boolean;
+  /** Don't mask tool-result parts whose original content is shorter
+   *  than this (estimated tokens). Skips tiny "ok"-style success
+   *  messages where the stub would be larger than the original.
+   *  Doesn't apply to attachments (always worth masking). */
+  minTokens?: number;
+  /** How many turns to keep in the tail of the conversation, regardless
+   *  of score. Defaults to 20. */
+  keepTurns?: number;
+  /** How far above the target ratio to trigger a new masking pass.
+   *  Defaults to 0.25 (25%). */
+  delta?: number;
+  /** Target ratio of used/limit tokens to reach by masking. Defaults to 0.5 (50%). */
+  target?: number;
+};
+type MaskOpts = {
+  force?: boolean;
+  limit?: number;
+  ratio?: number;
+  tools?: Tool[];
+  prompt?: string[];
+};
+/** In-place mask projection for the request stream.
+ *
+ *  The masker replaces low-value parts with stable stubs to keep the
+ *  projected request within budget. A scoring pass ranks maskable parts
+ *  by recency, repeated-use shadowing, and per-policy weights; the budget
+ *  pass masks from lowest score upward until the target is reached or no
+ *  useful candidates remain.
+ *
+ *  Masking intentionally happens rarely because it changes historical
+ *  bytes and busts prefix cache. The first pass after startup/session
+ *  reset always rebuilds the projection. Later passes use a hysteresis
+ *  threshold: mask toward `target`, then trigger again at roughly
+ *  `actual + delta`. If the target cannot be reached, the next threshold
+ *  rises automatically to avoid repeated no-op cache busts.
+ */
+declare class Masker {
+  #private;
+  constructor(agent: Agent, opts?: MaybeGetter<MaskerOptions>);
+  get enabled(): boolean;
+  reset(): void;
+  get stats(): Map<Role, Record<string, number>>;
+  /** Number of messages with at least one masked part. */
+  get masked(): number;
+  isMasked(msgId: string, partIdx?: number): boolean;
+  /** Apply masks and return the projected message array.
+   *
+   *  Always rebuild once after startup/session reset: `pressure.ratio`
+   *  may describe a previously masked projection, while this instance has
+   *  no mask decisions yet. After that, rebuild only when projected
+   *  pressure crosses the hysteresis threshold. */
+  mask(messages: readonly Message[], opts?: MaskOpts): Promise<Message[]>;
+}
+//#endregion
+//#region src/permissions/types.d.ts
+/**
+ * Core permission primitives.
+ *
+ * - `Rule<T>` is the policy unit — pattern + verdict, scoped to a kind
+ *   of resource (`bash`, `read`, `write`, …).
+ * - `PermissionHandler<T>` is the validator for one or more scopes; the
+ *   manager dispatches `validate()` to the right handler.
+ * - `PermissionContext<T>` is what the handler sees on each call:
+ *   the matched `scope`, the rules pre-filtered to that scope, plus any
+ *   shared data (e.g. workspace directories) that the manager exposes
+ *   to all handlers.
+ *
+ * Scopes are open strings — built-ins are `bash | read | write | fetch`,
+ * but plugins register their own. `PermissionHandler<"a" | "b">` lets
+ * one impl handle multiple related scopes (e.g. `FileHandler` for both
+ * `read` and `write`, sharing workspace state via the context).
+ */
+type Verdict = "allow" | "deny" | "ask";
+type Rule<T extends string = string> = {
+  scope: T;
+  pattern: string;
+  policy: Verdict;
+};
+/** A handler-proposed action the user can promote (the matching pattern
+ *  / containing path that *would* have allowed the input). The handler
+ *  describes "what would have matched"; the UI picks the polarity
+ *  ("allow once", "allow always", "deny always") and writes the rule
+ *  back through the appropriate manager API.
+ *
+ *  - `kind: "rule"` → suggests adding a `Rule<scope>` with this pattern.
+ *  - `kind: "workspace"` → suggests adding a workspace directory; only
+ *     handlers operating over paths emit this.
+ */
+type Suggestion = {
+  kind: "rule";
+  scope: string;
+  pattern: string;
+  description?: string;
+} | {
+  kind: "workspace";
+  path: string;
+  description?: string;
+};
+type CheckResult = {
+  verdict: "allow";
+} | {
+  verdict: "deny";
+  reason: string;
+  /** Optional hints for the prompt UI. Each suggestion describes a
+   *  pattern/path that would have matched the input; the UI offers
+   *  polarity buttons ("allow once" / "allow always" / "deny always")
+   *  and applies the user's choice via the manager. */
+  suggestions?: Suggestion[];
+} | {
+  verdict: "ask";
+  reason: string;
+  ask: string;
+  suggestions?: Suggestion[];
+};
+interface PermissionContext<T extends string> {
+  /** The matched scope. Useful when a handler covers multiple scopes
+   *  (e.g. `FileHandler` for `"read" | "write"`) and wants to branch. */
+  scope: T;
+  /** Rules pre-filtered to `scope` by the manager. */
+  rules: readonly Rule<T>[];
+  /** Workspace directories shared across handlers — file scopes use
+   *  these as containment roots; bash uses them for cwd-aware checks.
+   *  All paths are absolute and pre-normalized. The session cwd is
+   *  always included as the first entry. */
+  workspaces: readonly string[];
+  /** Session cwd — absolute, pinned at manager construction. Use this
+   *  to resolve relative paths in `input`; never read `process.cwd()`
+   *  directly from a handler. */
+  cwd: string;
+  /** Re-enter the manager to validate a different scope. Used by
+   *  composite handlers — e.g. the bash handler delegates `<` redirects
+   *  and inferred file paths to `ctx.validate("read", path)` rather
+   *  than carrying file-rule logic itself. */
+  validate: (scope: string, input: string) => CheckResult;
+}
+interface PermissionHandler<T extends string> {
+  validate(input: string, ctx: PermissionContext<T>): CheckResult;
+}
+//#endregion
+//#region src/permissions/presets.d.ts
+/**
+ * Permission presets — verdict-keyed pattern lists in the same shape
+ * `parseRules` accepts. The TUI exposes these as `--preset strict`,
+ * `--preset readonly`, etc.; the manager resolves the chosen preset to
+ * the structured `Rule<string>[]` at construction.
+ *
+ * Pattern grammar:
+ *   "bash(ls:*)"     → bash command pattern
+ *   "read(/src/**)"  → workspace-relative gitignore pattern
+ *   "read(*)"        → matches every read in any workspace
+ *   "bash"           → bare scope, equivalent to `bash(*)` (match any cmd)
+ *
+ * Scope names are exact matches against the tool name they gate
+ * (snake_case). Underscored scopes work too (`task_stop`, `task_poll`).
+ */
+type PermissionPresetName = "strict" | "readonly" | "permissive" | "yolo";
+interface PermissionPreset {
+  description: string;
+  rules: Partial<Record<Verdict, string[]>>;
+}
+//#endregion
+//#region src/permissions/manager.d.ts
+type PermissionOptions = {
+  /** Session cwd — anchor for resolving relative paths and the default
+   *  spawn cwd for bash subprocesses. Pinned at construction; the agent
+   *  never mutates `process.cwd()`, and there's no `cd` tool. Defaults
+   *  to `process.cwd()`. */
+  cwd?: string;
+  /** Named preset — supplies a baseline rule set. Explicit `rules` win
+   *  over preset rules on conflict (first-match-wins resolution; user
+   *  rules are listed before preset rules at construction). */
+  preset?: PermissionPresetName;
+  rules?: Rule[] | Partial<Record<Verdict, string[] | undefined>>;
+  /** Initial workspace list. `cwd` is auto-added so the user doesn't
+   *  have to repeat it. Pass paths absolute (or relative — they'll be
+   *  resolved against `cwd`). */
+  workspaces?: readonly string[];
+};
+/**
+ * Owns per-session permission state and dispatches `validate(scope, input)`
+ * to the registered handler for `scope`. Handlers receive rules
+ * pre-filtered to their scope plus the shared workspace list.
+ *
+ * Mutators (`addWorkspace`, `addRule`, …) are how the prompt UI promotes
+ * an `ask` verdict — once the user picks "allow `Bash(git push:*)` for
+ * this session", the TUI calls `manager.addRule(...)` and subsequent
+ * `validate()` calls pick it up via the filter.
+ */
+declare class PermissionManager {
+  #private;
+  readonly cwd: string;
+  constructor(opts?: PermissionOptions);
+  get workspaces(): readonly string[];
+  addWorkspace(path: string): void;
+  removeWorkspace(path: string): void;
+  get rules(): readonly Rule[];
+  /** Rules whose scope has no registered handler — surfaces config
+   *  errors (typos, unknown scopes, malformed pattern strings). The TUI
+   *  can render these as a startup warning. */
+  get invalidRules(): readonly Rule[];
+  addRule(rule: Rule): void;
+  validate(scope: string, input: string): CheckResult;
+}
+//#endregion
+//#region src/skills.d.ts
+type SkillMeta = {
+  name: string;
+  mtime: number;
+  desc: string;
+  path: string;
+  unchanged?: boolean;
+};
+type SkillTool = Tool<{
+  name: string;
+}, unknown, SkillMeta>;
+/**
+ * Agent Skills support — discovery, catalog, and the activation tool.
+ *
+ * Locations scanned (subdirectories containing `SKILL.md`):
+ *   - `${cwd}/.agent/skills/`         — project
+ *   - `${homedir()}/.agent/skills/`   — user (cross-project)
+ *
+ * Project shadows user on name collision.
+ *
+ * Progressive disclosure (per the Agent Skills spec):
+ *   - Catalog (name + description) lives in the tool's schema /
+ *     description. The model sees this from the start.
+ *   - Body of the SKILL.md is loaded only when the tool is invoked.
+ *   - References (files under the skill's directory) are *enumerated*
+ *     at activation, not read — the model reads them via the `read`
+ *     tool when its instructions call for it.
+ *
+ * Lifecycle:
+ *   - Construct with `new Skills({ cwd })` — no I/O yet.
+ *   - Call `await skills.load()` to populate the catalog. Idempotent;
+ *     re-call to pick up newly installed skills (`/reload-plugins`).
+ *   - `skills.tool` returns the current activation tool, or undefined
+ *     when the catalog is empty. Lazily built; invalidated on reload.
+ */
+interface SkillEntry {
+  name: string;
+  desc: string;
+  mtime: number;
+  body: string;
+  /** Absolute path to the SKILL.md file. */
+  path: string;
+  /** Absolute path to the skill's base directory (parent of SKILL.md).
+   *  Used as the workspace anchor for permissions and as the root for
+   *  resolving references. */
+  dir: string;
+}
+interface SkillsOptions {
+  /** SKILL.md paths, sorted from highest to lowest precedence. */
+  paths?: string[];
+}
+declare class Skills {
+  #private;
+  readonly catalog: Map<string, SkillEntry>;
+  protected constructor(opts?: SkillsOptions);
+  static load(opts?: SkillsOptions): Promise<Skills>;
+  /** (Re)scan project + user `.agent/skills/` directories. Wipes the
+   *  current catalog and the cached tool, then repopulates. Safe to
+   *  call mid-session — agent uses `this.tool` per-step so the next
+   *  request after reload picks up the change. */
+  reload(): Promise<this>;
+  /** Skill base directories — pass each to `agent.permissions.addWorkspace`
+   *  so the model can read bundled `references/` files without tripping
+   *  permission asks. */
+  get dirs(): readonly string[];
+  /** The activation tool. Returns `undefined` when the catalog is empty
+   *  (the agent then omits skills entirely from the model's tool list,
+   *  per the spec). Lazily built on first access; invalidated by
+   *  `load()`. */
+  get tool(): Tool | undefined;
+  isActivated(skill: SkillEntry, ctx: ToolContext<SkillMeta>): Promise<boolean>;
+  activate(name: string, agent: Agent): Promise<{
+    call: import("@zaly/ai").ToolCallPart<string, {
+      name: string;
+    }>;
+    result: import("@zaly/ai").ToolResult<SkillMeta>;
+    messages: [import("@zaly/ai").Message<"system">, import("@zaly/ai").Message<"assistant">, import("@zaly/ai").Message<"tool">];
+  } | undefined>;
+}
+//#endregion
+//#region src/swarm.d.ts
+/** A registered agent in the swarm — a node in the agent tree. The
+ *  `name` IS the id: agents address each other by name, so there's no
+ *  point in maintaining a separate uuid the model would have to
+ *  remember. Collisions get an auto-suffix (`reviewer`, `reviewer-2`,
+ *  `reviewer-3`, …) resolved at `attach` time; reading `entry.name`
+ *  after attach tells the caller which suffix landed. The parent
+ *  relationship lives on `agent.parent` — single source of truth. */
+interface SwarmEntry {
+  /** Unique identity within the swarm. Same string as `name` (kept as
+   *  a separate field for code that wants to be explicit about "this
+   *  is the lookup key vs. the displayable name"). */
+  id: string;
+  /** Resolved name (with collision suffix if needed). What other
+   *  agents type when addressing this one. */
+  name: string;
+  desc: string;
+  agent: Agent;
+  /** Wallclock at registration. */
+  startedAt: number;
+}
+/** Options for spawning a new subagent via `Swarm.spawn`. */
+interface SpawnOptions {
+  /** Human-readable identity for inter-agent addressing — e.g.
+   *  `"reviewer"`, `"researcher"`. Other agents reference the spawned
+   *  agent by this name in `<agent>` meta tags. */
+  name: string;
+  /** What this agent is doing (one short line). Surfaced in
+   *  `task_list` / `<agent>` headers so the orchestrator can keep
+   *  track of who's working on what. */
+  desc: string;
+  /** System prompt for the child. Spelled out from scratch — the child
+   *  does NOT inherit the parent's prompt. */
+  prompt: string;
+  /** Initial task for the child. When set, the swarm sends it as the
+   *  child's first user message right after spawn. Omit to spawn an
+   *  agent that idles waiting for the first `send`. */
+  task?: string;
+}
+/**
+ * Tree of cooperating agents. One `Swarm` instance per agent tree —
+ * the orchestrator (root), every subagent it spawns, every subagent
+ * THEY spawn, all live in the same swarm and address each other by
+ * `name`.
+ *
+ * Responsibilities:
+ *   - Register / look up agents in the tree.
+ *   - Spawn subagents under a parent (delegates inheritance to
+ *     `parent.child(...)`; the swarm just records the metadata and
+ *     routes the initial task message).
+ *   - Route messages between agents (`send(from, to, content)`
+ *     injects a `<agent>` system message into the receiver carrying
+ *     the sender's identity).
+ *   - Tear-down (`stop(id)` aborts the agent and removes the entry).
+ *
+ * Not yet wired into `Tasks` or the tool catalog — that lands as a
+ * follow-up. This module is the data structure + lifecycle.
+ */
+declare class Swarm {
+  #private;
+  /** Look up an entry by id. */
+  get(id: string): SwarmEntry | undefined;
+  /** Reverse lookup: find an entry by Agent instance. Returns
+   *  `undefined` for agents that haven't been registered. */
+  find(agent: Agent): SwarmEntry | undefined;
+  /** All registered entries (root + every subagent). */
+  get entries(): readonly SwarmEntry[];
+  /** Direct children of the given agent (one level only). Walks the
+   *  agent-side parent pointer (`agent.parent`) so the swarm stays
+   *  free of duplicate parent state. */
+  children(parent: Agent): SwarmEntry[];
+  /** Register an existing Agent in the swarm. Use this to label the
+   *  root (the orchestrator that wasn't spawned by `spawn`) with a
+   *  name + description so other swarm members can address it.
+   *
+   *  The `name` doubles as the entry's id — the swarm resolves
+   *  collisions by auto-suffixing (`reviewer`, `reviewer-2`, ...).
+   *  Read the returned `entry.name` to find the actual assigned
+   *  identity if you care which suffix landed.
+   *
+   *  Idempotent on the same `Agent` instance: re-attaching returns
+   *  the existing entry, ignoring the new opts. To re-name an agent,
+   *  `stop()` first then re-attach.
+   *
+   *  Reserved: `name` of `"user"` and the empty string both throw —
+   *  the former conflicts with the human-sender identity in `<agent>`
+   *  meta; the latter is a programming error. */
+  attach(agent: Agent, opts: {
+    name: string;
+    desc: string;
+  }): SwarmEntry;
+  /** Spawn a new subagent under `parent`. Inheritance (cwd, model,
+   *  permissions, effective tools) is delegated to `parent.child(...)`;
+   *  the swarm then attaches the child and (optionally) seeds it with
+   *  `opts.task` as its first user message. */
+  spawn(parent: Agent, opts: SpawnOptions): Promise<SwarmEntry>;
+  /** Send a message from one agent to another. The receiver gets a
+   *  message tagged `<agent>` with sender metadata (`name` + `id`) so
+   *  it can parse who's speaking and respond by addressing them back.
+   *
+   *  Role:
+   *    - `role: "user"` when the sender is the receiver's parent (or
+   *      the literal `"user"`) — from the receiver's perspective the
+   *      sender IS its user.
+   *    - `role: "system"` otherwise (child → parent reports, sibling
+   *      messages, unregistered senders). */
+  send(from: Agent | "user", to: Agent, content: string): void;
+  /** Stop a registered subagent. Aborts its in-flight run and removes
+   *  the entry. The `Agent` itself is NOT disposed — call
+   *  `agent.dispose()` separately if you need its resources released. */
+  stop(id: string): void;
+  /** Stop every registered agent in the swarm. */
+  stopAll(): void;
+}
+//#endregion
+//#region src/ctx.d.ts
+type AgentContextOptions = Omit<AgentOptions, "session"> & {
+  session: Session;
+};
+type AgentContextEvents = {
+  model: {
+    model?: Model;
+    prev?: Model;
+  };
+  reasoning: {
+    effort: ReasoningEffort;
+    prev?: ReasoningEffort;
+  };
+  session: {
+    session: Session;
+    prev?: Session;
+  };
+  cwd: {
+    cwd: string;
+    prev?: string;
+  };
+  skills: {
+    skills?: Skills;
+  };
+};
+declare class AgentContext extends Emitter<AgentContextEvents> {
+  #private;
+  constructor(opts: AgentContextOptions);
+  private start;
+  attach(agent: Agent): void;
+  get messages(): readonly import("@zaly/ai").Message[];
+  get status(): AgentStatus | undefined;
+  get opts(): AgentOptions;
+  get cwd(): string;
+  set cwd(c: string);
+  get signal(): AbortSignal | undefined;
+  get agent(): Agent;
+  get reasoning(): ReasoningEffort;
+  set reasoning(r: ReasoningEffort);
+  get session(): Session;
+  useSession(s: Session): Promise<void>;
+  get model(): Model | undefined;
+  set model(m: Model | undefined);
+  set tools(tools: Tool[]);
+  get tools(): Tool[];
+  get prompt(): string[];
+  set prompt(p: string[]);
+  swarm(): Promise<Swarm>;
+  set skills(s: Skills | undefined);
+  get skills(): Skills | undefined;
+  private notifier;
+  masker(): Promise<Masker | undefined>;
+  permissions(): Promise<PermissionManager>;
+}
+declare function createAgentContext(opts: AgentOptions): Promise<AgentContext>;
+declare function createAgent(opts: AgentOptions): Promise<Agent>;
+//#endregion
+//#region src/tasks.d.ts
+/** Status of a task. `pending` = queued behind a dependency, not yet
+ *  started. `running` = work in progress (a Streamable is being polled).
+ *  `done` = result captured, no longer mutating. */
+type TaskStatus = "pending" | "running" | "done";
+/** Public projection of a registered task. Status-discriminated so the
+ *  fields visible at any moment are exactly the ones that make sense
+ *  for that lifecycle stage:
+ *
+ *    - `running`: `elapsedMs` since start; `hasNewOutput` when the
+ *      streamable signals that `task_poll` would yield bytes.
+ *    - `pending`: queued behind another task (`waitingFor`); `elapsedMs`
+ *      counts time-since-registration.
+ *    - `done`: settled. Carries `durationMs` and the captured `result`.
+ *
+ *  This is the only public task type — the registry exposes it via
+ *  `running()` / `finished()` / `get()`, events carry it (`task-done`
+ *  is narrowed to `status: "done"` so listeners get `result` typed
+ *  without checks), and `task_list` JSON-stringifies it directly. */
+type TaskInfo = {
+  id: string;
+  type: string;
+  desc: string;
+} & ({
+  status: "running";
+  elapsedMs: number;
+  hasNewOutput?: boolean;
+} | {
+  status: "pending";
+  waitingFor: string;
+  elapsedMs: number;
+} | {
+  status: "done";
+  durationMs: number;
+  result: ToolResult;
+});
+/** A `TaskInfo` known to be in the `done` state. `task-done` event
+ *  payloads use this so listeners get `result` and `durationMs` typed
+ *  without manual narrowing. */
+type DoneTaskInfo = Extract<TaskInfo, {
+  status: "done";
+}>;
+/** Events emitted by a `Tasks` instance. `task-done` only fires for
+ *  completions that happen *outside* an in-flight `run()` round —
+ *  round-internal completions are folded into the `run()` return value
+ *  instead. `heartbeat` fires periodically (when `heartbeatMs` is set
+ *  and at least one task is active), giving the agent a hook to keep
+ *  the model engaged on long-running work. */
+type TasksEvents = {
+  "task-added": {
+    task: TaskInfo;
+  };
+  "task-removed": {
+    task: TaskInfo;
+  };
+  "task-done": {
+    task: DoneTaskInfo;
+  };
+  heartbeat: {
+    running: readonly TaskInfo[];
+  };
+};
+/** Augment ToolMeta so tools and consumers can read freshness/state info
+ *  off `ToolResultPart.meta.task`. The registry stamps this on every
+ *  result it produces so the model can correlate placeholders to their
+ *  eventual completion. */
+interface TaskMeta {
+  task?: {
+    id: string;
+    status: TaskStatus;
+    type: string;
+    desc: string;
+    dependsOn?: string;
+    durationMs?: number;
+  };
+}
+/**
+ * Tool registry + execution machinery + long-running task bookkeeping.
+ * One Tasks instance per Agent. Owns the tool list (the agent delegates
+ * `agent.tools` to it) and runs every assistant tool batch through
+ * `run()`, which:
+ *
+ *  - validates each call's params,
+ *  - dispatches to the named tool (sync results land immediately),
+ *  - races `Streamable` returns against a grace window,
+ *  - chains `parallel: false` calls behind their predecessors,
+ *  - returns `ToolResultPart[]` 1:1 with the assistant's calls,
+ *    surfacing partial results / placeholders for anything still running
+ *    when the grace expires.
+ *
+ * Completions during a round are folded into the returned parts and do
+ * NOT fire `task-done`. Completions afterward fire normally — the agent
+ * listens and injects a system message into the next step.
+ */
+declare class Tasks extends Emitter<TasksEvents> {
+  #private;
+  graceMs: number;
+  get heartbeatMs(): number | undefined;
+  set heartbeatMs(value: number | undefined);
+  /** Snapshot of every active task (pending or running). */
+  running(): readonly TaskInfo[];
+  /** Snapshot of every task that has completed. Drops are by `remove()`
+   *  or implicit retention; this list grows unless the caller prunes. */
+  finished(): readonly DoneTaskInfo[];
+  /** Look up a task by id. Useful for `task_stop` / `task_poll`. */
+  get(id: string): TaskInfo | undefined;
+  /** Snapshot of every task in the registry — running, pending, and done. */
+  info(): readonly TaskInfo[];
+  tools(): Promise<readonly Tool[]>;
+  set $tools(tools: (() => Promise<readonly Tool[]>) | Tool[]);
+  /** Non-consuming check: does the underlying streamable have output
+   *  the model hasn't seen since the last `poll()`? Returns false for
+   *  tasks without a streamable, completed tasks, or streamables that
+   *  don't implement the optional `hasNew` hook (no signal to give).
+   *  Used by heartbeats to flag tasks worth polling. */
+  hasNewOutput(id: string): boolean;
+  /** Poll a task's streamable for incremental output without changing
+   *  its lifecycle state. Advances the streamable's cursor — the next
+   *  call returns only what arrived since *this* one. Returns the same
+   *  `ToolResult` shape the original tool produces (parts + meta).
+   *  Errors when the task is unknown, already done, or has no streamable
+   *  (the latter is the case for plain-Promise tools — there's no
+   *  partial state to read). */
+  pollOutput(id: string): ToolResult & {
+    running: boolean;
+  };
+  /** Drop a task from the registry — does not abort. Caller is
+   *  responsible for `abort()`-ing if the task is still running. */
+  remove(id: string): boolean;
+  /** Mark a task done with a final result. Fires `task-done` UNLESS the
+   *  task is currently owned by an in-flight `run()` round — in that
+   *  case the round folds the completion into its returned parts and
+   *  the event is suppressed. Starts any pending dependents. */
+  done(id: string, result: ToolResult): void;
+  /** Abort a running task. Calls the streamable's `abort()` if present;
+   *  pending tasks transition straight to `done` with a cancelled
+   *  result. Idempotent. */
+  abort(id: string, reason?: string): void;
+  /** Abort every active task. Used on agent dispose. Awaits each
+   *  task's `donePromise` so the registry is fully drained before
+   *  resolving — so callers can rely on no pending I/O after `dispose`. */
+  killAll(): Promise<void>;
+  /**
+   * Execute a batch of assistant tool calls. Returns ToolResultPart[]
+   * mapped 1:1 with `calls`. Sync completions land in the result array
+   * immediately; long-running ones return a placeholder and the eventual
+   * completion fires `task-done` post-round (the agent injects a system
+   * message in response).
+   *
+   * The `messages` snapshot is what tools see on `ctx.messages` — pass
+   * the conversation up to (and including) the assistant message that
+   * produced these calls, so freshness checks can scan back through
+   * prior tool results.
+   */
+  run(calls: readonly ToolCallPart[], ctx: ToolContext, opts?: {
+    onResult?: (call: ToolCallPart, result: ToolResultPart, idx: number) => void;
+  }): Promise<ToolResultPart[]>;
+}
+/** Render an array of `TaskInfo` as a `<tasks>` MetaPart for the model
+ *  (heartbeat pulses and `task_list`). Each task lands as one line of
+ *  JSON. The `result` field on done tasks is stripped — listing should
+ *  give an inventory, not historical output (the result was already
+ *  injected as a system message at task-done time, and re-shipping it
+ *  on every heartbeat / list call would be a token bomb). */
+declare function taskInfoPart(info: readonly TaskInfo[]): MetaPart;
+/** Build an `inject`-ready system message for a finished task. */
+declare function taskCompletionMessage(task: DoneTaskInfo): Message<"system">;
+//#endregion
+//#region src/utils/usage.d.ts
+/** Sum two Usages. Optional fields are only present in the result
+ *  when at least one input had them set, so callers can tell "no
+ *  reasoning happened this turn" apart from "0 reasoning tokens." */
+declare function addUsage(a: Usage, b: Usage): Usage;
+declare class TokenUsage implements Usage {
+  #private;
+  constructor(messages?: readonly Message[]);
+  get cost(): Usage;
+  get input(): number;
+  get output(): number;
+  get cacheRead(): number;
+  get cacheWrite(): number;
+  get reasoning(): number;
+  add(count: Usage): void;
+  resetLast(): void;
+  get last(): Usage;
+  get total(): Usage;
+  get contextSize(): number;
+}
+//#endregion
+//#region src/agent.d.ts
+/**
+ * Long-lived agent — drives the multi-turn loop, owns the run-time
+ * status / queues, and delegates conversation state to a `Session`.
+ *
+ * Typical interactive use:
+ *
+ * ```ts
+ * const agent = await Agent.load({ model, tools })
+ * agent.session.on("node", (e) => render(e))
+ * agent.send({ role: "user", content: "hi" })          // auto-runs
+ * // …user types again later…
+ * agent.send({ role: "user", content: "follow-up" })   // queues if running
+ * ```
+ *
+ * Headless / one-shot use is just a thin wrapper on top — see
+ * `runAgent` in the test helpers.
+ */
+declare class Agent extends Emitter<AgentEvents> {
+  #private;
+  /** Nesting depth — see `AgentOptions.depth`. Read-only; subagents pass
+   *  `parent.depth + 1` when constructing their child. */
+  readonly depth: number;
+  /** Cap on `depth` — see `AgentOptions.maxDepth`. */
+  readonly maxDepth: number;
+  /** Synchronous, low-level constructor. Prefer `Agent.load(opts)` —
+   *  it runs the same construction *plus* any async setup (resolving
+   *  `session: SessionOptions` to a built `Session`, skills discovery,
+   *  future warm-ups). The constructor is `protected` so test doubles /
+   *  subclasses can still call `super(init)` directly; they're
+   *  responsible for providing a pre-built `Session` on `init.session`. */
+  constructor(ctx: AgentContext);
+  reset(): Promise<void>;
+  /** Spawn a child agent that inherits this agent's runtime defaults —
+   *  cwd, model, permissions, full effective tool list (user tools +
+   *  the loaded skill tool), `depth + 1`, and `maxDepth`. Pass
+   *  `overrides` to specialize: typical ones are `prompt` (the child
+   *  has its own role), `session` (the child writes to its own JSONL),
+   *  and `tools` (curated subset).
+   *
+   *  Used by the `subagent` tool for delegation; equally useful for
+   *  ad-hoc parallel-agent patterns (multiple children working on
+   *  pieces of a task in parallel).
+   *
+   *  Depth cap: when the child would be at `maxDepth`, the `subagent`
+   *  tool is filtered out of its inherited tool list so recursion
+   *  bottoms out cleanly. The model just doesn't see the tool — no
+   *  error path. */
+  child(overrides?: Partial<AgentOptions>): Promise<Agent>;
+  /** Active conversation — delegates to the underlying `Session`. */
+  get messages(): readonly Message[];
+  get status(): AgentStatus;
+  get cwd(): string;
+  get model(): Model | undefined;
+  get session(): Session;
+  get signal(): AbortSignal | undefined;
+  /** Token usage from the most recent step's response. Drives
+   *  `contextSize` and any "this turn used N tokens" UI. */
+  get usage(): TokenUsage;
+  /** Cumulative token usage across every step in the current run.
+   *  Useful for billing-style displays. */
+  get totalUsage(): TokenCount$1;
+  /** Logical size of the current conversation in tokens — what the
+   *  next request will send as input. Equals the last step's
+   *  `input + output` (since the model's reply becomes part of the
+   *  next prompt). Returns 0 before any step has run. */
+  get contextSize(): number;
+  get pressure(): ContextPressure;
+  get lastStop(): AgentStop | undefined;
+  get steps(): number;
+  get parent(): Agent | undefined;
+  get tools(): Tool<unknown, unknown, object>[];
+  get prompt(): string[];
+  get ctx(): AgentContext;
+  /** Long-running task registry — exposed for the TUI / introspection
+   *  tools (`task_list`, etc.). Mutating directly is a foot-gun;
+   *  prefer the agent's higher-level surface. */
+  get tasks(): Tasks;
+  /** Append a message and (re)start the loop. The user spoke; the agent
+   *  responds. If a loop is currently running, the message lands on the
+   *  follow-up queue and is processed after the current turn naturally
+   *  stops. Otherwise the loop starts immediately. */
+  send(message?: Message | Message[], opts?: {
+    mode?: SendMode;
+    run?: boolean;
+  }): void;
+  useTool<T extends Tool = Tool>(name: T["name"], params: ParamsOf<T>, msg: string, opts?: {
+    hidden?: boolean;
+  }): Promise<{
+    call: ToolCallPart<T["name"], ParamsOf<T>>;
+    result: ToolResult<MetaOf<T>>;
+    messages: [Message<"system">, Message<"assistant">, Message<"tool">];
+  }>;
+  notify(type: string, data: Content | Record<string, unknown>): void;
+  /** Schedule a one-shot wake-up at `delayMs` from now. The agent will
+   *  receive a system message at that time IF nothing else has woken
+   *  the loop in the meantime — task-done injects, heartbeats, and user
+   *  messages all auto-cancel pending wakeups (their job was to ensure
+   *  the agent gets a turn; if it's already getting one, the timer is
+   *  redundant).
+   *
+   *  Cancelled wakeups don't silently disappear — their `hint`s, if any,
+   *  are folded into a system message that lands in the next step
+   *  alongside whatever woke the loop. The model sees the hints with a
+   *  `status="cancelled"` marker so it knows the timer didn't fire.
+   *
+   *  Returns the wakeup id (mostly for telemetry / TUI display — the
+   *  model can't usefully cancel it later, since by the time it has a
+   *  turn to call cancel, the wakeup has either fired or been cancelled
+   *  for it). */
+  scheduleWakeup(opts: {
+    delayMs: number;
+    hint?: string;
+  }): string;
+  /** Drive steps until the agent goes idle (no queued messages and
+   *  the model stopped naturally) or hits a non-recoverable stop.
+   *  Doubles as a resume from `paused` — drains queued messages and
+   *  picks the loop back up. If a run is already in flight, returns
+   *  the existing promise. */
+  run(): Promise<AgentStopKind>;
+  /** Run exactly one step. Useful for tests and custom drivers
+   *  that want to interleave logic between steps. */
+  step(): Promise<StepResult>;
+  compact(): Promise<void>;
+  /** Resolve when the agent is in a quiescent state — `idle` or
+   *  `paused`. If a run is currently in flight (or was just kicked off
+   *  synchronously by `send` / `inject` / a wakeup), waits for it to
+   *  settle before returning the final status. If no run is in flight,
+   *  resolves immediately with the current status.
+   *
+   *  Use this in REPL-style drivers to await the loop without racing
+   *  with internally-triggered runs (the wakeup timer, heartbeat, or
+   *  task-completion injects all spawn `void this.run()` independently
+   *  of caller-driven `await agent.run()`). The `#running` promise is
+   *  set synchronously inside `run()` before any await point, so this
+   *  catches every kicked-off cycle including the one `send` just fired.
+   *
+   *  Errors from the loop are swallowed — callers read `agent.lastError`
+   *  / `agent.lastStopReason` for diagnostics. The point of `waitIdle`
+   *  is just to know "the loop is no longer driving." */
+  waitIdle(timeout?: number): Promise<AgentStatus>;
+  /** Stop the loop with a custom reason.
+   * When `abort: true` (the default), also trigger the abort signal so any
+   * in-flight stream or tool calls can react to the stop.
+   * When `abort: false`, the agent still stops immediately, but any active
+   * stream or tool calls are left to run to completion */
+  stop(opts?: {
+    abort?: boolean;
+    reason?: string;
+  }): void;
+  start(): Promise<void>;
+  get started(): boolean;
+  /** Tear down session-scoped resources. Called on agent disposal — the
+   *  agent doesn't auto-dispose today, so callers (TUI on quit, headless
+   *  runner on completion) should invoke this explicitly. */
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/compaction/utils.d.ts
+type ToolStat = {
+  count: number;
+  score: number;
+  /** Turns ago at the most recent occurrence (0 = current/last turn).
+   *  Use with `lastTs` to give the agent both an "in-experience" recency
+   *  signal and a wall-clock staleness signal. */
+  lastTurn: number;
+  /** Wall-clock ms timestamp of the most recent occurrence. `0` if no
+   *  occurrence carried a timestamp. */
+  lastTs: number;
+};
+/** Per-file activity tally produced by `extractFiles`. Each entry is a
+ *  path that the agent touched, with per-kind counts and a frecency
+ *  `score` that downweights older touches and weights writes/edits
+ *  more than reads. Sort the top-N by `score` to surface the active
+ *  working set; `reads` / `writes` / `edits` give the per-kind detail
+ *  for display. */
+type FileUsage = ToolStat & {
+  path: string;
+  reads: number;
+  writes: number;
+  edits: number;
+};
+/** Per-command activity tally produced by `extractBashCommands`. `count`
+ *  is raw invocations; `score` is the same number but exp-decay-weighted
+ *  by turn distance from the end of the conversation, so recently-used
+ *  commands rank above old hot ones. */
+type BashUsage = ToolStat & {
+  command: string;
+};
+type ToolStatOptions = {
+  minCount?: number;
+  minScore?: number;
+  limit?: number;
+  sort?: "score" | "count" | "key";
+};
+/** Walk assistant tool-calls for `read` / `write` / `edit` and tally
+ *  per-path activity with frecency-weighted scoring. Returns the top-N
+ *  by score. Each entry carries the per-kind breakdown so the
+ *  summarizer can describe the *kind* of activity ("heavily edited",
+ *  "read once, then written", "iteratively refined").
+ *
+ *  Paths are canonicalized via the cwd recorded on each call's session
+ *  node — relative paths are resolved against the cwd that was active
+ *  when the call ran, and `~` is expanded. Calls under different cwds
+ *  that target the same file thus collapse into one bucket. */
+declare function extractFileUsage(messages: readonly Message[], opts?: ToolStatOptions): FileUsage[];
+/** Walk assistant tool-calls for `bash`, parse each command line, and
+ *  tally per-command frecency. Plumbing commands (cat, head, grep, awk,
+ *  sed, …) are filtered out — they dominate raw counts but carry no
+ *  operational signal a summarizer would describe. Returns the top-N
+ *  by frecency `score`. */
+declare function extractBashUsage(messages: readonly Message[], opts?: ToolStatOptions): BashUsage[];
+/** Flatten a list of messages into a single tagged transcript. */
+declare function extractConversation(messages: readonly Message[], opts?: {
+  maxToolResultLen?: number;
+}): string;
+declare function messageTail(messages: readonly Message[], opts: {
+  keepTokens?: number;
+}): Message[];
+declare function formatBashUsage(commands: BashUsage[]): string;
+declare function formatFileUsage(files: FileUsage[]): string;
+//#endregion
+//#region src/compaction/compactions.d.ts
+type CompactionOptions = {
+  enabled: boolean;
+  threshold?: number;
+  /** Existing messages up to this many tokens will be preserved in the context */
+  keepTokens: number;
+  maxToolResultLen: number;
+  summaryTokens: number;
+  bash: ToolStatOptions;
+  files: ToolStatOptions;
+  signal?: AbortSignal;
+  reasoning?: ReasoningEffort;
+  trigger?: "manual" | "auto";
+};
+//#endregion
+//#region src/notify.d.ts
+type NotifyOptions = {
+  idle?: number;
+  periodic?: number;
+};
+//#endregion
+//#region src/permissions/handlers/registry.d.ts
+type HandlerLoader = () => PermissionHandler<string>;
+declare const builtin$2: {
+  readonly bash: () => PermissionHandler<"bash">;
+  readonly read: () => PermissionHandler<"read" | "write">;
+  readonly tool: () => PermissionHandler<"tool">;
+  readonly write: () => PermissionHandler<"read" | "write">;
+};
+/** Open registry of permission scopes — declaration-merge to add your
+ *  own. The keys give `ctx.need("…", input)` typed autocomplete and
+ *  catch typos at compile time. The value carries the *input* type for
+ *  that scope (almost always `string` — files take paths, bash takes
+ *  commands, the generic `tool` scope takes the tool name).
+ *
+ *  Built-ins:
+ *    - `bash`  → command string
+ *    - `read`  → absolute path
+ *    - `write` → absolute path
+ *    - `tool`  → tool name (or richer `name:arg` shape per tool)
+ *
+ *  Add your own scope:
+ *
+ *  ```ts
+ *  declare module "@zaly/agent" {
+ *    interface PermissionScopes {
+ *      fetch: string  // expects a domain (or "*" for any)
+ *    }
+ *  }
+ *  ```
+ *
+ *  Then `ctx.need("fetch", domain)` is typed end-to-end. You still need
+ *  to register a runtime handler via `handlerRegistry.register("fetch", …)`
+ *  — this interface is only the type-side declaration.
+ */
+interface PermissionScopes {
+  bash: string;
+  read: string;
+  tool: string;
+  write: string;
+}
+type BuiltinScope = keyof typeof builtin$2;
+type PermissionScope = keyof PermissionScopes;
+type AnyScope = PermissionScope | (string & {});
+declare const handlerRegistry: import("@zaly/shared/registry").Registry<HandlerLoader, {
+  readonly bash: () => PermissionHandler<"bash">;
+  readonly read: () => PermissionHandler<"read" | "write">;
+  readonly tool: () => PermissionHandler<"tool">;
+  readonly write: () => PermissionHandler<"read" | "write">;
+}>;
+//#endregion
+//#region src/stop.d.ts
+/** Caps + heuristics that can end a run early. Wired into the
+ *  `AgentSession` loop via a single `detect()` call after each step. */
+interface StopOptions {
+  /** Hard ceiling on provider round-trips per `run()`. Default: 50. */
+  maxSteps?: number;
+  /** Cumulative token cap across the whole `run()`
+   *  (`totalUsage.input + totalUsage.output`). */
+  tokenBudget?: number;
+  /** Bail after this many consecutive failing tool calls. A successful
+   *  tool result resets the streak. */
+  maxToolErrors?: number;
+  /** Same `(name, params)` appearing N times in a row → loop. Catches
+   *  the most common failure mode: re-calling `read_file` with the same
+   *  path expecting different output. Default 3. */
+  loopConsecutive?: number;
+  /** Bounded window for duplicate detection. Default 10. */
+  loopWindow?: number;
+  /** Within the window, this many duplicates of one call → loop.
+   *  Catches alternation patterns (`A B A B …`) the consecutive arm
+   *  alone won't see. Default 4. */
+  loopWindowRepeats?: number;
+}
+/**
+ * Subscribes to an `AgentEvent` stream, accumulates the bookkeeping
+ * the loop needs to make stop-or-continue decisions, and exposes a
+ * single `detect()` to consult after each step.
+ *
+ * Lives outside `AgentSession` so concerns separate cleanly:
+ *   - the session owns conversation, queues, status, and loop control;
+ *   - the policy owns counters and the rules that act on them.
+ *
+ * Wire it up via `attach(session)` (returns an unsubscribe), or feed
+ * events manually with `handle(event)` for custom drivers.
+ */
+declare class StopPolicy {
+  #private;
+  constructor(opts?: StopOptions);
+  /** Token usage from the most recent step's response. */
+  get usage(): TokenCount$1;
+  /** Cumulative token usage across every step in the current run. */
+  get totalUsage(): TokenCount$1;
+  get steps(): number;
+  get consecutiveErrors(): number;
+  /** Tool-call history fed to the loop detector. Read-only. */
+  get calls(): readonly ToolCallPart[];
+  /** Subscribe to an emitter. To detach later, register the listener
+   *  yourself and pass the same fn to `emitter.off(fn)`:
+   *
+   *    const handler = (e) => policy.handle(e)
+   *    emitter.all(handler)
+   *    // later:
+   *    emitter.off(handler) */
+  attach(emitter: Emitter<AgentEvents>): void;
+  /** Feed a single event into the policy. Public so custom drivers
+   *  can drive it without going through `attach`. */
+  handle(event: Envelope<AgentEvents>): void;
+  /** Reset per-run counters. Token totals (`usage` / `totalUsage`)
+   *  persist unless `keepUsage: false` is passed — billing-style
+   *  displays usually want them sticky across resets. */
+  reset(opts?: {
+    keepUsage?: boolean;
+  }): void;
+  /** Decide whether the loop should stop. Returns the stop reason or
+   *  `undefined` to continue. Order matters — `loop-detected` wins
+   *  over `max-tool-errors` if both fire, since a model in a tight
+   *  loop is the more pressing thing to surface. */
+  detect(): AgentStopKind | undefined;
+}
+//#endregion
+//#region src/types.d.ts
+type SendMode = "inject" | "append";
+declare module "@zaly/ai" {
+  interface ToolContext {
+    /** Reference to the running agent — surfaced for tools that need to
+     *  schedule future inject-style work (`wakeup`, future
+     *  notifications). Only populated when invoked through an `Agent`;
+     *  one-shot harnesses leave it undefined. */
+    agent?: Agent;
+    /** Override the default `bash` command used by the `bash` tool. */
+    bash?: string[];
+    /** Data directory for tools to read/write durable files. */
+    sessionDir?: string;
+    /** Permissions registry — manager.validate(scope, input) for tools
+     *  that gate themselves. */
+    perms?: PermissionManager;
+    /** Long-running task registry. Tools that need to introspect (the
+     *  task management tools) read it; ordinary tools can stay
+     *  Tasks-unaware and return a `Streamable` instead. */
+    tasks?: Tasks;
+    messages?: readonly Message[];
+    /** Swarm registry — populated when the running agent was
+     *  constructed with one (or inherited it from its parent). Tools
+     *  that spawn or message subagents (`agent_spawn`, `agent_send`)
+     *  read this. Absent on standalone agents and on test contexts
+     *  that build a `ToolContext` by hand. */
+    swarm?: () => Promise<Swarm>;
+    /** Async permission check tools call before doing work. Resolves on
+     *  `allow`, throws a `AiError(PERMISSION_DENIED)` on `deny`. For
+     *  `ask` verdicts, the agent invokes `AgentOptions.allow` (when
+     *  configured); if that returns `true` we resolve, otherwise we
+     *  throw. Absent on contexts without an Agent (eval / direct
+     *  `runTool`) — tools should treat a missing `need` as "no
+     *  permission system, allow."
+     *
+     *  Two layers of gating exist:
+     *    - `Tasks` auto-checks `tool` scope with the tool name on every
+     *      dispatch (so `tool(bash)` rules globally gate by name).
+     *    - Tools may opt into richer per-input checks via specialized
+     *      scopes (`bash(args.command)`, `read(path)`, …).
+     *
+     *  Scope names autocomplete from the `PermissionScopes` interface;
+     *  add your own via declaration merging. */
+    need?: <S extends PermissionScope>(scope: S, input: PermissionScopes[S]) => Promise<void>;
+    isMasked?: (msgId: string, partIdx?: number) => boolean;
+  }
+}
+/** Information passed to `AgentOptions.allow` when an `ask` verdict
+ *  needs interactive resolution. Carry-everything shape so the harness
+ *  can render a useful prompt: which scope, which input, why the
+ *  manager paused, and what rule (if added) would have allowed it. */
+interface PermissionRequest {
+  ask: string;
+  scope: string;
+  input: string;
+  reason: string;
+  suggestions?: Suggestion[];
+}
+/** Resolved-options shape handed to `Agent`'s protected constructor.
+ *  Identical to `AgentOptions` except `session` is the *built* `Session`
+ *  instance (constructed for you by `Agent.load`). Subclasses that call
+ *  `super(init)` directly need to provide their own pre-built session. */
+interface AgentInit extends Omit<AgentOptions, "session" | "skills" | "cwd" | "tools" | "prompt"> {
+  cwd: string;
+  session: Session;
+  skills?: Skills;
+  tools?: Tool[];
+  prompt?: string[];
+}
+/** Snapshot of context-window pressure. Computed by `agent.pressure`
+ *  from the most recent step's usage and the model's declared context
+ *  limit. Consumers (notifier, masker) escalate behavior on `level`
+ *  rises and reset on `level === 0` (e.g. after compaction). */
+interface ContextPressure {
+  /** Cumulative tokens occupying the context window — uncached input
+   *  + cached reads + cached writes + output. */
+  used: number;
+  /** Model's declared context limit (`model.spec.limit.context`). */
+  limit: number;
+  /** `used / limit`. Useful for fine-grained displays; downstream
+   *  triggers should typically branch on `level` instead. */
+  ratio: number;
+  /** Discrete escalation level: `0` below the lowest threshold, `1`
+   *  past 75%, `2` past 85%, `3` past 95%. Hysteresis-friendly —
+   *  consumers track the highest level reached and only reset on `0`. */
+  level: number;
+}
+/** Outcome of a single step (one provider round-trip + tool batch).
+ *  Returned from `step()` so custom drivers can interleave their own
+ *  logic between steps. */
+type StepResult = {
+  kind: StepKind;
+  message?: AssistantMessage;
+  toolMessage?: Message<"tool">;
+  finishReason: FinishReason;
+  usage: TokenCount$1;
+  error?: Error;
+};
+type TurnResult = {
+  kind: AgentStopKind;
+  reason?: unknown;
+};
+/** Options for constructing an `Agent`. */
+interface AgentOptions extends CollectOptions {
+  model?: Model;
+  /** Logger used for top-level agent error boundaries. */
+  logger?: Logger;
+  /** Session for the conversation.
+   *  When omitted, a fresh in-memory Session is created. Either way,
+   *  `messages` (if any) are appended to it. */
+  session?: Session | SessionOptions;
+  /** Initial working directory for the agent and its tools.
+   * Defaults to the process's current directory at load time.
+   */
+  cwd?: string;
+  /** Tools the model may call. Kernel-owned: the agent both passes
+   *  these to the provider on every step and dispatches calls against
+   *  them. Mutable post-construction via `agent.tools = …`. */
+  tools?: Tool[];
+  /** Stop-policy knobs — `maxSteps`, `tokenBudget`, `maxToolErrors`,
+   *  loop-detection tuning. Grouped under one key to keep the agent's
+   *  top-level surface focused. Omit to use defaults (see `StopPolicy`). */
+  stop?: StopOptions;
+  /** Either `PermissionOptions` (construct a fresh manager) or an
+   *  existing `PermissionManager` instance to reuse — used by subagents
+   *  to share the parent's workspaces + rules without copying. */
+  permissions?: Omit<PermissionOptions, "cwd"> | PermissionManager;
+  /** Per-call passthrough knobs (`temperature`, `toolChoice`,
+   *  `reasoning`, `responseFormat`, …). The agent owns `model`,
+   *  `messages`, `prompt`, and `tools` — those have dedicated
+   *  top-level fields here. */
+  request?: StreamOptions;
+  /** Initial messages appended to the session at construction. Useful
+   *  for seeding a fresh conversation or for prepending fixed context
+   *  to an existing session. */
+  messages?: Message[];
+  /** Durable system prompt — passed to every step's request and
+   *  routed by adapters to each provider's dedicated system slot. Use
+   *  this for "behave like X" instructions that don't change across
+   *  the session. For mid-conversation steering, `send()` a
+   *  `role: "system"` message instead. Mutable via `agent.prompt = …`. */
+  prompt?: string[];
+  /** Model's declared context window — enables silent-overflow detection. */
+  contextLimit?: number;
+  /** Nesting depth of this agent. `0` = top-level (user-facing).
+   *  Subagents bump this by 1 each time they spawn. The `subagent` tool
+   *  consults this to decide whether to expose itself to the spawned
+   *  child — at depth `maxDepth`, the child gets the parent's tool list
+   *  *without* the subagent tool, so recursion bottoms out cleanly.
+   *  Defaults to `0`. */
+  depth?: number;
+  /** Maximum allowed agent depth. Subagents at depth `< maxDepth` may
+   *  spawn further subagents; at depth `>= maxDepth`, the subagent tool
+   *  is filtered out of their tool list (no error — the model just
+   *  doesn't see it). Defaults to `2`, giving root → child → grandchild.
+   *  Top-level only — children inherit this from the parent at spawn
+   *  time. */
+  maxDepth?: number;
+  /** Enable the built-in `skill` tool (Agent Skills support). When
+   *  `true` (default), the agent constructs a `Skills` instance, scans
+   *  `${cwd}/.agent/skills/` and `~/.agent/skills/` on `skills.load()`,
+   *  and exposes the activation tool to the model. Set `false` to skip
+   *  skills entirely (no `skills` getter, no scanning, no tool). */
+  skills?: Skills;
+  /** Optional `Swarm` registry. When set, this agent participates in a
+   *  multi-agent swarm — children spawned via `agent.child()` inherit
+   *  the same swarm, and tools like `agent_spawn` / `agent_send`
+   *  become functional via `ctx.swarm`. The swarm is shared by every
+   *  agent in the tree; only the root needs to be configured with one.
+   *  Children inherit it automatically. */
+  swarm?: Swarm;
+  /** Heartbeat interval (ms) for the Tasks registry. While at least one
+   *  task is pending or running, the agent injects a `<heartbeat>` system
+   *  message at this cadence so the model sees what's still going and
+   *  the loop stays alive. Leave undefined to disable. Tune for the
+   *  workload — interactive sessions often want 30s; batch / autonomous
+   *  runs may want 5m. */
+  heartbeatMs?: number;
+  /** Runtime notifications: `session-started` / `session-resumed`,
+   *  `time` / `new-day` / `user-returned`, `model-changed`,
+   *  `context-pressure`. Defaults to enabled with sensible thresholds.
+   *
+   *  Pass `false` to disable entirely (tests usually want this — the
+   *  injected messages would otherwise show up in conversation
+   *  expectations); pass a `NotifyOptions` object to tune thresholds
+   *  while keeping the notifier active. */
+  notify?: boolean | NotifyOptions;
+  /** Tool-result masking. When enabled, the agent rewrites older
+   *  re-callable tool results (`read`, `fetch`, …) to compact stubs on
+   *  the way to the provider, freeing context without touching the
+   *  session DAG. Once a message is stamped, the stamp is durable for
+   *  the agent's lifetime — see `Masker` for the cache-stability rules.
+   *
+   *  Default off. Pass `true` to enable, or a `MaskOptions` object to
+   *  tune `tools` / `keepRecent`. */
+  mask?: MaybeGetter<MaskerOptions>;
+  /** Resolver for `ask` permission verdicts. The agent invokes this
+   *  with the scope / input / reason / suggestions; resolve `true` to
+   *  allow the call, `false` to deny. Absent → ask defaults to deny.
+   *
+   *  Hook a TUI prompt here, or return `true` unconditionally for
+   *  unattended runs that should treat ask as allow (yolo-but-richer). */
+  allow?: (req: PermissionRequest) => Promise<boolean>;
+  compaction?: MaybeGetter<Partial<CompactionOptions>>;
+  /** Override the default `bash` command used by the `bash` tool. */
+  bash?: string[];
+  loadModel?: (id: string) => Promise<Model>;
+}
+//#endregion
+//#region src/prompt/registry.d.ts
+interface PromptCtx {
+  model: Model;
+  cwd: string;
+}
+type PromptLoader = (ctx: PromptCtx) => Promise<string>;
+type Prompt<T extends string | PromptLoader = string | PromptLoader> = {
+  name: string;
+  text: T;
+};
+declare const builtin$1: {
+  readonly "AGENTS.md": (ctx: PromptCtx) => Promise<string>;
+  readonly "MEMORY.md": (ctx: PromptCtx) => Promise<string>;
+  readonly agent: () => Promise<string>;
+  readonly env: (ctx: PromptCtx) => Promise<string>;
+  readonly model: (ctx: PromptCtx) => Promise<string>;
+};
+type BuiltinPrompt = keyof typeof builtin$1;
+type AnyPrompt = BuiltinPrompt | (string & {});
+declare const promptRegistry: import("@zaly/shared/registry").Registry<PromptLoader, {
+  readonly "AGENTS.md": (ctx: PromptCtx) => Promise<string>;
+  readonly "MEMORY.md": (ctx: PromptCtx) => Promise<string>;
+  readonly agent: () => Promise<string>;
+  readonly env: (ctx: PromptCtx) => Promise<string>;
+  readonly model: (ctx: PromptCtx) => Promise<string>;
+}>;
+declare class PromptCollection extends BaseCollection<AnyPrompt[], Prompt[], Prompt> {
+  list(): Prompt[];
+  render(ctx: PromptCtx & {
+    prompts?: string[];
+  }): Promise<Prompt<string>[]>;
+}
+declare function promptCollection(): Promise<PromptCollection>;
+//#endregion
+//#region src/tools/registry.d.ts
+/** Per-load context handed to every tool factory. Lets factories
+ *  customise the tool — typically schema descriptions — based on the
+ *  agent's model and working directory. Tools that don't care about
+ *  init just ignore the arg. */
+interface ToolInit {
+  model: Model;
+  cwd: string;
+}
+type ToolLoader = () => Promise<Tool>;
+type BuiltinTool = keyof typeof builtin;
+type AnyTool = AnyKey<BuiltinTool>;
+declare const builtin: {
+  readonly agent_send: () => Promise<Tool<unknown, unknown, object>>;
+  readonly agent_spawn: () => Promise<Tool<unknown, unknown, object>>;
+  readonly bash: () => Promise<Tool<unknown, unknown, object>>;
+  readonly edit: () => Promise<Tool<unknown, unknown, object>>;
+  readonly fetch: () => Promise<Tool<unknown, unknown, object>>;
+  readonly find: () => Promise<Tool<unknown, unknown, object>>;
+  readonly grep: () => Promise<Tool<unknown, unknown, object>>;
+  readonly read: () => Promise<Tool<unknown, unknown, object>>;
+  readonly search: () => Promise<Tool<unknown, unknown, object>>;
+  readonly subagent: () => Promise<Tool<unknown, unknown, object>>;
+  readonly task_list: () => Promise<Tool<unknown, unknown, object>>;
+  readonly task_poll: () => Promise<Tool<unknown, unknown, object>>;
+  readonly task_stop: () => Promise<Tool<unknown, unknown, object>>;
+  readonly wakeup: () => Promise<Tool<unknown, unknown, object>>;
+  readonly write: () => Promise<Tool<unknown, unknown, object>>;
+};
+declare const toolRegistry: import("@zaly/shared/registry").Registry<ToolLoader, {
+  readonly agent_send: () => Promise<Tool<unknown, unknown, object>>;
+  readonly agent_spawn: () => Promise<Tool<unknown, unknown, object>>;
+  readonly bash: () => Promise<Tool<unknown, unknown, object>>;
+  readonly edit: () => Promise<Tool<unknown, unknown, object>>;
+  readonly fetch: () => Promise<Tool<unknown, unknown, object>>;
+  readonly find: () => Promise<Tool<unknown, unknown, object>>;
+  readonly grep: () => Promise<Tool<unknown, unknown, object>>;
+  readonly read: () => Promise<Tool<unknown, unknown, object>>;
+  readonly search: () => Promise<Tool<unknown, unknown, object>>;
+  readonly subagent: () => Promise<Tool<unknown, unknown, object>>;
+  readonly task_list: () => Promise<Tool<unknown, unknown, object>>;
+  readonly task_poll: () => Promise<Tool<unknown, unknown, object>>;
+  readonly task_stop: () => Promise<Tool<unknown, unknown, object>>;
+  readonly wakeup: () => Promise<Tool<unknown, unknown, object>>;
+  readonly write: () => Promise<Tool<unknown, unknown, object>>;
+}>;
+declare class ToolCollection extends BaseCollection<AnyTool[], AnyTool[], Tool> {
+  list(): AnyTool[];
+  load(tools?: AnyTool[]): Promise<Tool[]>;
+}
+declare function toolCollection(): Promise<ToolCollection>;
+//#endregion
+//#region src/tools/bash.d.ts
+type BashTool = typeof bashTool;
+declare const bashTool: import("@zaly/ai").Tool<{
+  command: string;
+  description?: string | undefined;
+  max_lines?: number | undefined;
+  timeout?: number | undefined;
+}, unknown, object>;
+//#endregion
+//#region src/tools/read.d.ts
+type ReadTool = typeof readTool;
+type FileMeta = {
+  path: string;
+  mtime: number;
+  kind: "read" | "write" | "edit";
+  /** True when the result reflects the whole-file content — set by
+   *  un-sliced `read` and by `write` (which always replaces the
+   *  full file). Used by the masker to know whether this result
+   *  subsumes earlier reads of the same path. `edit` never sets it
+   *  because the result is patch-relative. */
+  full?: boolean;
+  unchanged?: boolean;
+};
+type ReadToolMeta = FileMeta & {
+  offset: number;
+  limit: number;
+};
+/** Build the `read` tool with model-aware schema description. The
+ *  attachment-shape blurb is included only when the loaded model
+ *  actually accepts the relevant modality — text-only models see a
+ *  description that promises only text output, so they don't reach
+ *  for the tool expecting images they can't process. */
+declare const readTool: import("@zaly/ai").Tool<{
+  path: string;
+  offset?: number | undefined;
+  limit?: number | undefined;
+}, unknown, ReadToolMeta>;
+//#endregion
+//#region src/tools/edit.d.ts
+type EditTool = typeof editTool;
+type EditToolMeta = FileMeta & {
+  /** File content before any edit was applied. */
+  original: string;
+  /** File content after all edits were applied — exactly what's now on disk. */
+  content: string;
+};
+/**
+ * Apply one or more exact-text replacements to a file.
+ *
+ * Semantics:
+ *   - All `oldText` matches are resolved against the *original* file
+ *     content. Edits are not applied sequentially — so edit #1's
+ *     `newText` cannot accidentally produce a match for edit #2's
+ *     `oldText`.
+ *   - Each `oldText` must occur exactly once in the file (uniqueness
+ *     forces the model to disambiguate via context rather than guessing).
+ *   - Edits must not overlap. Nearby changes should be combined into a
+ *     single edit covering the surrounding block.
+ *   - The file is rewritten atomically: either every edit applies
+ *     cleanly or none do.
+ *
+ * Use `read` first to inspect the file. Keep `oldText` minimal but
+ * uniquely identifying. For full-file rewrites, use `write` instead.
+ */
+declare const editTool: import("@zaly/ai").Tool<{
+  path: string;
+  oldText: string;
+  newText: string;
+  edits?: {
+    oldText: string;
+    newText: string;
+  }[] | undefined;
+}, unknown, EditToolMeta>;
+//#endregion
+//#region src/tools/find.d.ts
+type FindTool = typeof findTool;
+type FindToolMeta = {
+  cwd: string;
+  glob: string | string[];
+  matches: number;
+  truncated: boolean;
+};
+declare const findTool: import("@zaly/ai").Tool<{
+  glob?: string | string[] | undefined;
+  cwd?: string | undefined;
+  paths?: string[] | undefined;
+  type?: "any" | "dir" | "file" | undefined;
+  exclude?: string[] | undefined;
+  hidden?: boolean | undefined;
+  ignore?: boolean | undefined;
+  follow?: boolean | undefined;
+  limit?: number | undefined;
+}, unknown, FindToolMeta>;
+//#endregion
+//#region src/tools/grep.d.ts
+type GrepTool = typeof grepTool;
+type GrepToolMeta = {
+  cwd: string;
+  pattern: string;
+  truncated: boolean;
+  cmd: string[];
+};
+declare const grepTool: import("@zaly/ai").Tool<{
+  pattern: string;
+  cwd?: string | undefined;
+  paths?: string[] | undefined;
+  glob?: string[] | undefined;
+  exclude?: string[] | undefined;
+  file_type?: string[] | undefined;
+  fixed_strings?: boolean | undefined;
+  case_sensitive?: boolean | undefined;
+  hidden?: boolean | undefined;
+  ignore?: boolean | undefined;
+  follow?: boolean | undefined;
+  context?: number | undefined;
+  limit?: number | undefined;
+}, unknown, GrepToolMeta>;
+//#endregion
+//#region src/tools/write.d.ts
+type WriteTool = typeof writeTool;
+type WriteToolMeta = FileMeta & {
+  /** File content before the write. Undefined for new files. The
+   *  post-write content is recoverable from the original call's
+   *  `params.content`, so we don't redundantly stash it on meta. */
+  original?: string;
+};
+/**
+ * Write a file to disk. Overwrites if the file exists; creates parent
+ * directories as needed.
+ *
+ * Content is written *verbatim* in everything but line endings. The
+ * model always emits LF; this tool detects the existing file's
+ * line-ending style (or the platform default for new files via
+ * `detectEol`) and re-applies it on write so a CRLF file stays CRLF
+ * after an LF-from-the-model overwrite. No trailing-newline injection,
+ * no whitespace stripping.
+ *
+ * Freshness: when the target file already exists, the model must have
+ * read it in this session and the on-disk mtime must be unchanged
+ * since that read. Otherwise the tool refuses with `FILE_NOT_FRESH` —
+ * "read this file before overwriting it." New files (path doesn't
+ * exist) bypass this check; nothing to be fresh against.
+ *
+ * Returns a small acknowledgement (`{ ok, bytes, lines }`) rather than
+ * echoing the content back — the model already has it. `bytes` reflects
+ * the on-disk byte count, including any extra bytes from CRLF expansion.
+ */
+declare const writeTool: import("@zaly/ai").Tool<{
+  path: string;
+  content: string;
+}, unknown, WriteToolMeta>;
+//#endregion
+//#region src/utils/uuid.d.ts
+/**
+ * RFC 9562 UUIDv7 — timestamp-prefixed (48-bit ms since epoch),
+ * monotonic within a millisecond via a 32-bit sequence counter,
+ * random tail otherwise. Sortable lexicographically by creation time,
+ * which is handy for debugging ("show me the latest few records by
+ * uuid") and for any future DB index.
+ *
+ * Hand-rolled to keep `@zaly/agent` dep-free. Same algorithm as the
+ * `uuid` package's v7 implementation, just without the buffer/offset
+ * ceremony — we only ever want the canonical string form.
+ */
+declare function uuidv7(): string;
+declare function isUuidv7(s: string): boolean;
+declare function isUuidv7Like(s: string): boolean;
+//#endregion
+//#region src/commands.d.ts
+type Command = {
+  name: string;
+  body: string;
+  path: string;
+  description?: string;
+  args: ArgsOpts;
+};
+interface CommandsOptions {
+  /** cmd.md paths, sorted from highest to lowest precedence. */
+  paths?: string[];
+  logger?: Logger;
+  /** Bash execution of commands:
+   * - `true`: Use the system default bash shell.
+   * - `false`: Disable bash execution.
+   * - `string[]`: Use a custom bash shell with the provided arguments. */
+  bash?: boolean | string[];
+  /** When `false`, template expressions are disabled and only simple variable interpolation is allowed. */
+  expr?: boolean;
+}
+declare class Commands {
+  #private;
+  readonly catalog: Map<string, Command>;
+  constructor(opts?: CommandsOptions);
+  load(): Promise<this>;
+  add(path: string): Promise<void>;
+  get(name: string): Command | undefined;
+  format(input: string | ArgsResult, cmd: Command): Promise<string>;
+}
+//#endregion
+//#region src/context/tokens.d.ts
+type TokenCount = {
+  type: AnyType | Message["role"] | "prompt" | "tool-schema" | "system-prompt";
+  kind?: string;
+  tokens: number;
+  children?: TokenCount[];
+};
+type TokenStats = {
+  key: string;
+  tokens: number;
+  count: number;
+  children?: Map<string, TokenStats>;
+};
+declare function estimatePart(p: AnyPart): TokenCount;
+declare function tokenStats(msgs: readonly Message[], opts?: {
+  prompt?: (string | Prompt<string>)[];
+  tools?: Tool[];
+  expand?: (c: TokenCount) => boolean;
+}): TokenStats;
+declare function formatTokenStats(s: TokenStats, indent?: number): string;
+//#endregion
+export { type Agent, type AgentContext, type AgentContextEvents, type AgentEvents, type AgentInit, type AgentOptions, type AgentStatus, type AgentStop, type AgentStopKind, AnyPrompt, type AnyScope, AnyTool, type BashTool, BashUsage, BuiltinPrompt, type BuiltinScope, BuiltinTool, type CheckResult, Command, Commands, CommandsOptions, type ContextPressure, type DoneTaskInfo, type EditTool, type EditToolMeta, FileUsage, type FindTool, type FindToolMeta, type GrepTool, type GrepToolMeta, type PermissionContext, type PermissionHandler, type PermissionManager, type PermissionOptions, type PermissionPreset, type PermissionPresetName, type PermissionRequest, type PermissionScope, type PermissionScopes, Prompt, type PromptCollection, PromptCtx, PromptLoader, type ReadTool, type ReadToolMeta, type Rule, type SendMode, SkillEntry, SkillMeta, SkillTool, Skills, SkillsOptions, type StepKind, type StepResult, type StopOptions, type StopPolicy, type Suggestion, type TaskInfo, type TaskMeta, type TaskStatus, type Tasks, type TasksEvents, TokenCount, TokenStats, type TokenUsage, type ToolCollection, ToolInit, ToolLoader, ToolStat, ToolStatOptions, type TurnResult, type Verdict, type WriteTool, type WriteToolMeta, type addUsage, createAgent, type createAgentContext, estimatePart, extractBashUsage, extractConversation, extractFileUsage, formatBashUsage, formatFileUsage, formatTokenStats, handlerRegistry, isUuidv7, isUuidv7Like, messageTail, promptCollection, promptRegistry, type taskCompletionMessage, type taskInfoPart, tokenStats, toolCollection, toolRegistry, uuidv7 };
+//# sourceMappingURL=index.d.mts.map