@auxiora/callgraph 0.1.0

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Auxiora Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@auxiora/callgraph",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { CallgraphTracker } from './tracker.js';
+export { CallgraphStore } from './store.js';
+export type { StoredNode, StoredEdge, StoredSnapshot, WorkflowSummary } from './store.js';
+export type {
+  AgentNode,
+  AgentNodeInput,
+  AgentNodeUpdate,
+  AgentStatus,
+  CallgraphConfig,
+  CallgraphEdge,
+  CallgraphSnapshot,
+} from './types.js';

package/src/store.ts

@@ -0,0 +1,142 @@
+import { DatabaseSync } from 'node:sqlite';
+import type { AgentStatus } from './types.js';
+
+export interface StoredNode {
+  id: string;
+  workflowId: string;
+  name: string;
+  parentId?: string;
+  depth: number;
+  status: AgentStatus;
+  startedAt: number;
+  completedAt?: number;
+  tokenUsage: number;
+}
+
+export interface StoredEdge {
+  workflowId: string;
+  parentId: string;
+  childId: string;
+}
+
+export interface WorkflowSummary {
+  workflowId: string;
+  nodeCount: number;
+  firstStartedAt: number;
+}
+
+export interface StoredSnapshot {
+  nodes: StoredNode[];
+  edges: StoredEdge[];
+  totalTokenUsage: number;
+}
+
+const NODES_DDL = `
+  CREATE TABLE IF NOT EXISTS callgraph_nodes (
+    id TEXT NOT NULL,
+    workflowId TEXT NOT NULL,
+    name TEXT NOT NULL,
+    parentId TEXT,
+    depth INTEGER NOT NULL,
+    status TEXT NOT NULL,
+    startedAt INTEGER NOT NULL,
+    completedAt INTEGER,
+    tokenUsage INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (id, workflowId)
+  )
+`;
+
+const EDGES_DDL = `
+  CREATE TABLE IF NOT EXISTS callgraph_edges (
+    workflowId TEXT NOT NULL,
+    parentId TEXT NOT NULL,
+    childId TEXT NOT NULL,
+    PRIMARY KEY (workflowId, parentId, childId)
+  )
+`;
+
+export class CallgraphStore {
+  private readonly db: DatabaseSync;
+  private closed = false;
+
+  constructor(dbPath: string) {
+    this.db = new DatabaseSync(dbPath);
+    this.db.exec('PRAGMA journal_mode=WAL');
+    this.db.exec('PRAGMA busy_timeout=5000');
+    this.db.exec(NODES_DDL);
+    this.db.exec(EDGES_DDL);
+  }
+
+  recordNode(node: StoredNode): void {
+    if (this.closed) return;
+    const stmt = this.db.prepare(
+      'INSERT OR REPLACE INTO callgraph_nodes (id, workflowId, name, parentId, depth, status, startedAt, completedAt, tokenUsage) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    );
+    stmt.run(node.id, node.workflowId, node.name, node.parentId ?? null, node.depth, node.status, node.startedAt, node.completedAt ?? null, node.tokenUsage);
+  }
+
+  recordEdge(edge: StoredEdge): void {
+    if (this.closed) return;
+    const stmt = this.db.prepare(
+      'INSERT OR IGNORE INTO callgraph_edges (workflowId, parentId, childId) VALUES (?, ?, ?)',
+    );
+    stmt.run(edge.workflowId, edge.parentId, edge.childId);
+  }
+
+  getNodesByWorkflow(workflowId: string): StoredNode[] {
+    if (this.closed) return [];
+    const stmt = this.db.prepare('SELECT * FROM callgraph_nodes WHERE workflowId = ? ORDER BY depth ASC, startedAt ASC');
+    const rows = stmt.all(workflowId) as Record<string, unknown>[];
+    return rows.map((r) => ({
+      id: r.id as string,
+      workflowId: r.workflowId as string,
+      name: r.name as string,
+      parentId: (r.parentId as string) || undefined,
+      depth: r.depth as number,
+      status: r.status as AgentStatus,
+      startedAt: r.startedAt as number,
+      completedAt: (r.completedAt as number) || undefined,
+      tokenUsage: r.tokenUsage as number,
+    }));
+  }
+
+  getEdgesByWorkflow(workflowId: string): StoredEdge[] {
+    if (this.closed) return [];
+    const stmt = this.db.prepare('SELECT * FROM callgraph_edges WHERE workflowId = ?');
+    const rows = stmt.all(workflowId) as Record<string, unknown>[];
+    return rows.map((r) => ({
+      workflowId: r.workflowId as string,
+      parentId: r.parentId as string,
+      childId: r.childId as string,
+    }));
+  }
+
+  getSnapshot(workflowId: string): StoredSnapshot {
+    const nodes = this.getNodesByWorkflow(workflowId);
+    const edges = this.getEdgesByWorkflow(workflowId);
+    let totalTokenUsage = 0;
+    for (const node of nodes) {
+      totalTokenUsage += node.tokenUsage;
+    }
+    return { nodes, edges, totalTokenUsage };
+  }
+
+  listWorkflows(): WorkflowSummary[] {
+    if (this.closed) return [];
+    const stmt = this.db.prepare(
+      'SELECT workflowId, COUNT(*) as nodeCount, MIN(startedAt) as firstStartedAt FROM callgraph_nodes GROUP BY workflowId ORDER BY firstStartedAt DESC',
+    );
+    const rows = stmt.all() as Record<string, unknown>[];
+    return rows.map((r) => ({
+      workflowId: r.workflowId as string,
+      nodeCount: r.nodeCount as number,
+      firstStartedAt: r.firstStartedAt as number,
+    }));
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.db.close();
+  }
+}

package/src/tracker.ts

@@ -0,0 +1,127 @@
+import type { CallgraphConfig, AgentNode, AgentNodeInput, AgentNodeUpdate, CallgraphEdge } from './types.js';
+
+export class CallgraphTracker {
+  private readonly nodes = new Map<string, AgentNode>();
+  private readonly edges: CallgraphEdge[] = [];
+  private readonly children = new Map<string, string[]>();
+  private readonly config: CallgraphConfig;
+
+  constructor(config: CallgraphConfig) {
+    this.config = config;
+  }
+
+  addAgent(input: AgentNodeInput): void {
+    if (this.nodes.has(input.id)) {
+      throw new Error(`Agent ${input.id} already exists in callgraph`);
+    }
+
+    let depth = 0;
+    if (input.parentId) {
+      const parent = this.nodes.get(input.parentId);
+      if (!parent) {
+        throw new Error(`Parent agent ${input.parentId} not found`);
+      }
+      depth = parent.depth + 1;
+      if (depth > this.config.maxDepth) {
+        throw new Error(`Agent ${input.id} exceeds depth limit (${depth} > ${this.config.maxDepth})`);
+      }
+      this.edges.push({ parentId: input.parentId, childId: input.id });
+      const siblings = this.children.get(input.parentId) ?? [];
+      siblings.push(input.id);
+      this.children.set(input.parentId, siblings);
+    }
+
+    this.nodes.set(input.id, {
+      id: input.id,
+      name: input.name,
+      parentId: input.parentId,
+      depth,
+      status: 'running',
+      startedAt: input.startedAt,
+      tokenUsage: 0,
+    });
+  }
+
+  updateAgent(id: string, update: AgentNodeUpdate): void {
+    const node = this.nodes.get(id);
+    if (!node) {
+      throw new Error(`Agent ${id} not found`);
+    }
+    if (update.status !== undefined) node.status = update.status;
+    if (update.completedAt !== undefined) node.completedAt = update.completedAt;
+    if (update.tokenUsage !== undefined) node.tokenUsage = update.tokenUsage;
+  }
+
+  getNode(id: string): AgentNode | undefined {
+    return this.nodes.get(id);
+  }
+
+  getNodes(): AgentNode[] {
+    return [...this.nodes.values()];
+  }
+
+  getEdges(): CallgraphEdge[] {
+    return [...this.edges];
+  }
+
+  getChildren(parentId: string): AgentNode[] {
+    const childIds = this.children.get(parentId) ?? [];
+    return childIds.map((id) => this.nodes.get(id)!);
+  }
+
+  getMaxDepth(): number {
+    let max = 0;
+    for (const node of this.nodes.values()) {
+      if (node.depth > max) max = node.depth;
+    }
+    return max;
+  }
+
+  topologicalOrder(): string[] {
+    const visited = new Set<string>();
+    const result: string[] = [];
+
+    const visit = (id: string): void => {
+      if (visited.has(id)) return;
+      visited.add(id);
+      result.push(id);
+      const childIds = this.children.get(id) ?? [];
+      for (const childId of childIds) {
+        visit(childId);
+      }
+    };
+
+    for (const node of this.nodes.values()) {
+      if (!node.parentId) {
+        visit(node.id);
+      }
+    }
+
+    return result;
+  }
+
+  getSubtreeTokenUsage(rootId: string): number {
+    const node = this.nodes.get(rootId);
+    if (!node) return 0;
+
+    let total = node.tokenUsage;
+    const childIds = this.children.get(rootId) ?? [];
+    for (const childId of childIds) {
+      total += this.getSubtreeTokenUsage(childId);
+    }
+    return total;
+  }
+
+  getSnapshot(): { nodes: AgentNode[]; edges: CallgraphEdge[]; maxDepth: number; totalTokenUsage: number } {
+    let totalTokens = 0;
+    for (const node of this.nodes.values()) {
+      totalTokens += node.tokenUsage;
+    }
+    return {
+      nodes: this.getNodes(),
+      edges: this.getEdges(),
+      maxDepth: this.getMaxDepth(),
+      totalTokenUsage: totalTokens,
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,41 @@
+export interface CallgraphConfig {
+  maxDepth: number;
+}
+
+export type AgentStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+
+export interface AgentNodeInput {
+  id: string;
+  name: string;
+  startedAt: number;
+  parentId?: string;
+}
+
+export interface AgentNode {
+  id: string;
+  name: string;
+  parentId?: string;
+  depth: number;
+  status: AgentStatus;
+  startedAt: number;
+  completedAt?: number;
+  tokenUsage: number;
+}
+
+export interface AgentNodeUpdate {
+  status?: AgentStatus;
+  completedAt?: number;
+  tokenUsage?: number;
+}
+
+export interface CallgraphEdge {
+  parentId: string;
+  childId: string;
+}
+
+export interface CallgraphSnapshot {
+  nodes: AgentNode[];
+  edges: CallgraphEdge[];
+  maxDepth: number;
+  totalTokenUsage: number;
+}

package/tests/store.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { CallgraphStore } from '../src/store.js';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+describe('CallgraphStore', () => {
+  let store: CallgraphStore;
+  let tmpDir: string;
+
+  afterEach(() => {
+    store?.close();
+    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('stores and retrieves agent nodes', () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'cg-'));
+    store = new CallgraphStore(join(tmpDir, 'callgraph.db'));
+
+    store.recordNode({
+      id: 'agent-1',
+      workflowId: 'wf-1',
+      name: 'supervisor',
+      depth: 0,
+      status: 'running',
+      startedAt: Date.now(),
+      tokenUsage: 0,
+    });
+
+    const nodes = store.getNodesByWorkflow('wf-1');
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0].name).toBe('supervisor');
+    expect(nodes[0].depth).toBe(0);
+  });
+
+  it('stores and retrieves edges', () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'cg-'));
+    store = new CallgraphStore(join(tmpDir, 'callgraph.db'));
+
+    store.recordNode({ id: 'p', workflowId: 'wf-1', name: 'parent', depth: 0, status: 'running', startedAt: Date.now(), tokenUsage: 0 });
+    store.recordNode({ id: 'c', workflowId: 'wf-1', name: 'child', depth: 1, status: 'running', startedAt: Date.now(), tokenUsage: 0, parentId: 'p' });
+    store.recordEdge({ workflowId: 'wf-1', parentId: 'p', childId: 'c' });
+
+    const edges = store.getEdgesByWorkflow('wf-1');
+    expect(edges).toHaveLength(1);
+    expect(edges[0].parentId).toBe('p');
+    expect(edges[0].childId).toBe('c');
+  });
+
+  it('retrieves full snapshot for a workflow', () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'cg-'));
+    store = new CallgraphStore(join(tmpDir, 'callgraph.db'));
+
+    store.recordNode({ id: 'root', workflowId: 'wf-2', name: 'root', depth: 0, status: 'completed', startedAt: 1000, tokenUsage: 500 });
+    store.recordNode({ id: 'w1', workflowId: 'wf-2', name: 'worker', depth: 1, status: 'completed', startedAt: 2000, tokenUsage: 300, parentId: 'root' });
+    store.recordEdge({ workflowId: 'wf-2', parentId: 'root', childId: 'w1' });
+
+    const snapshot = store.getSnapshot('wf-2');
+    expect(snapshot.nodes).toHaveLength(2);
+    expect(snapshot.edges).toHaveLength(1);
+    expect(snapshot.totalTokenUsage).toBe(800);
+  });
+
+  it('lists workflows with node counts', () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'cg-'));
+    store = new CallgraphStore(join(tmpDir, 'callgraph.db'));
+
+    store.recordNode({ id: 'a', workflowId: 'wf-1', name: 'a', depth: 0, status: 'completed', startedAt: 1000, tokenUsage: 0 });
+    store.recordNode({ id: 'b', workflowId: 'wf-1', name: 'b', depth: 1, status: 'completed', startedAt: 2000, tokenUsage: 0, parentId: 'a' });
+    store.recordNode({ id: 'c', workflowId: 'wf-2', name: 'c', depth: 0, status: 'running', startedAt: 3000, tokenUsage: 0 });
+
+    const workflows = store.listWorkflows();
+    expect(workflows).toHaveLength(2);
+    const wf1 = workflows.find((w) => w.workflowId === 'wf-1');
+    expect(wf1?.nodeCount).toBe(2);
+  });
+});

