@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/lock.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `agents.lock` — a deterministic SHA-256 manifest of the resolved resource set
+ * at a project root, plus the `--frozen` verification that fails closed on any
+ * drift. This is the reproducible-CI slice of the governance work (#337); org
+ * version pins and bundle signing are deferred follow-ups.
+ *
+ * Design:
+ *  - Content hashing REUSES `fingerprintDir` / `fingerprintFile`
+ *    (src/lib/staleness/fingerprint.ts) — the same two-tier fingerprinter every
+ *    staleness checker uses. No new recursive file walker is introduced here.
+ *  - The resource SET is the layered, resolved source union (project > user >
+ *    system > extras), the same precedence `resolveResource` / `syncResourcesToVersion`
+ *    read from. It is enumerated agent-independently on purpose: the lock must be
+ *    reproducible on a fresh CI checkout that has no installed agent VERSIONS, so
+ *    it snapshots the SOURCES sync copies FROM, not any per-version home.
+ *
+ * Lock shape (JSON): `{ "version": 1, "resources": { "<relpath>": "<sha256>" } }`,
+ * keys sorted so the file is byte-stable across machines and runs.
+ */
+export declare const LOCK_FILENAME = "agents.lock";
+export declare const LOCK_VERSION: 1;
+/**
+ * Resource kinds captured by the lock — the file/dir-backed layered resources
+ * shared across every agent. Presence-only kinds handled specially by the sync
+ * differ (plugins/promptcuts) are intentionally out of this first slice.
+ */
+export declare const LOCK_KINDS: readonly ["commands", "skills", "hooks", "rules", "mcp", "permissions", "subagents"];
+/** The on-disk lockfile: relpath -> sha256 hex digest, keys sorted. */
+export interface AgentsLock {
+    version: typeof LOCK_VERSION;
+    resources: Record<string, string>;
+}
+/**
+ * One resolved resource to fingerprint. `path` is an absolute file or directory;
+ * `key` is the stable relpath prefix under which its hashes are recorded
+ * (e.g. `skills/debug` for a directory, `commands/plan.md` for a single file).
+ */
+export interface LockSource {
+    path: string;
+    key: string;
+}
+/** Added/removed/changed keys between an expected lock and the live resources. */
+export interface LockDiff {
+    /** Present in the live resources, absent from the lock. */
+    added: string[];
+    /** Present in the lock, absent from the live resources. */
+    removed: string[];
+    /** Present in both but the sha256 differs. */
+    changed: string[];
+}
+/**
+ * Hash every resolved source into a flat `relpath -> sha256` map. Directories are
+ * expanded with `fingerprintDir` (every contained file, sorted); single files use
+ * `fingerprintFile`. Unreadable / missing sources are skipped — enumeration only
+ * ever hands us paths that existed at scan time.
+ */
+export declare function hashLockSources(sources: LockSource[]): Record<string, string>;
+/** Build a fully-sorted lock object from a resolved source set. */
+export declare function buildLock(sources: LockSource[]): AgentsLock;
+/** Serialise a lock to the canonical, sorted, newline-terminated JSON form. */
+export declare function serializeLock(lock: AgentsLock): string;
+/** Absolute path to the lockfile for a project root. */
+export declare function lockPath(projectRoot: string): string;
+/**
+ * Read + validate an existing lock. Returns null ONLY when the file is absent —
+ * a present-but-malformed lock throws, so `--frozen` fails closed instead of
+ * silently treating corruption as "no lock".
+ */
+export declare function readLock(projectRoot: string): AgentsLock | null;
+/** Write the lock to `<projectRoot>/agents.lock`, returning the path written. */
+export declare function writeLock(projectRoot: string, lock: AgentsLock): string;
+/** Diff a recorded lock against a freshly-computed one. */
+export declare function diffLock(expected: AgentsLock, actual: AgentsLock): LockDiff;
+/** True when a diff has no added/removed/changed entries. */
+export declare function lockDiffIsClean(diff: LockDiff): boolean;
+/** Verify a recorded lock against the live resolved sources. */
+export declare function verifyLock(expected: AgentsLock, sources: LockSource[]): LockDiff;
+/**
+ * The project root the lockfile lives at: the parent of the discovered project
+ * `.agents/` dir, or the cwd itself when none is found.
+ */
+export declare function resolveProjectRoot(cwd?: string): string;
+/**
+ * Enumerate the resolved resource sources for a cwd: for each lockable kind, the
+ * winning entry per name across layers (project > user > system > extras), keyed
+ * `<kind>/<entryName>`. This is a single-level `readdir` per kind dir — the
+ * recursive fingerprinting is delegated to `fingerprintDir`.
+ *
+ * Entry names keep their extension in the key, so a hook script `foo.sh` and its
+ * sidecar `foo.yaml` stay distinct (a name-stripped enumerator would collide
+ * them). Dotfiles at the kind-dir top level are skipped as noise.
+ */
+export declare function enumerateLockSources(cwd?: string): LockSource[];

package/dist/lib/lock.js

@@ -0,0 +1,207 @@
+/**
+ * `agents.lock` — a deterministic SHA-256 manifest of the resolved resource set
+ * at a project root, plus the `--frozen` verification that fails closed on any
+ * drift. This is the reproducible-CI slice of the governance work (#337); org
+ * version pins and bundle signing are deferred follow-ups.
+ *
+ * Design:
+ *  - Content hashing REUSES `fingerprintDir` / `fingerprintFile`
+ *    (src/lib/staleness/fingerprint.ts) — the same two-tier fingerprinter every
+ *    staleness checker uses. No new recursive file walker is introduced here.
+ *  - The resource SET is the layered, resolved source union (project > user >
+ *    system > extras), the same precedence `resolveResource` / `syncResourcesToVersion`
+ *    read from. It is enumerated agent-independently on purpose: the lock must be
+ *    reproducible on a fresh CI checkout that has no installed agent VERSIONS, so
+ *    it snapshots the SOURCES sync copies FROM, not any per-version home.
+ *
+ * Lock shape (JSON): `{ "version": 1, "resources": { "<relpath>": "<sha256>" } }`,
+ * keys sorted so the file is byte-stable across machines and runs.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fingerprintDir, fingerprintFile } from './staleness/fingerprint.js';
+import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from './state.js';
+export const LOCK_FILENAME = 'agents.lock';
+export const LOCK_VERSION = 1;
+/**
+ * Resource kinds captured by the lock — the file/dir-backed layered resources
+ * shared across every agent. Presence-only kinds handled specially by the sync
+ * differ (plugins/promptcuts) are intentionally out of this first slice.
+ */
+export const LOCK_KINDS = [
+    'commands',
+    'skills',
+    'hooks',
+    'rules',
+    'mcp',
+    'permissions',
+    'subagents',
+];
+/** Normalise a filesystem-relative path to POSIX separators for stable keys. */
+function toPosix(rel) {
+    return rel.split(path.sep).join('/');
+}
+/**
+ * Hash every resolved source into a flat `relpath -> sha256` map. Directories are
+ * expanded with `fingerprintDir` (every contained file, sorted); single files use
+ * `fingerprintFile`. Unreadable / missing sources are skipped — enumeration only
+ * ever hands us paths that existed at scan time.
+ */
+export function hashLockSources(sources) {
+    const out = {};
+    for (const src of sources) {
+        let stat;
+        try {
+            stat = fs.statSync(src.path);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            for (const fp of fingerprintDir(src.path)) {
+                const rel = toPosix(path.relative(src.path, fp.path));
+                out[`${src.key}/${rel}`] = fp.sha256;
+            }
+        }
+        else if (stat.isFile()) {
+            const fp = fingerprintFile(src.path);
+            if (fp)
+                out[src.key] = fp.sha256;
+        }
+    }
+    return out;
+}
+/** Build a fully-sorted lock object from a resolved source set. */
+export function buildLock(sources) {
+    return { version: LOCK_VERSION, resources: sortRecord(hashLockSources(sources)) };
+}
+/** Return a new record with keys inserted in sorted order (deterministic JSON). */
+function sortRecord(record) {
+    const out = {};
+    for (const key of Object.keys(record).sort())
+        out[key] = record[key];
+    return out;
+}
+/** Serialise a lock to the canonical, sorted, newline-terminated JSON form. */
+export function serializeLock(lock) {
+    return JSON.stringify({ version: lock.version, resources: sortRecord(lock.resources) }, null, 2) + '\n';
+}
+/** Absolute path to the lockfile for a project root. */
+export function lockPath(projectRoot) {
+    return path.join(projectRoot, LOCK_FILENAME);
+}
+/**
+ * Read + validate an existing lock. Returns null ONLY when the file is absent —
+ * a present-but-malformed lock throws, so `--frozen` fails closed instead of
+ * silently treating corruption as "no lock".
+ */
+export function readLock(projectRoot) {
+    const p = lockPath(projectRoot);
+    if (!fs.existsSync(p))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    }
+    catch (e) {
+        throw new Error(`${LOCK_FILENAME} is not valid JSON: ${e.message}`);
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error(`${LOCK_FILENAME} is malformed (expected an object).`);
+    }
+    const obj = parsed;
+    if (obj.version !== LOCK_VERSION) {
+        throw new Error(`${LOCK_FILENAME} version ${String(obj.version)} is unsupported (expected ${LOCK_VERSION}).`);
+    }
+    if (!obj.resources || typeof obj.resources !== 'object') {
+        throw new Error(`${LOCK_FILENAME} is missing a resources map.`);
+    }
+    return { version: LOCK_VERSION, resources: obj.resources };
+}
+/** Write the lock to `<projectRoot>/agents.lock`, returning the path written. */
+export function writeLock(projectRoot, lock) {
+    const p = lockPath(projectRoot);
+    fs.writeFileSync(p, serializeLock(lock));
+    return p;
+}
+/** Diff a recorded lock against a freshly-computed one. */
+export function diffLock(expected, actual) {
+    const e = expected.resources;
+    const a = actual.resources;
+    const added = [];
+    const removed = [];
+    const changed = [];
+    for (const k of Object.keys(a))
+        if (!(k in e))
+            added.push(k);
+    for (const k of Object.keys(e)) {
+        if (!(k in a))
+            removed.push(k);
+        else if (e[k] !== a[k])
+            changed.push(k);
+    }
+    added.sort();
+    removed.sort();
+    changed.sort();
+    return { added, removed, changed };
+}
+/** True when a diff has no added/removed/changed entries. */
+export function lockDiffIsClean(diff) {
+    return diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0;
+}
+/** Verify a recorded lock against the live resolved sources. */
+export function verifyLock(expected, sources) {
+    return diffLock(expected, buildLock(sources));
+}
+/**
+ * The project root the lockfile lives at: the parent of the discovered project
+ * `.agents/` dir, or the cwd itself when none is found.
+ */
+export function resolveProjectRoot(cwd = process.cwd()) {
+    const projectDir = getProjectAgentsDir(cwd);
+    return projectDir ? path.dirname(projectDir) : path.resolve(cwd);
+}
+/**
+ * Enumerate the resolved resource sources for a cwd: for each lockable kind, the
+ * winning entry per name across layers (project > user > system > extras), keyed
+ * `<kind>/<entryName>`. This is a single-level `readdir` per kind dir — the
+ * recursive fingerprinting is delegated to `fingerprintDir`.
+ *
+ * Entry names keep their extension in the key, so a hook script `foo.sh` and its
+ * sidecar `foo.yaml` stay distinct (a name-stripped enumerator would collide
+ * them). Dotfiles at the kind-dir top level are skipped as noise.
+ */
+export function enumerateLockSources(cwd = process.cwd()) {
+    const roots = [];
+    const projectDir = getProjectAgentsDir(cwd);
+    if (projectDir)
+        roots.push(projectDir);
+    roots.push(getUserAgentsDir());
+    roots.push(getSystemAgentsDir());
+    for (const extra of getEnabledExtraRepos())
+        roots.push(extra.dir);
+    const sources = [];
+    const seen = new Set();
+    for (const kind of LOCK_KINDS) {
+        for (const root of roots) {
+            const kindDir = path.join(root, kind);
+            let entries;
+            try {
+                entries = fs.readdirSync(kindDir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.name.startsWith('.'))
+                    continue;
+                const key = `${kind}/${entry.name}`;
+                if (seen.has(key))
+                    continue; // project layer wins on same name
+                seen.add(key);
+                sources.push({ path: path.join(kindDir, entry.name), key });
+            }
+        }
+    }
+    return sources.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}

