@kolisachint/hooteams-dag 0.1.14

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [0.1.14] - 2026-06-13
+
+### Added
+- New package: the `TaskDag` — topological order (Kahn), ready/blocked tracking, retry/rework helpers, JSON persistence and crash-recovery (`toJSON`/`fromJSON`/`resetTransient`) — extracted from `@kolisachint/hooteams-orchestrator` into this dependency-free foundation layer (its only import is the `AgentMessage` type from `@kolisachint/hoocode-agent-core`). Re-exported from the orchestrator barrel, so existing consumers are unaffected.
+- Immutable node snapshots: accessors (`get`/`all`/`ready`/`blocked`/`resetToIdle`/`add`) return frozen copies with their `deps`/`results` arrays sliced, so callers can never mutate internal node state through a live reference (a write throws in strict mode, and array splices don't leak back). All node mutation goes through the dag's own methods, including the new `setOutput(id, output)` and `incrementAttempts(id)`. Optional fields are stored canonically — never as explicit `undefined` keys — so a node's serialized shape is stable across `toJSON`/`fromJSON` round trips (`add` omits an unset `retries`; `setOutput(undefined)`/`markDone()`/`resetToIdle` remove `output`/`results` rather than blanking them). `ready`/`blocked`/`isComplete` read internal state directly instead of snapshotting the whole graph on every call.

package/package.json

@@ -0,0 +1,16 @@
+{
+	"name": "@kolisachint/hooteams-dag",
+	"version": "0.1.14",
+	"description": "Dependency-free task DAG for hooteams: topological order, ready/blocked tracking, immutable node snapshots, JSON persistence",
+	"type": "module",
+	"main": "./src/index.ts",
+	"types": "./src/index.ts",
+	"scripts": {
+		"test": "bun test"
+	},
+	"dependencies": {
+		"@kolisachint/hoocode-agent-core": "^0.4.49"
+	},
+	"author": "Sachin Koli",
+	"license": "MIT"
+}

package/src/dag.ts

@@ -0,0 +1,228 @@
+import type { AgentMessage, AgentStatus, TaskNode } from "./types.js";
+
+export interface TaskNodeInput {
+	id: string;
+	role: string;
+	deps?: string[];
+	/** Extra dispatch attempts the node gets after a failed run. Default 0. */
+	retries?: number;
+}
+
+/**
+ * Dependency graph of team tasks. Nodes start "idle", become dispatchable when
+ * every dependency is "done", and markDone() reports which nodes that
+ * completion unblocked so the orchestrator can dispatch them next.
+ */
+export class TaskDag {
+	private readonly nodes = new Map<string, TaskNode>();
+
+	add(input: TaskNodeInput): TaskNode {
+		if (this.nodes.has(input.id)) {
+			throw new Error(`Task "${input.id}" already exists`);
+		}
+		const node: TaskNode = { id: input.id, role: input.role, deps: input.deps?.slice() ?? [], status: "idle" };
+		if (input.retries !== undefined) node.retries = input.retries;
+		this.nodes.set(input.id, node);
+		return this.snapshot(node);
+	}
+
+	get(id: string): TaskNode | undefined {
+		const node = this.nodes.get(id);
+		return node ? this.snapshot(node) : undefined;
+	}
+
+	all(): TaskNode[] {
+		return [...this.nodes.values()].map((node) => this.snapshot(node));
+	}
+
+	/**
+	 * Frozen copy handed to external callers, so the dag's internal node state is
+	 * never held as a live mutable reference: writing to a returned node throws
+	 * (strict mode), and its `deps`/`results` arrays are sliced so they can't be
+	 * spliced into either. (The AgentMessage objects inside `results` are shared
+	 * by reference — they are treated as immutable agent output.) All mutation
+	 * goes through the dag's own methods (markRunning, markDone, setOutput,
+	 * incrementAttempts, …).
+	 */
+	private snapshot(node: TaskNode): TaskNode {
+		const copy: TaskNode = { ...node, deps: node.deps.slice() };
+		if (node.results) copy.results = node.results.slice();
+		return Object.freeze(copy);
+	}
+
+	/**
+	 * Record a settled node's final assistant text, injected into dependents'
+	 * prompts. Clearing it (undefined) removes the field rather than storing an
+	 * explicit `undefined`, keeping the node's serialized shape stable.
+	 */
+	setOutput(id: string, output: string | undefined): void {
+		const node = this.require(id);
+		if (output === undefined) delete node.output;
+		else node.output = output;
+	}
+
+	/** Count one more failed/reworked attempt against a node and return the new total. */
+	incrementAttempts(id: string): number {
+		const node = this.require(id);
+		node.attempts = (node.attempts ?? 0) + 1;
+		return node.attempts;
+	}
+
+	/** Kahn's algorithm. Throws on unknown deps or cycles. */
+	topologicalOrder(): string[] {
+		const inDegree = new Map<string, number>();
+		const dependents = new Map<string, string[]>();
+		for (const node of this.nodes.values()) {
+			inDegree.set(node.id, node.deps.length);
+			for (const dep of node.deps) {
+				if (!this.nodes.has(dep)) {
+					throw new Error(`Task "${node.id}" depends on unknown task "${dep}"`);
+				}
+				const list = dependents.get(dep) ?? [];
+				list.push(node.id);
+				dependents.set(dep, list);
+			}
+		}
+		const queue = [...inDegree.entries()].filter(([, degree]) => degree === 0).map(([id]) => id);
+		const order: string[] = [];
+		while (queue.length > 0) {
+			const id = queue.shift()!;
+			order.push(id);
+			for (const dependent of dependents.get(id) ?? []) {
+				const remaining = inDegree.get(dependent)! - 1;
+				inDegree.set(dependent, remaining);
+				if (remaining === 0) queue.push(dependent);
+			}
+		}
+		if (order.length !== this.nodes.size) {
+			const stuck = [...inDegree.entries()]
+				.filter(([, degree]) => degree > 0)
+				.map(([id]) => id)
+				.join(", ");
+			throw new Error(`Task graph has a cycle involving: ${stuck}`);
+		}
+		return order;
+	}
+
+	/** Nodes that are idle and whose dependencies are all done. */
+	ready(): TaskNode[] {
+		return [...this.nodes.values()]
+			.filter((node) => node.status === "idle" && node.deps.every((dep) => this.nodes.get(dep)?.status === "done"))
+			.map((node) => this.snapshot(node));
+	}
+
+	/** Mark a node as dispatched so ready() stops returning it. */
+	markRunning(id: string, status: AgentStatus = "streaming"): void {
+		const node = this.require(id);
+		node.status = status;
+	}
+
+	/**
+	 * Record a node's completion and the messages its agent produced.
+	 * Returns the nodes this completion made ready, in insertion order.
+	 */
+	markDone(id: string, results?: AgentMessage[]): TaskNode[] {
+		const node = this.require(id);
+		const readyBefore = new Set(this.ready().map((other) => other.id));
+		node.status = "done";
+		if (results === undefined) delete node.results;
+		else node.results = results;
+		return this.ready().filter((other) => !readyBefore.has(other.id));
+	}
+
+	markFailed(id: string): void {
+		this.require(id).status = "error";
+	}
+
+	/**
+	 * Mark a running node as waiting on a human approval. Paused nodes are
+	 * neither ready nor complete, so the dag stays open until they resume
+	 * (markRunning) and eventually settle.
+	 */
+	markPaused(id: string): void {
+		this.require(id).status = "paused";
+	}
+
+	/**
+	 * Send a settled node back to "idle" so ready() re-dispatches it, clearing
+	 * the previous attempt's results and output (but not its attempt count).
+	 * Used for retries and validator-triggered reruns.
+	 */
+	resetToIdle(id: string): TaskNode {
+		const node = this.require(id);
+		node.status = "idle";
+		delete node.results;
+		delete node.output;
+		return this.snapshot(node);
+	}
+
+	/** Nodes that can never run because a transitive dependency failed. */
+	blocked(): TaskNode[] {
+		const failed = new Set([...this.nodes.values()].filter((node) => node.status === "error").map((node) => node.id));
+		if (failed.size === 0) return [];
+		const blocked: TaskNode[] = [];
+		for (const id of this.topologicalOrder()) {
+			const node = this.nodes.get(id)!;
+			if (node.status === "error") continue;
+			if (node.deps.some((dep) => failed.has(dep))) {
+				failed.add(node.id);
+				blocked.push(this.snapshot(node));
+			}
+		}
+		return blocked;
+	}
+
+	/** True when every node is done, failed, or permanently blocked. */
+	isComplete(): boolean {
+		const blockedIds = new Set(this.blocked().map((node) => node.id));
+		return [...this.nodes.values()].every(
+			(node) => node.status === "done" || node.status === "error" || blockedIds.has(node.id),
+		);
+	}
+
+	/**
+	 * Plain-object snapshot of the graph keyed by node id, safe to
+	 * JSON.stringify. The caller decides where to persist it.
+	 */
+	toJSON(): Record<string, TaskNode> {
+		const snapshot: Record<string, TaskNode> = {};
+		for (const [id, node] of this.nodes) {
+			snapshot[id] = { ...node, deps: node.deps.slice() };
+		}
+		return snapshot;
+	}
+
+	/**
+	 * Reset nodes caught mid-run (thinking/streaming/tool) back to idle so a
+	 * restored dag re-dispatches them. Paused nodes are left paused — their
+	 * approval gate is re-surfaced instead of re-running them. Returns the
+	 * nodes that were reset.
+	 */
+	resetTransient(): TaskNode[] {
+		const reset: TaskNode[] = [];
+		for (const node of this.nodes.values()) {
+			if (node.status === "thinking" || node.status === "streaming" || node.status === "tool") {
+				node.status = "idle";
+				reset.push(this.snapshot(node));
+			}
+		}
+		return reset;
+	}
+
+	/** Rebuild a dag from a toJSON() snapshot, preserving statuses and results. */
+	static fromJSON(snapshot: Record<string, TaskNode>): TaskDag {
+		const dag = new TaskDag();
+		for (const node of Object.values(snapshot)) {
+			dag.nodes.set(node.id, { ...node, deps: node.deps?.slice() ?? [] });
+		}
+		return dag;
+	}
+
+	private require(id: string): TaskNode {
+		const node = this.nodes.get(id);
+		if (!node) {
+			throw new Error(`Unknown task "${id}"`);
+		}
+		return node;
+	}
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { TaskDag } from "./dag.js";
+export type { TaskNodeInput } from "./dag.js";
+export type { AgentMessage, AgentStatus, SerializedDag, TaskNode } from "./types.js";

package/src/types.ts

@@ -0,0 +1,29 @@
+import type { AgentMessage } from "@kolisachint/hoocode-agent-core";
+
+export type { AgentMessage };
+
+/** Coarse per-agent status derived from the event stream. */
+export type AgentStatus = "idle" | "thinking" | "streaming" | "tool" | "done" | "error" | "paused";
+
+/** One unit of work in the team DAG, executed by the agent registered under `role`. */
+export interface TaskNode {
+	id: string;
+	role: string;
+	/** Ids of nodes that must reach "done" before this node becomes ready. */
+	deps: string[];
+	status: AgentStatus;
+	/** Messages produced by the node's run, recorded by markDone. */
+	results?: AgentMessage[];
+	/**
+	 * Final assistant text of the node's run, recorded on completion and
+	 * injected into the prompts of nodes that depend on this one.
+	 */
+	output?: string;
+	/** Extra dispatch attempts the node gets after a failed run. Default 0. */
+	retries?: number;
+	/** Failed attempts consumed so far; set by the orchestrator. */
+	attempts?: number;
+}
+
+/** Shape of TaskDag.toJSON(), as persisted in "dag_state" session entries. */
+export type SerializedDag = Record<string, TaskNode>;

package/test/dag.test.ts

@@ -0,0 +1,224 @@
+import { describe, expect, test } from "bun:test";
+import { TaskDag } from "../src/dag.js";
+
+function diamond(): TaskDag {
+	// plan → (code, docs) → test
+	const dag = new TaskDag();
+	dag.add({ id: "plan", role: "planner" });
+	dag.add({ id: "code", role: "coder", deps: ["plan"] });
+	dag.add({ id: "docs", role: "writer", deps: ["plan"] });
+	dag.add({ id: "test", role: "tester", deps: ["code", "docs"] });
+	return dag;
+}
+
+describe("topologicalOrder", () => {
+	test("orders dependencies before dependents", () => {
+		const order = diamond().topologicalOrder();
+		expect(order.indexOf("plan")).toBeLessThan(order.indexOf("code"));
+		expect(order.indexOf("plan")).toBeLessThan(order.indexOf("docs"));
+		expect(order.indexOf("code")).toBeLessThan(order.indexOf("test"));
+		expect(order.indexOf("docs")).toBeLessThan(order.indexOf("test"));
+		expect(order).toHaveLength(4);
+	});
+
+	test("throws on cycles", () => {
+		const dag = new TaskDag();
+		dag.add({ id: "a", role: "x", deps: ["b"] });
+		dag.add({ id: "b", role: "y", deps: ["a"] });
+		expect(() => dag.topologicalOrder()).toThrow(/cycle/);
+	});
+
+	test("throws on unknown dependency", () => {
+		const dag = new TaskDag();
+		dag.add({ id: "a", role: "x", deps: ["ghost"] });
+		expect(() => dag.topologicalOrder()).toThrow(/unknown task "ghost"/);
+	});
+
+	test("rejects duplicate ids", () => {
+		const dag = new TaskDag();
+		dag.add({ id: "a", role: "x" });
+		expect(() => dag.add({ id: "a", role: "y" })).toThrow(/already exists/);
+	});
+});
+
+describe("markDone propagation", () => {
+	test("only roots are ready initially", () => {
+		expect(diamond().ready().map((node) => node.id)).toEqual(["plan"]);
+	});
+
+	test("completing a node returns newly ready nodes only", () => {
+		const dag = diamond();
+		const unblocked = dag.markDone("plan");
+		expect(unblocked.map((node) => node.id).sort()).toEqual(["code", "docs"]);
+
+		// test needs both code and docs — finishing just code unblocks nothing
+		expect(dag.markDone("code")).toEqual([]);
+		expect(dag.markDone("docs").map((node) => node.id)).toEqual(["test"]);
+	});
+
+	test("running nodes are not reported ready", () => {
+		const dag = diamond();
+		dag.markDone("plan");
+		dag.markRunning("code");
+		expect(dag.ready().map((node) => node.id)).toEqual(["docs"]);
+	});
+
+	test("stores results on the node", () => {
+		const dag = diamond();
+		const messages = [{ role: "user" as const, content: "done", timestamp: Date.now() }];
+		dag.markDone("plan", messages);
+		expect(dag.get("plan")?.results).toEqual(messages);
+	});
+
+	test("failed nodes block their descendants", () => {
+		const dag = diamond();
+		dag.markDone("plan");
+		dag.markFailed("code");
+		expect(dag.blocked().map((node) => node.id)).toEqual(["test"]);
+		// docs is unaffected and still ready
+		expect(dag.ready().map((node) => node.id)).toEqual(["docs"]);
+		expect(dag.isComplete()).toBe(false);
+		dag.markDone("docs");
+		expect(dag.isComplete()).toBe(true);
+	});
+});
+
+describe("paused nodes", () => {
+	test("paused nodes are neither ready nor complete", () => {
+		const dag = diamond();
+		dag.markDone("plan");
+		dag.markRunning("code");
+		dag.markPaused("code");
+		expect(dag.get("code")?.status).toBe("paused");
+		expect(dag.ready().map((node) => node.id)).toEqual(["docs"]);
+		dag.markDone("docs");
+		// code is paused and test depends on it — the dag stays open
+		expect(dag.isComplete()).toBe(false);
+		dag.markRunning("code");
+		dag.markDone("code");
+		dag.markDone("test");
+		expect(dag.isComplete()).toBe(true);
+	});
+
+	test("paused status round-trips through toJSON/fromJSON", () => {
+		const dag = diamond();
+		dag.markDone("plan");
+		dag.markPaused("code");
+		const restored = TaskDag.fromJSON(JSON.parse(JSON.stringify(dag.toJSON())));
+		expect(restored.get("code")?.status).toBe("paused");
+	});
+
+	test("resetTransient reverts mid-run nodes to idle but keeps paused and done", () => {
+		const dag = diamond();
+		dag.markDone("plan");
+		dag.markRunning("code", "streaming");
+		dag.markPaused("docs");
+		const reset = dag.resetTransient();
+		expect(reset.map((node) => node.id)).toEqual(["code"]);
+		expect(dag.get("code")?.status).toBe("idle");
+		expect(dag.get("docs")?.status).toBe("paused");
+		expect(dag.get("plan")?.status).toBe("done");
+	});
+});
+
+describe("retries and rework", () => {
+	test("add() records the retry budget on the node", () => {
+		const dag = new TaskDag();
+		dag.add({ id: "a", role: "x", retries: 2 });
+		expect(dag.get("a")?.retries).toBe(2);
+	});
+
+	test("resetToIdle re-arms a settled node, clearing results and output but not attempts", () => {
+		const dag = diamond();
+		dag.markDone("plan", [{ role: "user", content: "done", timestamp: 1 } as any]);
+		dag.setOutput("plan", "the plan");
+		dag.incrementAttempts("plan");
+		expect(dag.get("plan")?.output).toBe("the plan");
+
+		const node = dag.resetToIdle("plan");
+
+		expect(node.status).toBe("idle");
+		expect(node.results).toBeUndefined();
+		expect(node.output).toBeUndefined();
+		expect(node.attempts).toBe(1);
+		expect(dag.ready().map((other) => other.id)).toEqual(["plan"]);
+		expect(dag.isComplete()).toBe(false);
+	});
+
+	test("incrementAttempts counts up and returns the running total", () => {
+		const dag = new TaskDag();
+		dag.add({ id: "a", role: "x" });
+		expect(dag.incrementAttempts("a")).toBe(1);
+		expect(dag.incrementAttempts("a")).toBe(2);
+		expect(dag.get("a")?.attempts).toBe(2);
+	});
+});
+
+describe("immutable snapshots", () => {
+	test("accessors hand back frozen copies, so external writes never leak into the dag", () => {
+		const dag = new TaskDag();
+		dag.add({ id: "a", role: "x" });
+		const node = dag.get("a")!;
+		expect(Object.isFrozen(node)).toBe(true);
+		expect(() => {
+			(node as any).output = "leak";
+		}).toThrow();
+		// the dag's own state is untouched by the rejected write
+		expect(dag.get("a")?.output).toBeUndefined();
+	});
+
+	test("mutating a returned node's deps array does not change the dag", () => {
+		const dag = new TaskDag();
+		dag.add({ id: "a", role: "x", deps: [] });
+		const node = dag.get("a")!;
+		node.deps.push("ghost");
+		expect(dag.get("a")?.deps).toEqual([]);
+	});
+
+	test("mutating a returned node's results array does not change the dag", () => {
+		const dag = new TaskDag();
+		dag.add({ id: "a", role: "x" });
+		dag.markDone("a", [{ role: "assistant", content: "one", timestamp: 1 } as any]);
+		const node = dag.get("a")!;
+		node.results!.push({ role: "user", content: "leak", timestamp: 2 } as any);
+		expect(dag.get("a")?.results).toHaveLength(1);
+	});
+});
+
+describe("persistence", () => {
+	test("toJSON/fromJSON round-trips nodes, statuses, and results", () => {
+		const dag = diamond();
+		dag.markDone("plan", [{ role: "user", content: [{ type: "text", text: "done" }], timestamp: 1 } as any]);
+		dag.markRunning("code");
+
+		const restored = TaskDag.fromJSON(JSON.parse(JSON.stringify(dag.toJSON())));
+
+		expect(restored.all()).toEqual(dag.all());
+		expect(restored.get("plan")?.results).toEqual(dag.get("plan")?.results);
+		// derived state survives the round trip: code is running, docs is ready
+		expect(restored.ready().map((node) => node.id)).toEqual(["docs"]);
+	});
+
+	test("a node reset after producing output round-trips cleanly", () => {
+		const dag = diamond();
+		dag.markDone("plan");
+		dag.setOutput("plan", "the plan");
+		dag.resetToIdle("plan");
+
+		const restored = TaskDag.fromJSON(JSON.parse(JSON.stringify(dag.toJSON())));
+
+		// resetToIdle clears output/results by removing them, so the serialized
+		// shape is stable: no explicit-undefined keys to drop on the round trip.
+		expect(restored.all()).toEqual(dag.all());
+		expect(dag.get("plan")?.output).toBeUndefined();
+	});
+
+	test("the restored dag is independent of the source", () => {
+		const dag = diamond();
+		const restored = TaskDag.fromJSON(dag.toJSON());
+		restored.markDone("plan");
+		expect(restored.get("plan")?.status).toBe("done");
+		expect(dag.get("plan")?.status).toBe("idle");
+	});
+
+});