package/tests/tracker.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect } from 'vitest';
+import { CallgraphTracker } from '../src/tracker.js';
+import type { AgentNode } from '../src/types.js';
+
+describe('CallgraphTracker', () => {
+  it('tracks root agent with no parent', () => {
+    const tracker = new CallgraphTracker({ maxDepth: 10 });
+    tracker.addAgent({ id: 'root', name: 'orchestrator', startedAt: Date.now() });
+
+    const nodes = tracker.getNodes();
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0].id).toBe('root');
+    expect(nodes[0].depth).toBe(0);
+  });
+
+  it('tracks parent-child edges', () => {
+    const tracker = new CallgraphTracker({ maxDepth: 10 });
+    tracker.addAgent({ id: 'root', name: 'supervisor', startedAt: Date.now() });
+    tracker.addAgent({ id: 'worker-1', name: 'coder', startedAt: Date.now(), parentId: 'root' });
+    tracker.addAgent({ id: 'worker-2', name: 'reviewer', startedAt: Date.now(), parentId: 'root' });
+
+    const edges = tracker.getEdges();
+    expect(edges).toHaveLength(2);
+    expect(edges[0]).toEqual({ parentId: 'root', childId: 'worker-1' });
+    expect(edges[1]).toEqual({ parentId: 'root', childId: 'worker-2' });
+
+    const children = tracker.getChildren('root');
+    expect(children.map((c) => c.id)).toEqual(['worker-1', 'worker-2']);
+  });
+
+  it('computes depth correctly for nested agents', () => {
+    const tracker = new CallgraphTracker({ maxDepth: 10 });
+    tracker.addAgent({ id: 'a', name: 'root', startedAt: Date.now() });
+    tracker.addAgent({ id: 'b', name: 'mid', startedAt: Date.now(), parentId: 'a' });
+    tracker.addAgent({ id: 'c', name: 'leaf', startedAt: Date.now(), parentId: 'b' });
+
+    const leaf = tracker.getNode('c');
+    expect(leaf?.depth).toBe(2);
+    expect(tracker.getMaxDepth()).toBe(2);
+  });
+
+  it('rejects agents exceeding max depth', () => {
+    const tracker = new CallgraphTracker({ maxDepth: 2 });
+    tracker.addAgent({ id: 'a', name: 'root', startedAt: Date.now() });
+    tracker.addAgent({ id: 'b', name: 'mid', startedAt: Date.now(), parentId: 'a' });
+    tracker.addAgent({ id: 'c', name: 'leaf', startedAt: Date.now(), parentId: 'b' });
+
+    expect(() =>
+      tracker.addAgent({ id: 'd', name: 'too-deep', startedAt: Date.now(), parentId: 'c' }),
+    ).toThrow('depth limit');
+  });
+
+  it('updates agent status and token usage', () => {
+    const tracker = new CallgraphTracker({ maxDepth: 10 });
+    tracker.addAgent({ id: 'a', name: 'worker', startedAt: Date.now() });
+    tracker.updateAgent('a', { status: 'completed', tokenUsage: 1500, completedAt: Date.now() });
+
+    const node = tracker.getNode('a');
+    expect(node?.status).toBe('completed');
+    expect(node?.tokenUsage).toBe(1500);
+  });
+
+  it('returns topological order', () => {
+    const tracker = new CallgraphTracker({ maxDepth: 10 });
+    tracker.addAgent({ id: 'root', name: 'root', startedAt: Date.now() });
+    tracker.addAgent({ id: 'child-1', name: 'c1', startedAt: Date.now(), parentId: 'root' });
+    tracker.addAgent({ id: 'child-2', name: 'c2', startedAt: Date.now(), parentId: 'root' });
+    tracker.addAgent({ id: 'grandchild', name: 'gc', startedAt: Date.now(), parentId: 'child-1' });
+
+    const order = tracker.topologicalOrder();
+    const rootIdx = order.indexOf('root');
+    const c1Idx = order.indexOf('child-1');
+    const gcIdx = order.indexOf('grandchild');
+    expect(rootIdx).toBeLessThan(c1Idx);
+    expect(c1Idx).toBeLessThan(gcIdx);
+  });
+
+  it('computes aggregate token usage for subtree', () => {
+    const tracker = new CallgraphTracker({ maxDepth: 10 });
+    tracker.addAgent({ id: 'root', name: 'root', startedAt: Date.now() });
+    tracker.addAgent({ id: 'c1', name: 'c1', startedAt: Date.now(), parentId: 'root' });
+    tracker.addAgent({ id: 'c2', name: 'c2', startedAt: Date.now(), parentId: 'root' });
+    tracker.updateAgent('root', { tokenUsage: 100 });
+    tracker.updateAgent('c1', { tokenUsage: 200 });
+    tracker.updateAgent('c2', { tokenUsage: 300 });
+
+    expect(tracker.getSubtreeTokenUsage('root')).toBe(600);
+    expect(tracker.getSubtreeTokenUsage('c1')).toBe(200);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}