@prometheus-ai/agent 0.5.4 → 0.5.8

package/src/prompts/tools/task.md

@@ -1,44 +1,59 @@
-Launches subagents to parallelize workflows.
+{{#if asyncEnabled}}{{#if batchEnabled}}Spawns subagents to work in the background — one per `tasks[]` item; a single spawn is a one-item batch.{{else}}Spawns ONE subagent per call to work in the background.{{/if}}
 
-{{#if asyncEnabled}}
-- Results are delivered automatically when complete.
-- The tool result lists the assigned task ids (e.g. `AuthLoader`) — those are the live agent ids.
-{{#if ircEnabled}}
-- Coordinate with running tasks via `irc` using those ids. `job cancel` terminates a task and **cannot carry a message** — only use it for stalled/abandoned work.
-- If genuinely blocked on completion, wait with `job poll`; otherwise keep working.
-{{else}}
-- If genuinely blocked on completion, wait with `job poll`; otherwise keep working.
-- Use `job list` to snapshot manager state; `cancel: [id]` only to actually stop a stuck task.
-{{/if}}
-{{/if}}
+- Spawning is non-blocking: the call returns immediately with the agent id{{#if batchEnabled}}s{{/if}} and job id{{#if batchEnabled}}s{{/if}}; each result is delivered automatically when that agent yields.
+- Parallelism = {{#if batchEnabled}}multiple `tasks[]` items in ONE call. To launch several subagents, you MUST batch them into a single call's `tasks[]` — they share `context` once instead of duplicating it. Separate `task` calls in one message are ONLY for spawns needing a different `agent` type or unrelated `context`{{else}}multiple `task` calls in one assistant message{{/if}}. Concurrency is bounded at {{MAX_CONCURRENCY}} running subagents per session.
+- If genuinely blocked on a result, wait with `job poll`; otherwise keep working. `job cancel` terminates a task and **cannot carry a message** — only for stalled/abandoned work.
+{{else}}{{#if batchEnabled}}Runs subagents synchronously — one per `tasks[]` item; a single spawn is a one-item batch.{{else}}Runs ONE subagent synchronously per call.{{/if}}
 
+- Spawning is blocking: the call returns only after the agent{{#if batchEnabled}}s{{/if}} finish; results arrive inline.
+- Parallelism = {{#if batchEnabled}}multiple `tasks[]` items in ONE call. To launch several subagents, you MUST batch them into a single call's `tasks[]` — they share `context` once instead of duplicating it. Separate `task` calls in one message are ONLY for spawns needing a different `agent` type or unrelated `context`{{else}}multiple `task` calls in one assistant message{{/if}}. Concurrency is bounded at {{MAX_CONCURRENCY}} running subagents per session.
+{{/if}}
 {{#if ircEnabled}}
-Subagents have no conversation history, but they can reach you and their siblings live via the `irc` tool. Front-load every fact, file path, and direction they need in {{#if contextEnabled}}`context` or `assignment`{{else}}each `assignment`{{/if}}.
-{{else}}
-Subagents have no conversation history. Every fact, file path, and direction they need MUST be explicit in {{#if contextEnabled}}`context` or `assignment`{{else}}each `assignment`{{/if}}.
+- Coordinate with agents via `irc` using their ids. Agents reach you and their siblings live the same way.
 {{/if}}
 
+<lifecycle>
+- Finished agents stay alive: `idle` first, then `parked` after a TTL.{{#if ircEnabled}} Both remain addressable and revivable: messaging one via `irc` wakes it and runs your message as a follow-up turn. **Prefer messaging an agent that already holds the relevant context over spawning fresh** — check `irc` op:"list" for candidates.{{/if}}
+- `history://<id>` is the agent's transcript; `agent://<id>` its latest output artifact.
+</lifecycle>
+
 <parameters>
-- `agent`: agent type for all tasks
-- `tasks`: tasks to execute in parallel
- - `.id`: CamelCase, ≤32 chars
- - `.description`: UI label only — subagent never sees it
- - `.assignment`: complete self-contained instructions; one-liners and missing acceptance criteria are PROHIBITED
-{{#if contextEnabled}}- `context`: shared background prepended to every assignment; session-specific only{{/if}}
-{{#if customSchemaEnabled}}- `schema`: JTD schema for expected structured output (do not put format rules in assignments){{/if}}
-{{#if isolationEnabled}}- `isolated`: run in isolated env; use when tasks edit overlapping files{{/if}}
+- `agent`: agent type to spawn
+{{#if batchEnabled}}
+- `context`: shared background prepended to every assignment — goal, constraints, shared contract (see context-fmt); REQUIRED, session-specific only
+- `tasks`: tasks to spawn — one subagent per item, all in parallel:
+  - `assignment`: complete self-contained instructions; one-liners and missing acceptance criteria are PROHIBITED
+  - `id`: stable agent id, CamelCase, ≤32 chars; generated when omitted
+  - `description`: UI label only — subagent never sees it
+  - `role`: specialist identity this subagent embodies (e.g. "Auth-flow security reviewer") — sets its system-prompt persona and roster display name; tailor every spawn rather than cloning a generic worker
+{{#if isolationEnabled}}
+  - `isolated`: run this spawn in an isolated env; returns patches. Isolated agents are torn down at completion — not addressable afterwards
+{{/if}}
+{{else}}
+- `id`: stable agent id, CamelCase, ≤32 chars; generated when omitted
+- `description`: UI label only — subagent never sees it
+- `role`: specialist identity this subagent embodies (e.g. "Auth-flow security reviewer") — sets its system-prompt persona and roster display name; tailor every spawn rather than cloning a generic worker
+- `assignment`: complete self-contained instructions; one-liners and missing acceptance criteria are PROHIBITED
+{{#if isolationEnabled}}
+- `isolated`: run in isolated env; returns patches. Isolated agents are torn down at completion — not addressable afterwards
+{{/if}}
+{{/if}}
 </parameters>
 
 <rules>
-- **Maximize batch width.** Spawn the widest parallel set the work decomposes into. NEVER spawn a single-task batch for divisible work, or defer work that could have been concurrent.
-- NEVER assign tasks to run project-wide build/test/lint. Caller verifies after the batch.
-- **Subagents do not verify, lint, or format.** Every assignment MUST instruct the subagent to skip all gates and formatters. You run them once at the end across the union of changed files — avoids redundant runs and racing formatter passes.
+- **Maximize fan-out.** Issue the widest {{#if batchEnabled}}`tasks[]` batch{{else}}set of parallel `task` calls{{/if}} the work decomposes into. NEVER serialize work that could run concurrently.
+- **Subagents do not verify, lint, or format.** Every assignment MUST instruct the subagent to skip all gates, formatters, and project-wide build/test/lint. You run them once at the end across the union of changed files.
 - No globs, no "update all", no package-wide scope. Fan out.
-- Do not concern yourself with how agents might overlap on certain actions. Never use it as an excuse to go slower: they can resolve collisions in real-time with the harness facilities.
-- Pass large payloads via `local://<path>` URIs, not inline. {{#if contextEnabled}} (other than the context){{/if}}
-{{#if contextEnabled}}- Put shared constraints in `context` once; do not duplicate across assignments.{{/if}}
+- **Tailor every spawn with a `role`.** A role naming the specialist (e.g. "Parser edge-case tester", "SSE backpressure specialist") makes a sharper agent than a bare generic `task`/`quick_task` worker; decompose into named specialists, never clones of one generic worker. A role-less generic spawn is the exception.
+- NEVER slow down or serialize because tasks might overlap on some files. Agents resolve collisions among themselves in real time.
+- Subagents have no conversation history. Every fact, file path, and direction they need MUST be explicit in {{#if batchEnabled}}`context` or the item's `assignment`{{else}}the `assignment`{{/if}}.
+{{#if batchEnabled}}
+- **Shared background** lives in `context` once — never duplicated across assignments. Pass large payloads via `local://<path>` URIs, not inline.
+{{else}}
+- **Shared background**: write it ONCE to a `local://` file (e.g. `local://ctx.md`) and reference that path in each assignment. Pass large payloads via `local://<path>` URIs, not inline.
+{{/if}}
 - Prefer agents that investigate **and** edit in one pass; only spin a read-only discovery step when affected files are genuinely unknown.
-- **Read-only agents**: Agents tagged READ-ONLY (e.g. `explore`) have no edit/write/command tools. NEVER hand them an assignment that requires changing files or running commands — they cannot do it and the turn is wasted. Use them to investigate and report back; do the edits yourself or delegate to a writing agent (`task`, `oracle`, `designer`).
+- **Read-only agents**: Agents tagged READ-ONLY (e.g. `explore`) have no edit/write/command tools. NEVER hand them an assignment that requires changing files or running commands. Use them to investigate and report back; do the edits yourself or delegate to a writing agent (`task`, `oracle`, `designer`).
 - **No reasoning offload**: NEVER offload reasoning, analysis, design, or decision-making to `quick_task` or `explore` — they run minimal-effort / small models for mechanical lookups and data collection only. Keep judgment and synthesis in your own context; delegate hard thinking to `task`, `plan`, or `oracle`.
 </rules>
 
@@ -52,9 +67,10 @@ Test: can task B run correctly without seeing A's output? If no, sequence A →
 Sequential when one task produces a contract (types, API, schema, core module) the other consumes.
 Parallel when tasks touch disjoint files or are independent refactors/tests.
 {{/if}}
+{{#if ircEnabled}}Sequenced follow-ups SHOULD message the agent that produced the prerequisite — it already holds the context.{{/if}}
 </parallelization>
 
-{{#if contextEnabled}}
+{{#if batchEnabled}}
 <context-fmt>
 # Goal         ← one sentence: what the batch accomplishes
 # Constraints  ← MUST/NEVER rules and session decisions

package/src/prompts/tools/todo.md

@@ -2,7 +2,7 @@
 
 Manages a phased task list. Pass `ops`: a flat array of operations.
 The next pending task is auto-promoted to `in_progress` after each completion.
-Allowed `op` values are only `init`, `start`, `done`, `drop`, `rm`, `append`, and `note`. `pending` is a task status, not an `op`; leave not-yet-started tasks implicit in `init`/`append` lists.
+Allowed `op` values are only `init`, `start`, `done`, `drop`, `rm`, `append`, and `view`. `pending` is a task status, not an `op`; leave not-yet-started tasks implicit in `init`/`append` lists.
 
 ## Operations
 
@@ -12,9 +12,9 @@ Allowed `op` values are only `init`, `start`, `done`, `drop`, `rm`, `append`, an
 |`start`|`task`|Mark in progress|
 |`done`|`task` or `phase`|Mark completed|
 |`drop`|`task` or `phase`|Mark abandoned|
-|`rm`|`task` or `phase`|Remove|
+|`rm`|`task` or `phase` (optional)|Remove task or phase's tasks; omit both to clear the entire list|
 |`append`|`phase`, `items: string[]`|Append tasks to `phase`; lazily creates phase|
-|`note`|`task`, `text`|Append a note to a task. Reminders for future-you only.|
+|`view`|—|Read-only: echo the current list without modifying it|
 
 ## Anatomy
 - **Task content**: 5–10 words, what is being done, not how. Used as the task identifier — unique.
@@ -25,6 +25,7 @@ Allowed `op` values are only `init`, `start`, `done`, `drop`, `rm`, `append`, an
 - Complete phases in order.
 - On blockers, `append` a new task to the active phase to unblock yourself, or `drop`.
 - `task` and `phase` fields reference content/name verbatim; keep them stable once introduced.
+- Lost track of exact task text? `view` echoes the full list — NEVER guess content from memory; a mismatched `task` string is an error.
 
 ## When to create a list
 - Task requires 3+ distinct steps
@@ -35,6 +36,8 @@ Allowed `op` values are only `init`, `start`, `done`, `drop`, `rm`, `append`, an
 <examples>
 # Initial setup (multi-phase)
 `{"ops":[{"op":"init","list":[{"phase":"Foundation","items":["Scaffold crate","Wire workspace"]},{"phase":"Auth","items":["Port credential store","Wire OAuth providers"]},{"phase":"Verification","items":["Run cargo test"]}]}]}`
+# View current state (read-only)
+`{"ops":[{"op":"view"}]}`
 # Initial setup (single phase)
 `{"ops":[{"op":"init","list":[{"phase":"Implementation","items":["Apply fix","Run tests"]}]}]}`
 # Complete one task

package/src/registry/agent-lifecycle.ts

@@ -0,0 +1,218 @@
+/**
+ * AgentLifecycleManager - Owns the idle → parked → revived lifecycle of
+ * adopted subagents.
+ *
+ * The task executor hands a finished agent over via {@link AgentLifecycleManager.adopt};
+ * from then on the manager arms a TTL timer whenever the agent goes `idle`,
+ * parks it on expiry (disposes the live session, keeps the AgentRef +
+ * sessionFile), and revives it on demand through
+ * {@link AgentLifecycleManager.ensureLive}. Only this manager flips
+ * `parked` ↔ `idle`.
+ */
+
+import { logger } from "@prometheus-ai/utils";
+import type { AgentSession } from "../session/agent-session";
+import { AgentRegistry, MAIN_AGENT_ID, type RegistryEvent } from "./agent-registry";
+
+export type AgentReviver = () => Promise<AgentSession>;
+
+export interface AdoptOptions {
+	/** TTL before an idle agent is parked. <= 0 disables parking. */
+	idleTtlMs: number;
+	/** Recreates a live AgentSession from the ref's sessionFile. Absent => not resumable after park (e.g. isolated runs). */
+	revive?: AgentReviver;
+}
+
+interface AdoptedAgent {
+	idleTtlMs: number;
+	revive?: AgentReviver;
+	timer?: NodeJS.Timeout;
+}
+
+export class AgentLifecycleManager {
+	static #global: AgentLifecycleManager | undefined;
+
+	static global(): AgentLifecycleManager {
+		if (!AgentLifecycleManager.#global) {
+			AgentLifecycleManager.#global = new AgentLifecycleManager();
+		}
+		return AgentLifecycleManager.#global;
+	}
+
+	/** Reset the global manager. Test-only. */
+	static resetGlobalForTests(): void {
+		const current = AgentLifecycleManager.#global;
+		if (current) {
+			current.#unsubscribe?.();
+			current.#unsubscribe = undefined;
+			for (const adopted of current.#adopted.values()) {
+				clearTimeout(adopted.timer);
+			}
+			current.#adopted.clear();
+			current.#revivals.clear();
+			current.#parking.clear();
+		}
+		AgentLifecycleManager.#global = undefined;
+	}
+
+	readonly #registry: AgentRegistry;
+	readonly #adopted = new Map<string, AdoptedAgent>();
+	/** Ids whose session is being disposed by {@link park} right now. */
+	readonly #parking = new Set<string>();
+	/** In-flight revives, so concurrent {@link ensureLive} calls coalesce. */
+	readonly #revivals = new Map<string, Promise<AgentSession>>();
+	#unsubscribe: (() => void) | undefined;
+
+	constructor(registry: AgentRegistry = AgentRegistry.global()) {
+		this.#registry = registry;
+		this.#unsubscribe = registry.onChange(event => this.#onRegistryEvent(event));
+	}
+
+	/**
+	 * Take ownership of a finished subagent. Caller has already set registry
+	 * status to "idle". Arms the TTL timer (idleTtlMs <= 0 adopts without one).
+	 */
+	adopt(id: string, opts: AdoptOptions): void {
+		if (id === MAIN_AGENT_ID) return;
+		if (!this.#registry.get(id)) {
+			logger.warn("AgentLifecycleManager.adopt: unknown agent id", { id });
+			return;
+		}
+		const existing = this.#adopted.get(id);
+		clearTimeout(existing?.timer);
+		const adopted: AdoptedAgent = { idleTtlMs: opts.idleTtlMs, revive: opts.revive };
+		this.#adopted.set(id, adopted);
+		this.#armTimer(id, adopted);
+	}
+
+	/** True if the id is adopted (parked or live). */
+	has(id: string): boolean {
+		return this.#adopted.has(id);
+	}
+
+	/** True while {@link park} is disposing this agent's session (lets dispose hooks distinguish park from teardown). */
+	isParking(id: string): boolean {
+		return this.#parking.has(id);
+	}
+
+	/**
+	 * Dispose the live session, detach it from the registry, and mark the
+	 * agent `parked`. No-op unless the id is adopted and live.
+	 */
+	async park(id: string): Promise<void> {
+		const adopted = this.#adopted.get(id);
+		if (!adopted) return;
+		const ref = this.#registry.get(id);
+		if (!ref?.session) return;
+		if (adopted.timer) {
+			clearTimeout(adopted.timer);
+			adopted.timer = undefined;
+		}
+		this.#parking.add(id);
+		try {
+			try {
+				await ref.session.dispose();
+			} catch (error) {
+				logger.warn("AgentLifecycleManager.park: session dispose failed", { id, error: String(error) });
+			}
+			this.#registry.detachSession(id);
+			this.#registry.setStatus(id, "parked");
+		} finally {
+			this.#parking.delete(id);
+		}
+	}
+
+	/**
+	 * Return the live session, reviving from the sessionFile if parked.
+	 * Throws a plain Error if the id is unknown or parked without a reviver.
+	 * Concurrent calls share one in-flight revive.
+	 */
+	async ensureLive(id: string): Promise<AgentSession> {
+		const ref = this.#registry.get(id);
+		if (!ref) {
+			throw new Error(
+				`Unknown agent "${id}" — it was never registered or has been released. If a transcript exists, read history://${id}.`,
+			);
+		}
+		if (ref.session) return ref.session;
+		const inflight = this.#revivals.get(id);
+		if (inflight) return inflight;
+		const adopted = this.#adopted.get(id);
+		if (ref.status !== "parked" || !adopted?.revive) {
+			throw new Error(
+				`Agent "${id}" is ${ref.status} and cannot be revived${adopted?.revive ? "" : " (no reviver registered)"}. Its transcript remains readable at history://${id}.`,
+			);
+		}
+		const revival = this.#revive(id, adopted.revive, ref.sessionFile);
+		this.#revivals.set(id, revival);
+		try {
+			return await revival;
+		} finally {
+			this.#revivals.delete(id);
+		}
+	}
+
+	/** Hard removal: dispose if live, unregister from registry, drop timers. */
+	async release(id: string): Promise<void> {
+		const adopted = this.#adopted.get(id);
+		clearTimeout(adopted?.timer);
+		this.#adopted.delete(id);
+		const ref = this.#registry.get(id);
+		if (ref?.session) {
+			try {
+				await ref.session.dispose();
+			} catch (error) {
+				logger.warn("AgentLifecycleManager.release: session dispose failed", { id, error: String(error) });
+			}
+		}
+		this.#registry.unregister(id);
+	}
+
+	/** Teardown everything (process exit / main session dispose). */
+	async dispose(): Promise<void> {
+		this.#unsubscribe?.();
+		this.#unsubscribe = undefined;
+		const ids = [...this.#adopted.keys()];
+		await Promise.all(ids.map(id => this.release(id)));
+		this.#revivals.clear();
+		this.#parking.clear();
+	}
+
+	async #revive(id: string, revive: AgentReviver, sessionFile: string | null): Promise<AgentSession> {
+		const session = await revive();
+		this.#registry.attachSession(id, session, sessionFile);
+		// Emits status_changed → "idle", which re-arms the TTL timer below.
+		this.#registry.setStatus(id, "idle");
+		return session;
+	}
+
+	#armTimer(id: string, adopted: AdoptedAgent): void {
+		if (adopted.idleTtlMs <= 0) return;
+		clearTimeout(adopted.timer);
+		const timer = setTimeout(() => {
+			adopted.timer = undefined;
+			void this.park(id);
+		}, adopted.idleTtlMs);
+		timer.unref?.();
+		adopted.timer = timer;
+	}
+
+	#onRegistryEvent(event: RegistryEvent): void {
+		const adopted = this.#adopted.get(event.ref.id);
+		if (!adopted) return;
+		if (event.type === "removed") {
+			clearTimeout(adopted.timer);
+			this.#adopted.delete(event.ref.id);
+			return;
+		}
+		if (event.type !== "status_changed") return;
+		if (event.ref.status === "running") {
+			if (adopted.timer) {
+				clearTimeout(adopted.timer);
+				adopted.timer = undefined;
+			}
+		} else if (event.ref.status === "idle") {
+			this.#armTimer(event.ref.id, adopted);
+		}
+	}
+}

package/src/registry/agent-registry.ts

@@ -1,16 +1,27 @@
 /**
- * AgentRegistry - Process-global registry of live AgentSession instances.
+ * AgentRegistry - Process-global registry of agents (the main session plus
+ * every subagent), keyed by stable id.
  *
- * Tracks every alive agent (the main session plus every subagent) so the
- * `irc` tool can address peers by id. Sessions are registered explicitly at
- * creation and removed when the owner releases them.
+ * Tracks each agent's status and (when live) its AgentSession so peers can be
+ * addressed by id (`irc`, `task resume`, `history://`). Sessions are
+ * registered explicitly at creation; finished agents stay registered as
+ * `idle` (live) or `parked` (session disposed, ref + sessionFile retained for
+ * revival) and are only removed on explicit release/teardown.
  */
 
 import type { AgentSession } from "../session/agent-session";
+import { oneLineLabel } from "../task/types";
 
 export const MAIN_AGENT_ID = "Main";
 
-export type AgentStatus = "running" | "idle" | "completed" | "aborted";
+/**
+ * - `running`: a turn is in flight.
+ * - `idle`: live AgentSession in memory, awaiting work. Finished agents are
+ *   `idle`, not removed.
+ * - `parked`: session disposed; AgentRef + sessionFile retained, revivable.
+ * - `aborted`: hard-killed, terminal.
+ */
+export type AgentStatus = "running" | "idle" | "parked" | "aborted";
 export type AgentKind = "main" | "sub";
 
 export interface AgentRef {
@@ -19,10 +30,13 @@ export interface AgentRef {
 	kind: AgentKind;
 	parentId?: string;
 	status: AgentStatus;
+	/** Null exactly when parked/aborted. */
 	session: AgentSession | null;
 	sessionFile: string | null;
 	createdAt: number;
 	lastActivity: number;
+	/** Short gist of what the agent is currently doing (latest intent or tool), for the work-aware roster. Display-only. */
+	activity?: string;
 }
 
 export type RegistryEvent =
@@ -82,10 +96,37 @@ export class AgentRegistry {
 		const ref = this.#refs.get(id);
 		if (!ref || ref.status === status) return;
 		ref.status = status;
+		// Activity describes current work; it is meaningless once the agent
+		// leaves `running`, so drop it to avoid showing stale work in rosters.
+		if (status !== "running") ref.activity = undefined;
 		ref.lastActivity = Date.now();
 		this.#emit({ type: "status_changed", ref });
 	}
 
+	/**
+	 * Record a short activity gist for the work-aware roster. Display-only and
+	 * read on demand (`irc list`, peer roster), so it emits no event — keeping
+	 * the per-tool-call update rate off the registry listener path (same as
+	 * `attachSession`, which also bumps `lastActivity` without emitting). Only a
+	 * `running` agent has current work: a heartbeat for any other status is
+	 * dropped, so a late progress flush can't resurrect activity on a ref that
+	 * `setStatus` just cleared. Every running heartbeat refreshes `lastActivity`
+	 * — even when the gist text is unchanged — so the roster's "active … ago" and
+	 * recency sort track real work, not just the last status change.
+	 * The gist is normalized to one bounded line (`oneLineLabel`) so model-derived
+	 * intent text can neither break the roster nor smuggle terminal escapes —
+	 * every caller is safe without sanitizing at its own call site.
+	 */
+	setActivity(id: string, activity: string): void {
+		const ref = this.#refs.get(id);
+		if (!ref) return;
+		if (ref.status !== "running") return;
+		const gist = oneLineLabel(activity);
+		ref.lastActivity = Date.now();
+		if (ref.activity === gist) return;
+		ref.activity = gist;
+	}
+
 	attachSession(id: string, session: AgentSession, sessionFile?: string | null): void {
 		const ref = this.#refs.get(id);
 		if (!ref) return;