@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/teams/registry.js

@@ -1,56 +1,139 @@
+/**
+ * Team registry.
+ *
+ * Manages the persistent registry of named teams stored in registry.json
+ * under the teams data directory. Provides CRUD operations for team metadata
+ * (creation timestamp and optional description).
+ */
 import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
 import * as path from 'path';
-import { resolveBaseDir } from './persistence.js';
+import { randomBytes } from 'crypto';
+import lockfile from 'proper-lockfile';
+import { getUserAgentsDir } from '../state.js';
 async function registryPath() {
-    const base = await resolveBaseDir();
-    return path.join(base, 'registry.json');
+    return path.join(getUserAgentsDir(), 'teams', 'registry.json');
 }
+/**
+ * Atomic JSON write: writes to a unique sibling tmp file then renames over
+ * the target. rename(2) is atomic on POSIX, so a crashed write leaves the
+ * old file untouched instead of producing a half-written registry that
+ * loadTeams() would reject.
+ */
+async function atomicWriteJson(p, data) {
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    const tmp = `${p}.tmp.${process.pid}.${randomBytes(4).toString('hex')}`;
+    const body = JSON.stringify(data, null, 2);
+    await fs.writeFile(tmp, body);
+    try {
+        await fs.rename(tmp, p);
+    }
+    catch (err) {
+        await fs.unlink(tmp).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Run `fn` while holding an exclusive cross-process lock on the registry
+ * file. proper-lockfile requires the target to exist, so we touch it first.
+ * Stale locks (from crashed callers) auto-expire after `stale` ms.
+ */
+async function withRegistryLock(p, fn) {
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    if (!fsSync.existsSync(p)) {
+        // Use 'wx' so a concurrent caller doesn't clobber data written between
+        // our existsSync check and writeFile.
+        try {
+            await fs.writeFile(p, '{}', { flag: 'wx' });
+        }
+        catch (err) {
+            if (err && err.code !== 'EEXIST')
+                throw err;
+        }
+    }
+    const release = await lockfile.lock(p, {
+        retries: { retries: 60, minTimeout: 25, maxTimeout: 250, factor: 1.5 },
+        stale: 10_000,
+    });
+    try {
+        return await fn();
+    }
+    finally {
+        await release();
+    }
+}
+/**
+ * Load all teams from the registry file. Returns an empty object only when
+ * the file does not exist. A malformed file is a hard error — silently
+ * returning {} would let any caller wipe the user's registry on the next
+ * write, which is exactly the data-loss path we are trying to close.
+ */
 export async function loadTeams() {
+    const p = await registryPath();
+    let raw;
+    try {
+        raw = await fs.readFile(p, 'utf-8');
+    }
+    catch (err) {
+        if (err && err.code === 'ENOENT')
+            return {};
+        throw err;
+    }
     try {
-        const raw = await fs.readFile(await registryPath(), 'utf-8');
         return JSON.parse(raw);
     }
-    catch {
-        return {};
+    catch (err) {
+        throw new Error(`Team registry corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
     }
 }
 async function saveTeams(reg) {
     const p = await registryPath();
-    await fs.mkdir(path.dirname(p), { recursive: true });
-    await fs.writeFile(p, JSON.stringify(reg, null, 2));
+    await atomicWriteJson(p, reg);
 }
+/** Create a new team. Throws if a team with the same name already exists. */
 export async function createTeam(name, description) {
-    const reg = await loadTeams();
-    if (reg[name]) {
-        throw new Error(`Team '${name}' already exists`);
-    }
-    const meta = {
-        created_at: new Date().toISOString(),
-        ...(description ? { description } : {}),
-    };
-    reg[name] = meta;
-    await saveTeams(reg);
-    return meta;
+    const p = await registryPath();
+    return withRegistryLock(p, async () => {
+        const reg = await loadTeams();
+        if (reg[name]) {
+            throw new Error(`Team '${name}' already exists`);
+        }
+        const meta = {
+            created_at: new Date().toISOString(),
+            ...(description ? { description } : {}),
+        };
+        reg[name] = meta;
+        await saveTeams(reg);
+        return meta;
+    });
 }
+/** Return existing team metadata or create a new team if it does not exist. */
 export async function ensureTeam(name) {
-    const reg = await loadTeams();
-    if (reg[name])
-        return reg[name];
-    const meta = { created_at: new Date().toISOString() };
-    reg[name] = meta;
-    await saveTeams(reg);
-    return meta;
+    const p = await registryPath();
+    return withRegistryLock(p, async () => {
+        const reg = await loadTeams();
+        if (reg[name])
+            return reg[name];
+        const meta = { created_at: new Date().toISOString() };
+        reg[name] = meta;
+        await saveTeams(reg);
+        return meta;
+    });
 }
+/** Remove a team from the registry. Returns false if the team did not exist. */
 export async function removeTeam(name) {
-    const reg = await loadTeams();
-    if (!reg[name])
-        return false;
-    delete reg[name];
-    await saveTeams(reg);
-    return true;
+    const p = await registryPath();
+    return withRegistryLock(p, async () => {
+        const reg = await loadTeams();
+        if (!reg[name])
+            return false;
+        delete reg[name];
+        await saveTeams(reg);
+        return true;
+    });
 }
+/** Check whether a team with the given name exists in the registry. */
 export async function teamExists(name) {
     const reg = await loadTeams();
     return Boolean(reg[name]);
 }
-//# sourceMappingURL=registry.js.map

package/dist/lib/teams/summarizer.d.ts

@@ -1,3 +1,4 @@
+/** Event type priority tiers for filtering. Higher tiers surface more important events. */
 export declare const PRIORITY: Record<string, string[]>;
 /**
  * Collapse sequential events of the same type into summary entries.
@@ -8,7 +9,9 @@ export declare function collapseEvents(events: any[], maxEvents?: number): any[]
  * Get a breakdown of tool calls by type.
  */
 export declare function getToolBreakdown(events: any[]): Record<string, number>;
+/** Group consecutive events of the same type into combined entries with counts and truncated content. */
 export declare function groupAndFlattenEvents(events: any[]): any[];
+/** Accumulated summary of an agent's activity: files touched, tools used, errors, and final message. */
 export declare class AgentSummary {
     agentId: string;
     agentType: string;
@@ -31,10 +34,18 @@ export declare class AgentSummary {
     toDict(detailLevel?: 'brief' | 'standard' | 'detailed'): any;
     private truncate;
 }
+/** Build an AgentSummary by walking all events and accumulating file ops, tool calls, errors, and messages. */
 export declare function summarizeEvents(agentId: string, agentType: string, status: string, events: any[], duration?: string | null): AgentSummary;
+/**
+ * Compute the delta of new activity since a given point in time (ISO timestamp)
+ * or event index. Used for incremental status polling.
+ */
 export declare function getDelta(agentId: string, agentType: string, status: string, events: any[], since?: string | number): any;
+/** Filter events to only those in the specified priority tiers (defaults to critical + important). */
 export declare function filterEventsByPriority(events: any[], includeLevels?: string[] | null): any[];
+/** Return the event type of the last tool-related or significant event, or null. */
 export declare function getLastTool(events: any[]): string | null;
+/** Lightweight status snapshot with counts, recent commands, and error flag. */
 export interface QuickStatus {
     agent_id: string;
     agent_type: string;
@@ -48,11 +59,14 @@ export interface QuickStatus {
     has_errors: boolean;
     last_message: string | null;
 }
+/** Extract all tool_use events as {tool, args} pairs. */
 export declare function getToolUses(events: any[]): Array<{
     tool: string;
     args: any;
 }>;
+/** Extract the last N complete messages from the event stream, joining streaming deltas. */
 export declare function getLastMessages(events: any[], count?: number): string[];
+/** Build a lightweight QuickStatus snapshot from agent events. */
 export declare function getQuickStatus(agentId: string, agentType: string, status: string, events: any[]): QuickStatus;
+/** Produce a one-line human-readable status summary string (e.g. "Running, modified 3 files, used bash 5 times"). */
 export declare function getStatusSummary(agentId: string, agentType: string, status: string, events: any[], duration?: string | null): string;
-//# sourceMappingURL=summarizer.d.ts.map

package/dist/lib/teams/summarizer.js

@@ -19,6 +19,7 @@ function extractErrorFromRawEvents(events, maxChars = 500) {
     }
     return null;
 }
+/** Event type priority tiers for filtering. Higher tiers surface more important events. */
 export const PRIORITY = {
     critical: [
         'error',
@@ -146,6 +147,7 @@ export function getToolBreakdown(events) {
     }
     return breakdown;
 }
+/** Group consecutive events of the same type into combined entries with counts and truncated content. */
 export function groupAndFlattenEvents(events) {
     if (events.length === 0)
         return [];
@@ -254,6 +256,7 @@ export function groupAndFlattenEvents(events) {
     }
     return grouped;
 }
+/** Accumulated summary of an agent's activity: files touched, tools used, errors, and final message. */
 export class AgentSummary {
     agentId;
     agentType;
@@ -335,6 +338,7 @@ export class AgentSummary {
         return text.substring(0, maxLen - 3) + '...';
     }
 }
+/** Build an AgentSummary by walking all events and accumulating file ops, tool calls, errors, and messages. */
 export function summarizeEvents(agentId, agentType, status, events, duration = null) {
     const summary = new AgentSummary(agentId, agentType, status, duration, events.length);
     summary.eventsCache = events;
@@ -467,6 +471,10 @@ export function summarizeEvents(agentId, agentType, status, events, duration = n
     }
     return summary;
 }
+/**
+ * Compute the delta of new activity since a given point in time (ISO timestamp)
+ * or event index. Used for incremental status polling.
+ */
 export function getDelta(agentId, agentType, status, events, since // Optional: ISO timestamp (string) or event index (number)
 ) {
     // Filter events by timestamp (string) or index (number)
@@ -535,6 +543,7 @@ export function getDelta(agentId, agentType, status, events, since // Optional:
         new_errors: summary.errors,
     };
 }
+/** Filter events to only those in the specified priority tiers (defaults to critical + important). */
 export function filterEventsByPriority(events, includeLevels = null) {
     if (!includeLevels) {
         includeLevels = ['critical', 'important'];
@@ -548,6 +557,7 @@ export function filterEventsByPriority(events, includeLevels = null) {
     }
     return events.filter(e => allowedTypes.has(e.type));
 }
+/** Return the event type of the last tool-related or significant event, or null. */
 export function getLastTool(events) {
     if (events.length === 0)
         return null;
@@ -559,6 +569,7 @@ export function getLastTool(events) {
     }
     return null;
 }
+/** Extract all tool_use events as {tool, args} pairs. */
 export function getToolUses(events) {
     const toolUses = [];
     for (const event of events) {
@@ -570,6 +581,7 @@ export function getToolUses(events) {
     }
     return toolUses;
 }
+/** Extract the last N complete messages from the event stream, joining streaming deltas. */
 export function getLastMessages(events, count = 3) {
     const messages = [];
     let currentBuffer = '';
@@ -607,6 +619,7 @@ export function getLastMessages(events, count = 3) {
     }
     return messages.slice(-count);
 }
+/** Build a lightweight QuickStatus snapshot from agent events. */
 export function getQuickStatus(agentId, agentType, status, events) {
     const filesCreatedSet = new Set();
     const filesModifiedSet = new Set();
@@ -693,6 +706,7 @@ export function getQuickStatus(agentId, agentType, status, events) {
         last_message: lastMessage,
     };
 }
+/** Produce a one-line human-readable status summary string (e.g. "Running, modified 3 files, used bash 5 times"). */
 export function getStatusSummary(agentId, agentType, status, events, duration = null) {
     if (events.length === 0) {
         if (status === 'running') {
@@ -763,4 +777,3 @@ export function getStatusSummary(agentId, agentType, status, events, duration =
     }
     return parts.join(', ');
 }
-//# sourceMappingURL=summarizer.js.map

package/dist/lib/teams/supervisor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * DAG supervisor — the continuous dispatch loop that makes the Factory
+ * dynamic.
+ *
+ * `teams start --watch` and `factory run` both use this. Each wave:
+ *   1. call startReady(team) to fire any now-ready teammates
+ *   2. listByTask(team) to count pending / running / done / failed
+ *   3. emit one status event (via the caller's callback)
+ *   4. exit when pending + running == 0 (DAG drained)
+ *
+ * Why a shared function:
+ *  - the loop is the orchestration, the thing that lets any worker add
+ *    tasks mid-flight via `agents teams add` and have them picked up
+ *  - `factory run` is just `teams start --watch` with factory-flavored
+ *    presentation; keeping them in sync avoids drift
+ *
+ * The caller supplies a presenter callback so the same loop can drive
+ * terminal output, json-per-wave output, or a TUI.
+ */
+import type { AgentManager, AgentProcess } from './agents.js';
+export interface WaveSummary {
+    wave: number;
+    timestamp: string;
+    team: string;
+    launched: AgentProcess[];
+    pending: number;
+    running: number;
+    completed: number;
+    failed: number;
+    drained: boolean;
+}
+export interface SupervisorOptions {
+    team: string;
+    intervalMs?: number;
+    maxWaves?: number;
+    /** Called once per wave. Return false to stop the loop gracefully. */
+    onWave: (summary: WaveSummary) => void | Promise<void> | boolean | Promise<boolean>;
+}
+export interface SupervisorResult {
+    waves: number;
+    stoppedBy: 'drained' | 'max-waves' | 'signal' | 'callback';
+    elapsed_ms: number;
+}
+/**
+ * Run the continuous DAG dispatcher until the team drains, the caller
+ * returns false from onWave, or SIGINT/SIGTERM arrives.
+ */
+export declare function runSupervisor(mgr: AgentManager, opts: SupervisorOptions): Promise<SupervisorResult>;

package/dist/lib/teams/supervisor.js

@@ -0,0 +1,73 @@
+/**
+ * Run the continuous DAG dispatcher until the team drains, the caller
+ * returns false from onWave, or SIGINT/SIGTERM arrives.
+ */
+export async function runSupervisor(mgr, opts) {
+    const intervalMs = opts.intervalMs ?? 8000;
+    const maxWaves = opts.maxWaves ?? 1000;
+    const team = opts.team;
+    const startedAt = Date.now();
+    let stopSignal = false;
+    const onSig = () => { stopSignal = true; };
+    process.once('SIGINT', onSig);
+    process.once('SIGTERM', onSig);
+    try {
+        for (let wave = 1; wave <= maxWaves; wave++) {
+            // Pick up teammates added by other processes (e.g. the Planner's
+            // `agents teams add` calls). Without this the supervisor only ever
+            // sees teammates it created itself.
+            await mgr.rescanFromDisk();
+            const launched = await mgr.startReady(team);
+            const all = await mgr.listByTask(team);
+            let pending = 0, running = 0, completed = 0, failed = 0;
+            for (const a of all) {
+                if (a.status === 'pending')
+                    pending++;
+                else if (a.status === 'running')
+                    running++;
+                else if (a.status === 'completed')
+                    completed++;
+                else if (a.status === 'failed')
+                    failed++;
+            }
+            const summary = {
+                wave,
+                timestamp: new Date().toISOString(),
+                team,
+                launched,
+                pending,
+                running,
+                completed,
+                failed,
+                drained: pending === 0 && running === 0,
+            };
+            const keepGoing = await opts.onWave(summary);
+            if (keepGoing === false) {
+                return { waves: wave, stoppedBy: 'callback', elapsed_ms: Date.now() - startedAt };
+            }
+            // Re-check drain AFTER the callback. The callback may have added new
+            // teammates mid-flight (that's the whole point of the dynamic DAG), so
+            // trusting the pre-callback snapshot would drain prematurely. Rescan
+            // too, because the callback could have triggered a sibling process
+            // that wrote a fresh meta.json.
+            await mgr.rescanFromDisk();
+            const afterCallback = await mgr.listByTask(team);
+            const stillLive = afterCallback.some((a) => a.status === 'pending' || a.status === 'running');
+            if (!stillLive) {
+                return { waves: wave, stoppedBy: 'drained', elapsed_ms: Date.now() - startedAt };
+            }
+            if (stopSignal) {
+                return { waves: wave, stoppedBy: 'signal', elapsed_ms: Date.now() - startedAt };
+            }
+            await new Promise((r) => setTimeout(r, intervalMs));
+            if (stopSignal) {
+                return { waves: wave, stoppedBy: 'signal', elapsed_ms: Date.now() - startedAt };
+            }
+        }
+        return { waves: maxWaves, stoppedBy: 'max-waves', elapsed_ms: Date.now() - startedAt };
+    }
+    finally {
+        process.off('SIGINT', onSig);
+        process.off('SIGTERM', onSig);
+    }
+}

package/dist/lib/template.d.ts

@@ -1,10 +1,13 @@
 /**
- * Template resolution utilities
- * Ported from agents/halo/cli/pkg/template
+ * Template resolution utilities.
+ * Ported from agents/halo/cli/pkg/template.
+ *
+ * Supports {{artifact.*}} and {{preflight.*}} placeholder patterns used in
+ * artifact action input mappings.
  */
 /**
- * Resolve template placeholders with artifact and preflight data
- * Replaces {{artifact.*}} and {{preflight.*}} patterns
+ * Resolve template placeholders with artifact and preflight data.
+ * Replaces {{artifact.*}} and {{preflight.*}} patterns.
  *
  * @param tmpl - Template string with placeholders
  * @param artifact - Map of artifact key-value pairs
@@ -13,7 +16,7 @@
  */
 export declare function resolveTemplate(tmpl: string, artifact: Record<string, string>, preflight: Record<string, string | string[] | unknown>): string;
 /**
- * Extract all template variables from a template string
+ * Extract all template variables from a template string.
  * @param tmpl - Template string
  * @returns Object with artifact and preflight variable names
  */
@@ -21,4 +24,3 @@ export declare function extractTemplateVariables(tmpl: string): {
     artifact: string[];
     preflight: string[];
 };
-//# sourceMappingURL=template.d.ts.map

package/dist/lib/template.js

@@ -1,10 +1,13 @@
 /**
- * Template resolution utilities
- * Ported from agents/halo/cli/pkg/template
+ * Template resolution utilities.
+ * Ported from agents/halo/cli/pkg/template.
+ *
+ * Supports {{artifact.*}} and {{preflight.*}} placeholder patterns used in
+ * artifact action input mappings.
  */
 /**
- * Resolve template placeholders with artifact and preflight data
- * Replaces {{artifact.*}} and {{preflight.*}} patterns
+ * Resolve template placeholders with artifact and preflight data.
+ * Replaces {{artifact.*}} and {{preflight.*}} patterns.
  *
  * @param tmpl - Template string with placeholders
  * @param artifact - Map of artifact key-value pairs
@@ -34,7 +37,7 @@ export function resolveTemplate(tmpl, artifact, preflight) {
     return result;
 }
 /**
- * Extract all template variables from a template string
+ * Extract all template variables from a template string.
  * @param tmpl - Template string
  * @returns Object with artifact and preflight variable names
  */
@@ -54,4 +57,3 @@ export function extractTemplateVariables(tmpl) {
     }
     return { artifact, preflight };
 }
-//# sourceMappingURL=template.js.map