@zaly/agent 0.0.3

package/dist/agent-GDLdDc2w.mjs

@@ -0,0 +1,902 @@
+import { r as uuidv7 } from "./uuid-ByXP5SO5.mjs";
+import { n as taskCompletionMessage, r as taskInfoPart, t as Tasks } from "./tasks-WmC270X2.mjs";
+import { Emitter, safeStringify, toError, toValue } from "@zaly/shared";
+import { AiError, isContextOverflow, runTool } from "@zaly/ai";
+//#region src/utils/usage.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." */
+function addUsage(a, b) {
+	const out = {
+		input: a.input + b.input,
+		output: a.output + b.output
+	};
+	if (a.cacheRead !== void 0 || b.cacheRead !== void 0) out.cacheRead = (a.cacheRead ?? 0) + (b.cacheRead ?? 0);
+	if (a.cacheWrite !== void 0 || b.cacheWrite !== void 0) out.cacheWrite = (a.cacheWrite ?? 0) + (b.cacheWrite ?? 0);
+	if (a.reasoning !== void 0 || b.reasoning !== void 0) out.reasoning = (a.reasoning ?? 0) + (b.reasoning ?? 0);
+	if (a.cost || b.cost) out.cost = addUsage(a.cost ?? empty(), b.cost ?? empty());
+	return out;
+}
+var TokenUsage = class {
+	#last = empty();
+	#total = empty();
+	constructor(messages) {
+		for (const m of messages ?? []) if (m.role === "assistant" && m.meta?.usage) this.add(m.meta.usage);
+	}
+	get cost() {
+		return this.total.cost ?? empty();
+	}
+	get input() {
+		return this.last.input;
+	}
+	get output() {
+		return this.last.output;
+	}
+	get cacheRead() {
+		return this.last.cacheRead ?? 0;
+	}
+	get cacheWrite() {
+		return this.last.cacheWrite ?? 0;
+	}
+	get reasoning() {
+		return this.last.reasoning ?? 0;
+	}
+	add(count) {
+		this.#last = count;
+		this.#total = addUsage(this.#total, count);
+	}
+	resetLast() {
+		this.#last = empty();
+	}
+	get last() {
+		return this.#last;
+	}
+	get total() {
+		return this.#total;
+	}
+	get contextSize() {
+		return this.last.input + this.last.output + (this.last.cacheRead ?? 0) + (this.last.cacheWrite ?? 0);
+	}
+};
+function empty() {
+	return {
+		input: 0,
+		output: 0
+	};
+}
+//#endregion
+//#region src/stop.ts
+/**
+* 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.
+*/
+var StopPolicy = class {
+	#opts;
+	#steps = 0;
+	#consecutiveErrors = 0;
+	#calls = [];
+	#usage = {
+		input: 0,
+		output: 0
+	};
+	#totalUsage = {
+		input: 0,
+		output: 0
+	};
+	constructor(opts = {}) {
+		this.#opts = opts;
+	}
+	/** Token usage from the most recent step's response. */
+	get usage() {
+		return this.#usage;
+	}
+	/** Cumulative token usage across every step in the current run. */
+	get totalUsage() {
+		return this.#totalUsage;
+	}
+	get steps() {
+		return this.#steps;
+	}
+	get consecutiveErrors() {
+		return this.#consecutiveErrors;
+	}
+	/** Tool-call history fed to the loop detector. Read-only. */
+	get calls() {
+		return this.#calls;
+	}
+	/** 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.onAny((event) => this.handle(event));
+	}
+	/** Feed a single event into the policy. Public so custom drivers
+	*  can drive it without going through `attach`. */
+	handle(event) {
+		switch (event.type) {
+			case "step-end":
+				this.#steps++;
+				break;
+			case "tool-call":
+				this.#calls.push(event.call);
+				break;
+			case "tool-result":
+				this.#consecutiveErrors = event.result.isError ? this.#consecutiveErrors + 1 : 0;
+				break;
+			case "stream-event":
+				if (event.event.type === "finish") {
+					this.#usage = event.event.usage;
+					this.#totalUsage = addUsage(this.#totalUsage, event.event.usage);
+				}
+				break;
+		}
+	}
+	/** 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 = {}) {
+		this.#steps = 0;
+		this.#consecutiveErrors = 0;
+		this.#calls = [];
+		if (opts.keepUsage === false) {
+			this.#usage = {
+				input: 0,
+				output: 0
+			};
+			this.#totalUsage = {
+				input: 0,
+				output: 0
+			};
+		}
+	}
+	/** 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() {
+		if (this.#opts.maxSteps !== void 0 && this.#steps >= this.#opts.maxSteps) return "max-steps";
+		if (this.#detectLoop()) return "loop-detected";
+		if (this.#opts.maxToolErrors !== void 0 && this.#consecutiveErrors >= this.#opts.maxToolErrors) return "max-tool-errors";
+		if (this.#opts.tokenBudget !== void 0 && this.#totalUsage.input + this.#totalUsage.output > this.#opts.tokenBudget) return "token-budget";
+	}
+	#detectLoop() {
+		const calls = this.#calls;
+		if (calls.length === 0) return false;
+		const consecutive = this.#opts.loopConsecutive ?? 3;
+		if (Number.isFinite(consecutive) && calls.length >= consecutive) {
+			const last = hashCall(calls[calls.length - 1]);
+			let run = 1;
+			for (let i = calls.length - 2; i >= 0 && run < consecutive; i--) if (hashCall(calls[i]) === last) run++;
+			else break;
+			if (run >= consecutive) return true;
+		}
+		const window = this.#opts.loopWindow ?? 10;
+		const windowRepeats = this.#opts.loopWindowRepeats ?? 4;
+		if (Number.isFinite(windowRepeats) && calls.length >= windowRepeats) {
+			const slice = calls.slice(Math.max(0, calls.length - window));
+			const counts = /* @__PURE__ */ new Map();
+			for (const call of slice) {
+				const h = hashCall(call);
+				const next = (counts.get(h) ?? 0) + 1;
+				if (next >= windowRepeats) return true;
+				counts.set(h, next);
+			}
+		}
+		return false;
+	}
+};
+function hashCall(call) {
+	return `${call.name}\0${safeStringify(call.params)}`;
+}
+//#endregion
+//#region src/agent.ts
+const PRESSURE_LEVELS = [
+	.75,
+	.85,
+	.95
+];
+/**
+* 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.
+*/
+var Agent = class extends Emitter {
+	#opts;
+	#ctx;
+	#stopPolicy;
+	#tasks;
+	/** Nesting depth — see `AgentOptions.depth`. Read-only; subagents pass
+	*  `parent.depth + 1` when constructing their child. */
+	depth;
+	/** Cap on `depth` — see `AgentOptions.maxDepth`. */
+	maxDepth;
+	#started = false;
+	#parent;
+	#injectQueue = [];
+	#appendQueue = [];
+	#notifyQueue = [];
+	#status = "idle";
+	#abortController;
+	#pauseRequested;
+	#running;
+	#usage;
+	/** Pending future-injects scheduled via `scheduleWakeup`. Cleared
+	*  whenever the loop becomes active for any reason — the scheduled
+	*  inject was a fallback "wake me up at time T if nothing else does,"
+	*  and once something else has, the timer is moot. Hints from cancelled
+	*  wakeups carry over as a system message so the intent doesn't
+	*  evaporate. */
+	#wakeups = /* @__PURE__ */ new Map();
+	#lastStop;
+	/** 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) {
+		super();
+		const opts = ctx.opts;
+		this.#ctx = ctx;
+		this.#opts = ctx.opts;
+		this.depth = opts.depth ?? 0;
+		this.maxDepth = opts.maxDepth ?? 2;
+		this.#tasks = new Tasks();
+		this.#tasks.$tools = async () => this.tools;
+		this.#tasks.heartbeatMs = opts.heartbeatMs;
+		this.#tasks.onEmitError = (error) => opts.logger?.child("tasks").error(error);
+		this.#tasks.on("task-done", ({ task }) => {
+			this.send(taskCompletionMessage(task));
+		});
+		this.#tasks.on("heartbeat", ({ running }) => {
+			this.send({
+				content: [{
+					content: [taskInfoPart(running)],
+					tag: "heartbeat",
+					type: "meta"
+				}],
+				role: "system"
+			});
+		});
+		this.#stopPolicy = new StopPolicy(opts.stop);
+		this.#stopPolicy.attach(this);
+		this.onEmitError = (error) => opts.logger?.child("events").error(error);
+		this.#ctx.attach(this);
+		this.#usage = new TokenUsage(this.messages);
+		this.#ctx.on("session", () => this.reset());
+	}
+	async reset() {
+		this.stop({
+			abort: true,
+			reason: "reset"
+		});
+		await this.waitIdle();
+		await this.#tasks.killAll();
+		this.#cancelAllWakeups();
+		this.#usage = new TokenUsage(this.messages);
+		this.#stopPolicy.reset({ keepUsage: false });
+		this.#injectQueue = [];
+		this.#appendQueue = [];
+		this.#notifyQueue = [];
+		this.#wakeups.clear();
+		this.#stop("natural");
+	}
+	/** 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. */
+	async child(overrides = {}) {
+		const childDepth = overrides.depth ?? this.depth + 1;
+		let tools = [...this.tools].filter((t) => t.name !== "skill");
+		if (childDepth >= this.maxDepth) tools = tools.filter((t) => t.name !== "subagent");
+		const { createAgent } = await import("./index.mjs").then((n) => n.t);
+		const ret = await createAgent({
+			cwd: this.cwd,
+			depth: childDepth,
+			mask: this.#opts.mask,
+			maxDepth: this.maxDepth,
+			model: this.model,
+			notify: this.#opts.notify,
+			permissions: await this.ctx.permissions(),
+			skills: this.#ctx.skills,
+			swarm: await this.#ctx.swarm(),
+			tools,
+			...overrides
+		});
+		ret.#parent = this;
+		await ret.start();
+		return ret;
+	}
+	/** Active conversation — delegates to the underlying `Session`. */
+	get messages() {
+		return this.session.messages;
+	}
+	get status() {
+		return this.#status;
+	}
+	get cwd() {
+		return this.#ctx.cwd;
+	}
+	get model() {
+		return this.#ctx.model;
+	}
+	get session() {
+		return this.#ctx.session;
+	}
+	get signal() {
+		return this.#abortController?.signal;
+	}
+	/** Token usage from the most recent step's response. Drives
+	*  `contextSize` and any "this turn used N tokens" UI. */
+	get usage() {
+		return this.#usage;
+	}
+	/** Cumulative token usage across every step in the current run.
+	*  Useful for billing-style displays. */
+	get totalUsage() {
+		return this.#usage.total;
+	}
+	/** 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() {
+		return this.#usage.contextSize;
+	}
+	get pressure() {
+		const used = this.contextSize;
+		const limit = this.model?.spec.contextSize ?? 0;
+		const ratio = limit > 0 ? used / limit : 0;
+		return {
+			level: PRESSURE_LEVELS.findLast((t) => ratio >= t) ?? 0,
+			limit,
+			ratio,
+			used
+		};
+	}
+	get lastStop() {
+		return this.#lastStop;
+	}
+	get steps() {
+		return this.#stopPolicy.steps;
+	}
+	get parent() {
+		return this.#parent;
+	}
+	get tools() {
+		return this.#ctx.tools;
+	}
+	get prompt() {
+		return this.#ctx.prompt;
+	}
+	get ctx() {
+		return this.#ctx;
+	}
+	/** 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() {
+		return this.#tasks;
+	}
+	#enqueue(message, opts = {}) {
+		const messages = Array.isArray(message) ? message : [message];
+		if (!messages.length) return;
+		for (const m of messages) m.id ??= uuidv7();
+		(opts.mode === "append" ? this.#appendQueue : this.#injectQueue).push(...messages);
+		this.emit("pending", { messages });
+	}
+	/** 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, opts = {}) {
+		this.#enqueue(message ?? [], opts);
+		if (opts.run === false) return;
+		if (this.#status === "idle" || this.#status === "paused") this.run();
+	}
+	async useTool(name, params, msg, opts = {}) {
+		const tool = this.tools.find((t) => t.name === name);
+		if (!tool) throw new Error(`cannot inject tool use: no tool named "${name}"`);
+		const id = uuidv7();
+		const call = {
+			id,
+			name,
+			params,
+			type: "tool-call"
+		};
+		const result = await runTool(tool, params, await this.#toolContext(), { preflight: false });
+		const messages = [
+			{
+				content: [{
+					content: msg,
+					data: { tool: name },
+					tag: "user-tool-use",
+					type: "meta"
+				}],
+				role: "system"
+			},
+			{
+				content: [call],
+				role: "assistant"
+			},
+			{
+				content: [{
+					content: result.content,
+					error: result.error,
+					id,
+					isError: result.isError,
+					meta: result.meta,
+					name,
+					type: "tool-result"
+				}],
+				role: "tool"
+			}
+		];
+		if (opts.hidden) for (const m of messages) m.hidden = true;
+		return {
+			call,
+			messages,
+			result
+		};
+	}
+	notify(type, data) {
+		const meta = typeof data === "string" || Array.isArray(data) ? {
+			content: data,
+			tag: type,
+			type: "meta"
+		} : {
+			data,
+			tag: type,
+			type: "meta"
+		};
+		this.#notifyQueue.push(meta);
+	}
+	/** 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) {
+		const id = uuidv7();
+		const timer = setTimeout(() => {
+			this.#wakeups.delete(id);
+			this.send({
+				content: [{
+					data: {
+						hint: opts.hint,
+						id
+					},
+					tag: "wakeup",
+					type: "meta"
+				}],
+				role: "system"
+			});
+		}, opts.delayMs);
+		timer.unref();
+		this.#wakeups.set(id, {
+			hint: opts.hint,
+			timer
+		});
+		return id;
+	}
+	/** Cancel all pending wakeups, surfacing their hints as a single
+	*  system message so the model can see what was queued. Called from
+	*  `#setStatus` whenever the agent transitions to `streaming` — that's
+	*  the unambiguous "loop is active" signal. */
+	#cancelAllWakeups() {
+		if (this.#wakeups.size === 0) return;
+		const carried = [];
+		for (const [id, { hint, timer }] of this.#wakeups) {
+			clearTimeout(timer);
+			if (hint) carried.push({
+				hint,
+				id
+			});
+		}
+		this.#wakeups.clear();
+		if (carried.length > 0) {
+			const parts = carried.map((c) => ({
+				data: {
+					hint: c.hint,
+					id: c.id,
+					status: "cancelled"
+				},
+				tag: "wakeup",
+				type: "meta"
+			}));
+			this.#injectQueue.push({
+				content: parts,
+				role: "system"
+			});
+		}
+	}
+	/** 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() {
+		if (this.#running) return this.#running;
+		this.#pauseRequested = void 0;
+		this.#abortController = void 0;
+		this.#running = this.#loop().catch((error) => {
+			this.#opts.logger?.child("run").error(error);
+			return this.#stop(error instanceof Error && error.name === "AbortError" ? "aborted" : "error", error);
+		}).finally(() => {
+			this.#abortController = void 0;
+			this.#running = void 0;
+		});
+		return this.#running;
+	}
+	async #collect() {
+		this.#abortController = new AbortController();
+		const context = {
+			messages: [...this.ctx.messages],
+			prompt: this.prompt,
+			tools: this.tools
+		};
+		await this.emitSerial("context", context);
+		const model = this.model;
+		if (!model) throw new Error("model must be loaded to collect");
+		return model.stream(context, this.#streamOpts());
+	}
+	#shouldAutoCompact() {
+		const opts = toValue(this.#opts.compaction);
+		if (!(opts?.enabled ?? true)) return false;
+		const threshold = opts?.threshold ?? .95;
+		return this.pressure.ratio >= threshold;
+	}
+	#streamOpts() {
+		const base = this.#opts.request ?? {};
+		return {
+			...base,
+			onEvent: (event) => {
+				this.emit("stream-event", { event });
+				try {
+					this.#opts.onEvent?.(event);
+				} catch (error) {
+					this.#opts.logger?.child("stream").error(error);
+				}
+			},
+			onUpdate: this.#opts.onUpdate,
+			reasoning: {
+				...base.reasoning,
+				effort: this.#ctx.reasoning
+			},
+			signal: this.#abortController?.signal
+		};
+	}
+	/** Run exactly one step. Useful for tests and custom drivers
+	*  that want to interleave logic between steps. */
+	async step() {
+		if (this.#shouldAutoCompact()) await this.compact();
+		if (this.#notifyQueue.length > 0) this.#injectQueue.push({
+			content: this.#notifyQueue.splice(0),
+			role: "system"
+		});
+		for (const m of this.#injectQueue.splice(0)) await this.session.add(m);
+		for (const m of this.#appendQueue.splice(0)) await this.session.add(m);
+		this.#setStatus("streaming");
+		let collected;
+		try {
+			collected = await this.#collect();
+		} catch (error) {
+			const err = toError(error);
+			const overflow = isContextOverflow({ message: err.message });
+			if (overflow) this.#opts.logger?.warn("Context overflow detected:", err);
+			return {
+				error: err,
+				finishReason: overflow ? "length" : "error",
+				kind: overflow ? "context-overflow" : "error",
+				usage: {
+					input: 0,
+					output: 0
+				}
+			};
+		}
+		this.#usage.add(collected.meta.usage);
+		const result = {
+			finishReason: collected.meta.finishReason,
+			message: collected,
+			usage: collected.meta.usage
+		};
+		if (this.#opts.contextLimit !== void 0 && isContextOverflow({
+			contextLimit: this.#opts.contextLimit,
+			usageInput: result.usage.input + (result.usage.cacheRead ?? 0) + (result.usage.cacheWrite ?? 0)
+		})) return {
+			kind: "context-overflow",
+			...result
+		};
+		const calls = await this.#parseToolCalls(collected);
+		await this.session.add(collected);
+		if (calls.length === 0) return {
+			kind: "natural",
+			...result
+		};
+		return {
+			kind: "tool-calls",
+			toolMessage: await this.#runTools(calls),
+			...result
+		};
+	}
+	async #parseToolCalls(message) {
+		if (typeof message.content === "string") return [];
+		const calls = message.content.filter((p) => p.type === "tool-call");
+		for (const call of calls) {
+			const tool = this.tools.find((t) => t.name === call.name);
+			if (!tool) continue;
+			try {
+				call.params = await tool.validator.cleanParams(call.params) ?? call.params;
+			} catch {}
+		}
+		return calls;
+	}
+	async compact() {
+		const prev = this.#status;
+		const pressure = this.pressure;
+		this.#setStatus("compacting");
+		this.#usage.resetLast();
+		try {
+			const { Compaction } = await import("./compactions-3AjPqjeZ.mjs");
+			const opts = {
+				...toValue(this.#opts.compaction),
+				signal: this.#abortController?.signal
+			};
+			await new Compaction(this, opts).compact(pressure);
+		} finally {
+			this.#setStatus(prev);
+		}
+	}
+	async #runTools(calls) {
+		this.#setStatus("running-tools");
+		this.emit("tool-calls", { calls });
+		for (const call of calls) this.emit("tool-call", { call });
+		const emitted = /* @__PURE__ */ new Set();
+		const resultParts = await this.#tasks.run(calls, await this.#toolContext(), { onResult: (call, result) => {
+			emitted.add(call.id);
+			this.emit("tool-result", {
+				call,
+				result
+			});
+		} });
+		for (let i = 0; i < calls.length; i++) {
+			const call = calls[i];
+			const part = resultParts[i];
+			if (emitted.has(call.id)) continue;
+			this.emit("tool-result", {
+				call,
+				result: {
+					content: part.content,
+					error: part.error,
+					isError: part.isError ?? false,
+					meta: part.meta
+				}
+			});
+		}
+		const message = {
+			content: resultParts,
+			role: "tool"
+		};
+		await this.session.add(message);
+		return message;
+	}
+	/** 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." */
+	async waitIdle(timeout) {
+		if (!this.#running) return this.#status;
+		const wait = [this.#running.catch(() => void 0)];
+		if (timeout !== void 0) wait.push(new Promise((resolve) => setTimeout(resolve, timeout)));
+		await Promise.race(wait);
+		return this.#status;
+	}
+	/** 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 = {}) {
+		this.#pauseRequested ??= opts.reason ?? "stop";
+		if (opts.abort ?? true) this.#abortController?.abort(opts.reason);
+	}
+	async start() {
+		if (this.#started) return;
+		this.#started = true;
+		await this.emit("start");
+	}
+	get started() {
+		return this.#started;
+	}
+	async #turn() {
+		for (let step = 1;; step++) {
+			if (this.#abortController?.signal.aborted) return {
+				kind: "aborted",
+				reason: this.#abortController.signal.reason
+			};
+			if (this.#pauseRequested !== void 0) return {
+				kind: "paused",
+				reason: this.#pauseRequested
+			};
+			this.emit("step-start", { step });
+			const outcome = await this.step();
+			this.emit("step-end", {
+				outcome: outcome.kind,
+				step
+			});
+			if (outcome.kind === "error") return {
+				kind: outcome.error?.name === "AbortError" ? "aborted" : "error",
+				reason: outcome.error
+			};
+			if (outcome.kind === "natural") return { kind: "natural" };
+			if (outcome.kind === "context-overflow") {
+				if (toValue(this.#opts.compaction)?.enabled === false) return { kind: "context-overflow" };
+				this.#opts.logger?.child("compaction").warn(`context overflow detected (size ${this.contextSize}, limit ${this.pressure.limit}); running compaction`);
+				await this.compact();
+				continue;
+			}
+			const stop = this.#stopPolicy.detect();
+			if (stop) return { kind: stop };
+		}
+	}
+	async #loop() {
+		if (!this.#started) await this.start();
+		this.#stopPolicy.reset();
+		for (let turn = 1;; turn++) {
+			this.emit("turn-start", { turn });
+			const result = await this.#turn();
+			const reason = result.reason ? toError(result.reason).message : void 0;
+			this.emit("turn-end", {
+				outcome: result.kind,
+				reason,
+				turn
+			});
+			if (result.kind === "natural") {
+				if (this.#appendQueue.length > 0) {
+					for (const m of this.#appendQueue.splice(0)) await this.session.add(m);
+					continue;
+				}
+				if (this.#injectQueue.length > 0) continue;
+			}
+			return this.#stop(result.kind, result.reason);
+		}
+	}
+	#stop(kind, reason) {
+		this.#lastStop = {
+			error: reason instanceof Error ? reason : void 0,
+			kind,
+			reason: reason === void 0 ? void 0 : toError(reason).message
+		};
+		this.#setStatus(kind === "natural" ? "idle" : "paused");
+		this.emit("stop", {
+			status: this.#status,
+			usage: this.usage,
+			...this.#lastStop
+		});
+		return kind;
+	}
+	/** Build the per-step `ToolContext` handed to each tool. The session
+	*  cwd, an abort signal scoped to the in-flight stream, and the
+	*  long-running spawn registry are all surfaced here. */
+	async #toolContext() {
+		const masker = await this.#ctx.masker();
+		return {
+			agent: this,
+			bash: this.#opts.bash,
+			cwd: this.cwd,
+			isMasked: (msgId, partIdx) => masker?.isMasked(msgId, partIdx) ?? false,
+			messages: this.session.messages,
+			need: (scope, input) => this.#need(scope, input),
+			perms: await this.ctx.permissions(),
+			sessionDir: this.session.dir,
+			signal: this.#abortController?.signal,
+			swarm: () => this.#ctx.swarm(),
+			tasks: this.#tasks
+		};
+	}
+	/** Implementation of `ctx.need(scope, input)`. Resolves on `allow`,
+	*  throws a `PERMISSION_DENIED` `AiError` on `deny`, and escalates
+	*  `ask` to `AgentOptions.allow` (treating it as `deny` when no
+	*  callback is configured). */
+	async #need(scope, input) {
+		const r = (await this.ctx.permissions()).validate(scope, input);
+		if (r.verdict === "allow") return;
+		if (r.verdict === "ask" && this.#opts.allow) {
+			if (await this.#opts.allow({
+				ask: r.ask,
+				input,
+				reason: r.reason,
+				scope,
+				suggestions: r.suggestions
+			})) return;
+		}
+		throw new AiError({
+			code: "PERMISSION_DENIED",
+			data: {
+				input,
+				scope,
+				suggestions: r.suggestions,
+				verdict: r.verdict
+			},
+			message: r.reason,
+			retryable: r.verdict === "ask"
+		});
+	}
+	/** 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. */
+	async dispose() {
+		this.clearListeners();
+		this.#cancelAllWakeups();
+		await this.#tasks.killAll();
+	}
+	#setStatus(status) {
+		const prev = this.#status;
+		if (prev === status) return;
+		if (status === "streaming" && (prev === "idle" || prev === "paused")) this.#cancelAllWakeups();
+		this.#status = status;
+		this.emit("status", { status });
+	}
+};
+//#endregion
+export { Agent };
+
+//# sourceMappingURL=agent-GDLdDc2w.mjs.map