@zaly/agent 0.0.3

package/dist/tasks-WmC270X2.mjs

@@ -0,0 +1,615 @@
+import { r as uuidv7 } from "./uuid-ByXP5SO5.mjs";
+import { Emitter, safeStringify } from "@zaly/shared";
+import { AiError, isStreamable, runTool, stringifyContent, toErrorResult } from "@zaly/ai";
+//#region src/tasks.ts
+const DEFAULT_GRACE_MS = 1e4;
+/**
+* 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.
+*/
+var Tasks = class extends Emitter {
+	#map = /* @__PURE__ */ new Map();
+	graceMs = DEFAULT_GRACE_MS;
+	#tools = [];
+	/** Heartbeat interval in ms. When set, fires `heartbeat` events while
+	*  at least one task is pending or running. Self-managing: starts on
+	*  the first active task, stops when the last one finishes. Set to
+	*  `undefined` to disable. */
+	#heartbeatMs;
+	#heartbeatTimer;
+	get heartbeatMs() {
+		return this.#heartbeatMs;
+	}
+	set heartbeatMs(value) {
+		this.#heartbeatMs = value;
+		this.#syncHeartbeat();
+	}
+	/** Snapshot of every active task (pending or running). */
+	running() {
+		return [...this.#map.values()].filter((t) => t.status !== "done").map((t) => toTaskInfo(t));
+	}
+	/** Snapshot of every task that has completed. Drops are by `remove()`
+	*  or implicit retention; this list grows unless the caller prunes. */
+	finished() {
+		return [...this.#map.values()].filter((t) => t.status === "done").map((t) => toTaskInfo(t));
+	}
+	/** Look up a task by id. Useful for `task_stop` / `task_poll`. */
+	get(id) {
+		const t = this.#map.get(id);
+		return t ? toTaskInfo(t) : void 0;
+	}
+	/** Snapshot of every task in the registry — running, pending, and done. */
+	info() {
+		return [...this.#map.values()].map(toTaskInfo);
+	}
+	async tools() {
+		return typeof this.#tools === "function" ? this.#tools() : this.#tools;
+	}
+	set $tools(tools) {
+		this.#tools = tools;
+	}
+	/** 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) {
+		const t = this.#map.get(id);
+		if (t?.status !== "running" || !t.streamable) return false;
+		return t.streamable.hasNew?.() ?? false;
+	}
+	/** 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) {
+		const t = this.#map.get(id);
+		if (!t) throw new AiError({
+			code: "NOT_FOUND",
+			data: { id },
+			message: `no task with id "${id}"`
+		});
+		if (t.status === "done") throw new AiError({
+			code: "TASK_DONE",
+			data: { id },
+			message: `task "${id}" has already completed; its result was injected as a system message`
+		});
+		if (!t.streamable) throw new AiError({
+			code: "NOT_STREAMABLE",
+			data: { id },
+			message: `task "${id}" has no incremental output — it's a plain-Promise tool whose result is delivered all-at-once when complete`
+		});
+		return t.streamable.poll();
+	}
+	/** Drop a task from the registry — does not abort. Caller is
+	*  responsible for `abort()`-ing if the task is still running. */
+	remove(id) {
+		const task = this.#map.get(id);
+		if (!task) return false;
+		this.#map.delete(id);
+		this.emit("task-removed", { task: toTaskInfo(task) });
+		return true;
+	}
+	/** 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, result) {
+		const task = this.#map.get(id);
+		if (!task || task.status === "done") return;
+		task.status = "done";
+		task.result = result;
+		task.finishedAt = Date.now();
+		task.resolveDone();
+		if (!task.ownerRound) this.emit("task-done", { task: toTaskInfo(task) });
+		this.#startReadyDependents(id, result);
+		this.#syncHeartbeat();
+	}
+	/** Abort a running task. Calls the streamable's `abort()` if present;
+	*  pending tasks transition straight to `done` with a cancelled
+	*  result. Idempotent. */
+	abort(id, reason = "aborted by request") {
+		const task = this.#map.get(id);
+		if (!task || task.status === "done") return;
+		if (task.streamable) task.streamable.abort();
+		if (task.status === "pending") this.done(id, toErrorResult(new AiError({
+			code: "TASK_ABORTED",
+			message: reason
+		})));
+	}
+	/** 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`. */
+	async killAll() {
+		const active = [...this.#map.values()].filter((t) => t.status !== "done");
+		for (const t of active) {
+			if (t.streamable) t.streamable.abort();
+			if (t.status === "pending") this.done(t.id, toErrorResult(new AiError({
+				code: "TASK_ABORTED",
+				message: "agent disposed"
+			})));
+		}
+		await Promise.all(active.map((t) => t.donePromise.catch(() => void 0)));
+		this.#syncHeartbeat();
+	}
+	/** Start or stop the heartbeat timer based on whether any task is
+	*  active and whether `heartbeatMs` is configured. Idempotent — called
+	*  after every state transition (`add` / `done` / `killAll`). The
+	*  timer is `unref`'d so it never holds the process open. */
+	#syncHeartbeat() {
+		const want = [...this.#map.values()].some((t) => t.status !== "done") && this.#heartbeatMs !== void 0;
+		if (want && !this.#heartbeatTimer) {
+			this.#heartbeatTimer = setInterval(() => {
+				this.emit("heartbeat", { running: this.info().filter((t) => t.status !== "done") });
+			}, this.#heartbeatMs);
+			this.#heartbeatTimer.unref();
+		} else if (!want && this.#heartbeatTimer) {
+			clearInterval(this.#heartbeatTimer);
+			this.#heartbeatTimer = void 0;
+		}
+	}
+	/**
+	* 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.
+	*/
+	async run(calls, ctx, opts = {}) {
+		const round = Symbol("round");
+		const tasks = [];
+		let chainHead;
+		const tools = await this.tools();
+		for (const call of calls) {
+			const tool = tools.find((t) => t.name === call.name);
+			if (!tool) {
+				tasks.push(this.#startSyncResult(call, unknownToolResult(call.name), round));
+				continue;
+			}
+			const parallel = tool.parallel ?? false;
+			if (chainHead && !parallel) {
+				tasks.push(this.#registerPending({
+					call,
+					ctxBase: ctx,
+					round,
+					tool,
+					waitingFor: chainHead
+				}));
+				chainHead = tasks[tasks.length - 1].id;
+				continue;
+			}
+			if (this.#needsPreflight(tool, ctx)) {
+				const preflight = await this.#preflight(tool, call, ctx);
+				if (preflight) {
+					tasks.push(this.#startSyncResult(call, preflight, round));
+					continue;
+				}
+			}
+			const task = this.#start({
+				call,
+				ctxBase: ctx,
+				round,
+				tool
+			});
+			tasks.push(task);
+			if (task.status === "running" && !parallel) chainHead = task.id;
+		}
+		const parts = [];
+		const resultPart = (idx) => {
+			if (parts[idx]) return parts[idx];
+			const task = tasks[idx];
+			if (task.status !== "done") task.ownerRound = void 0;
+			const call = calls[idx];
+			const part = this.#buildPart(call, task);
+			parts[idx] = part;
+			return part;
+		};
+		let onResult = opts.onResult;
+		const allDone = Promise.all(tasks.map(async (t, ti) => {
+			await t.donePromise;
+			onResult?.(calls[ti], resultPart(ti), ti);
+		}));
+		const grace = sleep(this.graceMs);
+		const aborted = ctx.signal ? new Promise((resolve) => {
+			if (ctx.signal.aborted) resolve();
+			else ctx.signal.addEventListener("abort", () => resolve(), { once: true });
+		}) : new Promise(() => void 0);
+		await Promise.race([
+			allDone,
+			grace,
+			aborted
+		]);
+		onResult = void 0;
+		return tasks.map((_, i) => resultPart(i));
+	}
+	/** Build a "done" task synchronously from a precomputed result.
+	*  Used for unknown-tool errors and validation failures. */
+	#startSyncResult(call, result, round) {
+		const task = this.#allocate({
+			id: uuidv7(),
+			type: call.name,
+			desc: call.name,
+			round
+		});
+		task.status = "done";
+		task.result = result;
+		task.finishedAt = task.startedAt;
+		task.resolveDone();
+		return task;
+	}
+	/** Allocate an internal task record, register it, and emit `task-added`. */
+	#allocate(opts) {
+		let resolveDone;
+		const donePromise = new Promise((r) => {
+			resolveDone = r;
+		});
+		const task = {
+			desc: opts.desc,
+			donePromise,
+			id: opts.id,
+			ownerRound: opts.round,
+			resolveDone,
+			startedAt: Date.now(),
+			status: "pending",
+			type: opts.type,
+			waitingFor: opts.waitingFor
+		};
+		this.#map.set(task.id, task);
+		this.emit("task-added", { task: toTaskInfo(task) });
+		this.#syncHeartbeat();
+		return task;
+	}
+	/** Register a pending task (chained behind `dependsOn`). Does not
+	*  invoke the tool — that happens once the dependency completes. */
+	#registerPending(opts) {
+		const task = this.#allocate({
+			id: uuidv7(),
+			type: opts.tool.name,
+			desc: descOfCall(opts.call),
+			waitingFor: opts.waitingFor,
+			round: opts.round
+		});
+		task.pending = {
+			call: opts.call,
+			ctx: opts.ctxBase,
+			tool: opts.tool
+		};
+		return task;
+	}
+	/** Start a tool call. Allocates a task record, validates params,
+	*  invokes `tool.call`, detects `Streamable`, and wires completion
+	*  back to `done()`. Returns the task in its post-launch state
+	*  (`done` for sync failures or already-resolved sync calls,
+	*  `running` for everything else). */
+	#start(opts) {
+		const task = this.#allocate({
+			id: uuidv7(),
+			type: opts.tool.name,
+			desc: descOfCall(opts.call),
+			round: opts.round
+		});
+		this.#dispatch(task, opts.tool, opts.call, opts.ctxBase);
+		return task;
+	}
+	#needsPreflight(tool, ctx) {
+		return ctx.need !== void 0 || tool.preflight !== void 0;
+	}
+	/** Run schema validation and semantic/tool permission checks before a
+	*  public task is allocated. Returns a formatted tool error when the
+	*  call should short-circuit, otherwise undefined. */
+	async #preflight(tool, call, ctxBase) {
+		const ctx = {
+			...ctxBase,
+			tasks: this
+		};
+		let params;
+		try {
+			params = await tool.validator.validateParams(call.params);
+			await ctx.need?.("tool", tool.name);
+			await tool.preflight?.(params, ctx);
+		} catch (error) {
+			return toErrorResult(error);
+		}
+	}
+	/** Validate / call / wire up completion for an existing task record.
+	*  Used both for fresh tasks (`#start`) and pending-becoming-ready
+	*  (`#startReadyDependents`). The task's id and registry entry are
+	*  reused so identifiers stay stable across the pending → running
+	*  transition.
+	*
+	*  Delegates the validate/call/error machinery to `runTool` (in
+	*  streaming mode) so there's one source of truth. The task's status
+	*  is flipped to `running` synchronously — the round loop reads it
+	*  right after `#start` returns to decide chain heads, and we want
+	*  that read to see the post-launch state, not the allocation default.
+	*  Async resolution either keeps it `running` (streamable returned)
+	*  or transitions to `done` (sync result or error). */
+	#dispatch(task, tool, call, ctxBase) {
+		const ctx = {
+			...ctxBase,
+			tasks: this
+		};
+		task.status = "running";
+		runTool(tool, call.params, ctx, {
+			preflight: false,
+			streaming: true
+		}).then((settled) => {
+			if (isStreamable(settled)) {
+				task.streamable = settled;
+				settled.done.then(() => {
+					const snap = settled.poll();
+					this.done(task.id, {
+						content: snap.content,
+						error: snap.error,
+						isError: snap.isError,
+						meta: snap.meta
+					});
+				}, (error) => this.done(task.id, toErrorResult(error)));
+				return;
+			}
+			this.done(task.id, settled);
+		}, (error) => this.done(task.id, toErrorResult(error)));
+	}
+	/** Walk pending tasks; start any whose `dependsOn` just completed.
+	*  If the dependency failed, propagate cancellation: dependents land
+	*  in `done` with an `UPSTREAM_FAILED` result. */
+	#startReadyDependents(completedId, completedResult) {
+		for (const t of this.#map.values()) {
+			if (t.status !== "pending" || t.waitingFor !== completedId) continue;
+			if (completedResult.isError) {
+				this.done(t.id, toErrorResult(new AiError({
+					code: "UPSTREAM_FAILED",
+					data: { dependsOn: completedId },
+					message: `skipped: upstream task ${completedId} failed`
+				})));
+				continue;
+			}
+			this.#startPending(t);
+		}
+	}
+	async #startPending(task) {
+		const pending = task.pending;
+		if (!pending) return;
+		if (!this.#needsPreflight(pending.tool, pending.ctx)) {
+			task.pending = void 0;
+			task.waitingFor = void 0;
+			task.ownerRound = void 0;
+			this.#dispatch(task, pending.tool, pending.call, pending.ctx);
+			return;
+		}
+		const preflight = await this.#preflight(pending.tool, pending.call, pending.ctx);
+		if (preflight) {
+			this.done(task.id, preflight);
+			return;
+		}
+		task.pending = void 0;
+		task.waitingFor = void 0;
+		task.ownerRound = void 0;
+		this.#dispatch(task, pending.tool, pending.call, pending.ctx);
+	}
+	/** Build a `ToolResultPart` for a task at round-end. Done tasks pass
+	*  through their captured result; still-running tasks get a snapshot
+	*  from the streamable (if any) plus a placeholder note for the model. */
+	#buildPart(call, task) {
+		if (task.status === "done" && task.result) return {
+			content: task.result.content,
+			error: task.result.error,
+			id: call.id,
+			isError: task.result.isError,
+			meta: stampTaskMeta(task.result.meta, task),
+			name: call.name,
+			type: "tool-result"
+		};
+		if (task.status === "pending") return {
+			content: [{
+				data: toTaskInfo(task),
+				tag: "task",
+				type: "meta"
+			}],
+			id: call.id,
+			isError: false,
+			meta: stampTaskMeta(void 0, task),
+			name: call.name,
+			type: "tool-result"
+		};
+		const snap = task.streamable?.poll();
+		const baseContent = partialContentFrom(snap);
+		const trailer = {
+			content: "Task is still running. Partial output above. The final result will arrive as a system message when the task completes; you do not need to poll. Continue with other work or wait.",
+			data: { ...toTaskInfo(task) },
+			tag: "task",
+			type: "meta"
+		};
+		const parts = [];
+		if (typeof baseContent === "string") {
+			if (baseContent !== "") parts.push({
+				text: baseContent,
+				type: "text"
+			});
+		} else parts.push(...baseContent);
+		parts.push(trailer);
+		return {
+			content: parts,
+			id: call.id,
+			isError: false,
+			meta: stampTaskMeta(snap?.meta, task),
+			name: call.name,
+			type: "tool-result"
+		};
+	}
+};
+/** Stamp `meta.task` with the current task state. Preserves any
+*  tool-attached `meta` fields. Used both on done results (so the
+*  model can correlate completion to the original call) and on
+*  partial / pending placeholders. */
+function stampTaskMeta(base, task) {
+	return {
+		...base,
+		task: {
+			dependsOn: task.waitingFor,
+			desc: task.desc,
+			durationMs: task.finishedAt ? task.finishedAt - task.startedAt : void 0,
+			id: task.id,
+			status: task.status,
+			type: task.type
+		}
+	};
+}
+/** Build the "running" placeholder content from a streamable snapshot.
+*  Empty string when there's nothing yet to show; copies the parts
+*  array so downstream mutation of the result message can't reach back
+*  into the streamable's accumulator. */
+function partialContentFrom(snap) {
+	if (!snap) return "";
+	if (typeof snap.content === "string") return snap.content;
+	return [...snap.content];
+}
+/** Best-effort human-readable label for a tool call. Reads a
+*  `description` field from params if the tool defined one (bash does);
+*  otherwise falls back to the tool name. Kept short so log lines stay
+*  scannable. */
+function descOfCall(call) {
+	const params = call.params;
+	if (params && typeof params === "object" && typeof params.description === "string") return params.description;
+	return call.name;
+}
+/** Synthesize the tool-result payload returned when the model calls a
+*  tool that wasn't registered for this turn. Same shape the previous
+*  `unknownToolResult` helper produced; inlined here to keep `tasks.ts`
+*  self-contained. */
+function unknownToolResult(name) {
+	return toErrorResult(new AiError({
+		code: "UNKNOWN_TOOL",
+		message: `no tool named "${name}" is registered for this turn`
+	}));
+}
+function sleep(ms) {
+	return new Promise((r) => {
+		setTimeout(r, ms).unref();
+	});
+}
+/** 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). */
+function taskInfoPart(info) {
+	if (info.length === 0) return {
+		data: "no active tasks",
+		tag: "tasks",
+		type: "meta"
+	};
+	return {
+		data: info.map((t) => safeStringify(t, omitResult)).join("\n"),
+		tag: "tasks",
+		type: "meta"
+	};
+}
+/** JSON.stringify replacer that drops the `result` field. Used by
+*  `taskInfoPart` to keep listing payloads bounded. */
+function omitResult(key, value) {
+	return key === "result" ? void 0 : value;
+}
+function toTaskInfo(task) {
+	const { id, status, type, desc } = task;
+	const ms = (task.finishedAt ?? Date.now()) - task.startedAt;
+	if (status === "running") return {
+		desc,
+		elapsedMs: ms,
+		hasNewOutput: task.streamable?.hasNew?.(),
+		id,
+		status,
+		type
+	};
+	if (status === "pending") return {
+		desc,
+		elapsedMs: ms,
+		id,
+		status,
+		type,
+		waitingFor: task.waitingFor ?? ""
+	};
+	return {
+		desc,
+		durationMs: ms,
+		id,
+		result: task.result ?? toErrorResult(new AiError({
+			code: "INTERNAL",
+			message: `task "${task.id}" completed without a result`
+		})),
+		status,
+		type
+	};
+}
+/** Format a finished task as the parts of a system inject. Layout:
+*
+*    <task>{id, type, desc, status: "done", durationMs}</task>
+*    {result body}
+*
+*  The header is the standard `TaskInfo`-shaped JSON so consumers
+*  (model, TUI) can parse it the same way they parse `task_list` and
+*  heartbeat output — same shape everywhere a task surfaces.
+*
+*  The body comes straight from `result.content`. For errors, that
+*  already includes the `<error>{code, message, ...}</error>` MetaPart
+*  + the formatted `❌ CODE: message` block (baked in by
+*  `toErrorResult`), so this function doesn't need to special-case
+*  errors — the structured tag and human body ride along with the
+*  result content for any tool failure, anywhere.
+*
+*  System messages can't carry attachments, so any image/pdf/etc. in
+*  the result degrades to a `[image]` placeholder via
+*  `stringifyContent` — best-effort, model still sees *something* was
+*  there. */
+function formatTaskCompletion(task) {
+	const { result, ...header } = task;
+	const parts = [{
+		data: header,
+		tag: "task",
+		type: "meta"
+	}];
+	const bodyText = stringifyContent(result.content);
+	if (bodyText !== "") parts.push({
+		text: bodyText,
+		type: "text"
+	});
+	return parts;
+}
+/** Build an `inject`-ready system message for a finished task. */
+function taskCompletionMessage(task) {
+	return {
+		content: formatTaskCompletion(task),
+		meta: {
+			kind: "task",
+			taskId: task.id
+		},
+		role: "system"
+	};
+}
+//#endregion
+export { taskCompletionMessage as n, taskInfoPart as r, Tasks as t };
+
+//# sourceMappingURL=tasks-WmC270X2.mjs.map