package/dist/lib/loop.js

@@ -26,6 +26,8 @@ import { buildExecCommand, buildExecEnv } from './exec.js';
 import { extractUsageEvents } from './budget/enforce.js';
 import { parseTimeout } from './routines.js';
 import { writeCheckpoint } from './checkpoint.js';
+import { mailboxDir } from './mailbox.js';
+import { composeWin32CommandLine } from './platform/index.js';
 const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** Path to a run's loop-signal.json. */
 export function loopSignalPath(runDir) {
@@ -129,8 +131,14 @@ export function defaultRunIteration(options) {
     const cwd = execOptions.cwd || process.cwd();
     const model = execOptions.model ?? `${execOptions.agent}-default`;
     return new Promise((resolve, reject) => {
+        // DEP0190-safe shell spawn: on the win32 shell path compose ONE fully-quoted
+        // command line and pass an EMPTY args array (see composeWin32CommandLine) so
+        // Node never concatenates the args array — which carries the re-injected
+        // prompt — into the cmd.exe line unescaped.
         const useShell = process.platform === 'win32' && (!path.isAbsolute(executable) || executable.endsWith('.cmd'));
-        const child = spawn(executable, args, {
+        const spawnCommand = useShell ? composeWin32CommandLine(executable, args) : executable;
+        const spawnArgs = useShell ? [] : args;
+        const child = spawn(spawnCommand, spawnArgs, {
             cwd,
             stdio: ['inherit', 'pipe', 'pipe'],
             env,
@@ -207,6 +215,9 @@ export async function runLoop(execOptions, loop, ctx, deps) {
         process.stderr.write(`[loop] WARNING: cross-iteration conversation continuity applies to claude only. ` +
             `Each ${ctx.agent} iteration runs as an independent fresh conversation (no /continue handoff).\n`);
     }
+    // Surface the run-level mailbox id (otherwise undiscoverable — runId is not in
+    // the session registry) so an operator can message the loop mid-flight.
+    process.stderr.write(`[loop] mailbox: agents message ${ctx.runId} "<text>"\n`);
     let tokens = ctx.startTokens ?? 0;
     let lastSignal;
     let stopSignal = false;
@@ -271,6 +282,10 @@ export async function runLoop(execOptions, loop, ctx, deps) {
                     AGENTS_RUN_DIR: ctx.runDir,
                     AGENTS_LOOP_SIGNAL: loopSignalPath(ctx.runDir),
                     AGENTS_LOOP_ITERATION: String(iteration),
+                    // Every iteration is a fresh session, so key the mailbox by the stable
+                    // run id — one box for the whole loop. Overrides the per-iteration
+                    // AGENTS_MAILBOX_DIR that buildExecEnv would derive from sessionId.
+                    AGENTS_MAILBOX_DIR: mailboxDir(ctx.runId),
                 },
             };
             let result;

package/dist/lib/machine-id.d.ts

@@ -0,0 +1,21 @@
+/**
+ * This machine's stable, human-readable id. Lives in a dependency-free leaf so
+ * low-level modules (state.ts) can key per-device paths off it without importing
+ * the secrets/session-sync layer (which would create a cycle).
+ */
+/**
+ * Normalize a raw hostname into a stable device id: first label only,
+ * lowercased, non-alphanumerics collapsed to hyphens. `zion.tail…ts.net` and
+ * `ZION` both become `zion`. The single source for this transform — machineId()
+ * and cross-machine session grouping must agree or the local machine won't
+ * match its own registry key.
+ */
+export declare function normalizeHost(raw: string): string;
+/**
+ * This machine's stable, human-readable id, used as its R2 sync prefix, session
+ * mirror directory, `agents devices` self-key, and per-device config folder.
+ * Tailnet hostnames (zion, yosemite-s0, mac-mini) are already unique and
+ * readable; we lowercase and strip any domain suffix. Overridable via
+ * AGENTS_SYNC_MACHINE_ID for tests and unusual setups.
+ */
+export declare function machineId(): string;

package/dist/lib/machine-id.js

@@ -0,0 +1,26 @@
+/**
+ * This machine's stable, human-readable id. Lives in a dependency-free leaf so
+ * low-level modules (state.ts) can key per-device paths off it without importing
+ * the secrets/session-sync layer (which would create a cycle).
+ */
+import * as os from 'os';
+/**
+ * Normalize a raw hostname into a stable device id: first label only,
+ * lowercased, non-alphanumerics collapsed to hyphens. `zion.tail…ts.net` and
+ * `ZION` both become `zion`. The single source for this transform — machineId()
+ * and cross-machine session grouping must agree or the local machine won't
+ * match its own registry key.
+ */
+export function normalizeHost(raw) {
+    return raw.split('.')[0].trim().toLowerCase().replace(/[^a-z0-9_-]/g, '-') || 'unknown';
+}
+/**
+ * This machine's stable, human-readable id, used as its R2 sync prefix, session
+ * mirror directory, `agents devices` self-key, and per-device config folder.
+ * Tailnet hostnames (zion, yosemite-s0, mac-mini) are already unique and
+ * readable; we lowercase and strip any domain suffix. Overridable via
+ * AGENTS_SYNC_MACHINE_ID for tests and unusual setups.
+ */
+export function machineId() {
+    return normalizeHost(process.env.AGENTS_SYNC_MACHINE_ID || os.hostname());
+}

package/dist/lib/mailbox-target.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Resolve an `agents message <target>` argument to exactly one destination —
+ * a cloud task, one live local/teams/loop agent, or an error. The anti-misroute
+ * rule lives here: a target that matches zero or more-than-one live agent is
+ * NEVER guessed; the caller reports it. Pure (no I/O) so it is unit-testable.
+ */
+import type { ActiveSession } from './session/active.js';
+export type MessageResolution = {
+    kind: 'cloud';
+    id: string;
+} | {
+    kind: 'local';
+    id: string;
+} | {
+    kind: 'none';
+} | {
+    kind: 'ambiguous';
+    candidates: Array<{
+        id: string;
+        label: string;
+    }>;
+};
+/**
+ * The mailbox id a live session's box is keyed by. Teams stamp a durable
+ * `agentId` (== the Claude session id for Claude teammates); a bare run has
+ * only its `sessionId`. The spawn-time `AGENTS_MAILBOX_DIR` wiring must key the
+ * box by this same id — this is the single source of truth for both sides.
+ */
+export declare function mailboxIdForActiveSession(s: ActiveSession): string | undefined;
+/**
+ * Resolve `target` against the live sessions. Exact id matches win over prefix
+ * matches; results are de-duped by canonical mailbox id (collapsed subagents
+ * share one). `isCloudTask` is consulted first so a cloud task id routes to the
+ * cloud provider.
+ */
+export declare function resolveMessageTarget(target: string, sessions: ActiveSession[], isCloudTask: (id: string) => boolean): MessageResolution;

package/dist/lib/mailbox-target.js

@@ -0,0 +1,45 @@
+/**
+ * The mailbox id a live session's box is keyed by. Teams stamp a durable
+ * `agentId` (== the Claude session id for Claude teammates); a bare run has
+ * only its `sessionId`. The spawn-time `AGENTS_MAILBOX_DIR` wiring must key the
+ * box by this same id — this is the single source of truth for both sides.
+ */
+export function mailboxIdForActiveSession(s) {
+    return s.agentId ?? s.sessionId;
+}
+function labelFor(s) {
+    return s.label ?? s.topic ?? s.teamName ?? s.host ?? s.context;
+}
+/**
+ * Resolve `target` against the live sessions. Exact id matches win over prefix
+ * matches; results are de-duped by canonical mailbox id (collapsed subagents
+ * share one). `isCloudTask` is consulted first so a cloud task id routes to the
+ * cloud provider.
+ */
+export function resolveMessageTarget(target, sessions, isCloudTask) {
+    if (isCloudTask(target))
+        return { kind: 'cloud', id: target };
+    // An empty target would make every `startsWith` prefix match — never guess.
+    if (target.length === 0)
+        return { kind: 'none' };
+    const exact = sessions.filter((s) => s.sessionId === target || s.agentId === target);
+    const chosen = exact.length > 0
+        ? exact
+        : sessions.filter((s) => Boolean(s.sessionId?.startsWith(target)) || Boolean(s.agentId?.startsWith(target)));
+    // De-dupe by canonical mailbox id (one box per logical agent).
+    const byId = new Map();
+    for (const s of chosen) {
+        const id = mailboxIdForActiveSession(s);
+        if (id && !byId.has(id))
+            byId.set(id, s);
+    }
+    const ids = [...byId.keys()];
+    if (ids.length === 0)
+        return { kind: 'none' };
+    if (ids.length === 1)
+        return { kind: 'local', id: ids[0] };
+    return {
+        kind: 'ambiguous',
+        candidates: [...byId.entries()].map(([id, s]) => ({ id, label: labelFor(s) })),
+    };
+}

package/dist/lib/mailbox.d.ts

@@ -0,0 +1,47 @@
+/** A single mailbox message. `text` may embed `host:/path` clip tokens. */
+export interface MailboxMessage {
+    /** Unique, time-sortable id. Also the on-disk filename stem. */
+    msgId: string;
+    /** The mailboxId this message is addressed to (anti-misroute stamp). */
+    to: string;
+    /** Who sent it (operator label / agent id / host). Optional. */
+    from?: string;
+    /** ISO-8601 creation time. */
+    ts: string;
+    /** The message body. */
+    text: string;
+}
+/**
+ * A mailboxId must be a single, separator-free path segment. Real ids (session
+ * UUID / teams agentId / loop runId) already satisfy this; rejecting anything
+ * else fails loud instead of silently misrouting — a message whose id contained
+ * a `/` would nest under a different dir than the `to` stamp it is matched
+ * against, and would be dropped with no error. Also blocks `.`/`..` traversal
+ * once `agents message` starts accepting external target ids.
+ */
+export declare function isValidMailboxId(mailboxId: string): boolean;
+export declare function assertValidMailboxId(mailboxId: string): void;
+/** Absolute path to a box. `root` override is for tests. */
+export declare function mailboxDir(mailboxId: string, root?: string): string;
+/**
+ * Enqueue a message into `boxDir` atomically. Returns the msgId. The `to` field
+ * is stamped so a drain can refuse a message that lands in the wrong box.
+ */
+export declare function enqueue(boxDir: string, msg: {
+    to: string;
+    text: string;
+    from?: string;
+}): string;
+/**
+ * Drain the box: return every pending message addressed to it, in FIFO order,
+ * removing them from the queue. Claim-first (inbox → processing → consumed) so
+ * an interrupted drain is recovered on the next call (at-least-once). Corrupt
+ * files and messages addressed to a different box are dropped, not returned.
+ *
+ * `boxId` defaults to the box's directory name — the id it was created under.
+ */
+export declare function drain(boxDir: string, boxId?: string): MailboxMessage[];
+/** Read pending messages (inbox + in-flight) without consuming them. FIFO. */
+export declare function peek(boxDir: string, boxId?: string): MailboxMessage[];
+/** Delete pending (not-yet-claimed) inbox messages. Returns the count removed. */
+export declare function clear(boxDir: string): number;