@phnx-labs/agents-cli 1.20.62 → 1.20.63

package/dist/lib/session/sync/provision.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Provisioning for cross-machine session sync: write the `r2.backups` secrets
+ * bundle and probe R2 connectivity. Pure logic — no prompts, no Commander — so
+ * it is unit-testable against the in-memory keychain seam. The interactive flow
+ * that collects the values lives in the command layer
+ * (`commands/sync-provision.ts`).
+ */
+/** Values a caller has already collected for the sync bundle. */
+export interface ProvisionInput {
+    accountId: string;
+    bucketName: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Optional S3 endpoint override (MinIO / non-R2). Default derived from accountId. */
+    endpoint?: string;
+    /**
+     * Shared transcript-encryption key for a machine JOINING an existing fabric —
+     * paste the key the first machine generated. Omit on the first machine to mint
+     * a fresh one. Ignored if the bundle already carries a key (never overwritten).
+     */
+    encKey?: string;
+}
+export type EncKeyAction = 'generated' | 'reused' | 'provided';
+/**
+ * Create or update the `r2.backups` bundle from already-collected values.
+ *
+ * The four R2 credentials are always (over)written. The encryption key is
+ * handled carefully: an existing key is REUSED, never overwritten (overwriting
+ * would orphan every transcript peers already encrypted under it); otherwise a
+ * caller-supplied `encKey` is stored, or a fresh one minted on the first machine.
+ */
+export declare function writeSyncBundle(input: ProvisionInput): {
+    encKeyAction: EncKeyAction;
+};
+/** The shared encryption key currently stored (for display when handing it to peers). */
+export declare function readStoredEncKey(): string | null;
+/**
+ * Prove the configured bundle can read AND write its bucket: put a throwaway
+ * object, read it back, delete it. Returns a structured result instead of
+ * throwing so the caller (setup) never crashes on a bad credential. The probe
+ * key lives OUTSIDE the `sessions/` prefix so it can never be mistaken for a
+ * machine manifest by the pull path.
+ */
+export declare function probeR2Connectivity(): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/lib/session/sync/provision.js

@@ -0,0 +1,91 @@
+/**
+ * Provisioning for cross-machine session sync: write the `r2.backups` secrets
+ * bundle and probe R2 connectivity. Pure logic — no prompts, no Commander — so
+ * it is unit-testable against the in-memory keychain seam. The interactive flow
+ * that collects the values lives in the command layer
+ * (`commands/sync-provision.ts`).
+ */
+import { bundleExists, readBundle, writeBundle, bundleItemStore, keychainRef, } from '../../secrets/bundles.js';
+import { secretsKeychainItem } from '../../secrets/index.js';
+import { SYNC_BUNDLE, loadR2Config, clearR2ConfigCache } from './config.js';
+import { R2Client } from './r2.js';
+import { generateSyncEncKey, resolveSyncEncKey } from './transcript-crypto.js';
+import { machineId } from '../../machine-id.js';
+/**
+ * Create or update the `r2.backups` bundle from already-collected values.
+ *
+ * The four R2 credentials are always (over)written. The encryption key is
+ * handled carefully: an existing key is REUSED, never overwritten (overwriting
+ * would orphan every transcript peers already encrypted under it); otherwise a
+ * caller-supplied `encKey` is stored, or a fresh one minted on the first machine.
+ */
+export function writeSyncBundle(input) {
+    // Validate a joining machine's pasted key up front so a bad paste fails here,
+    // not silently at the next sync.
+    if (input.encKey)
+        resolveSyncEncKey({ syncEncKey: input.encKey });
+    const bundle = bundleExists(SYNC_BUNDLE)
+        ? readBundle(SYNC_BUNDLE)
+        : { name: SYNC_BUNDLE, description: 'Cross-machine session-sync R2 credentials', vars: {} };
+    const store = bundleItemStore(bundle.backend);
+    const setKey = (key, value) => {
+        store.set(secretsKeychainItem(SYNC_BUNDLE, key), value);
+        bundle.vars[key] = keychainRef(key);
+    };
+    setKey('R2_ACCOUNT_ID', input.accountId);
+    setKey('R2_BUCKET_NAME', input.bucketName);
+    setKey('R2_ACCESS_KEY_ID', input.accessKeyId);
+    setKey('R2_SECRET_ACCESS_KEY', input.secretAccessKey);
+    if (input.endpoint)
+        setKey('R2_ENDPOINT', input.endpoint);
+    let encKeyAction;
+    if (bundle.vars['R2_SYNC_ENC_KEY']) {
+        encKeyAction = 'reused';
+    }
+    else if (input.encKey) {
+        setKey('R2_SYNC_ENC_KEY', input.encKey);
+        encKeyAction = 'provided';
+    }
+    else {
+        setKey('R2_SYNC_ENC_KEY', generateSyncEncKey());
+        encKeyAction = 'generated';
+    }
+    writeBundle(bundle);
+    clearR2ConfigCache(); // so the next loadR2Config() sees the just-written values
+    return { encKeyAction };
+}
+/** The shared encryption key currently stored (for display when handing it to peers). */
+export function readStoredEncKey() {
+    clearR2ConfigCache();
+    try {
+        return loadR2Config().syncEncKey ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Prove the configured bundle can read AND write its bucket: put a throwaway
+ * object, read it back, delete it. Returns a structured result instead of
+ * throwing so the caller (setup) never crashes on a bad credential. The probe
+ * key lives OUTSIDE the `sessions/` prefix so it can never be mistaken for a
+ * machine manifest by the pull path.
+ */
+export async function probeR2Connectivity() {
+    try {
+        clearR2ConfigCache();
+        const cfg = loadR2Config();
+        const r2 = new R2Client(cfg);
+        const key = `.agents-provision-probe/${machineId()}.txt`;
+        const token = `agents-sync-probe-${machineId()}`;
+        await r2.put(key, token, 'text/plain');
+        const got = await r2.get(key);
+        await r2.delete(key);
+        if (got !== token)
+            return { ok: false, error: 'wrote a probe object but read back different bytes' };
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: err.message };
+    }
+}

package/dist/lib/session/sync/sync.d.ts

@@ -24,6 +24,9 @@ export interface SyncResult {
     merged: number;
     pullSkipped: number;
     errors: string[];
+    /** Non-fatal advisories (e.g. transcripts uploaded unencrypted). Unlike
+     *  `errors` these do not set a failing exit code. */
+    warnings: string[];
 }
 export interface SyncOptions {
     verbose?: boolean;

package/dist/lib/session/sync/sync.js

@@ -20,16 +20,25 @@ import { R2Client } from './r2.js';
 import { loadR2Config, machineId } from './config.js';
 import { SYNC_AGENTS, listLocalTranscripts, localSessionIds, mirrorPath, objectKey, manifestKey, SESSIONS_PREFIX, } from './agents.js';
 import { mergeTranscripts, transcriptStats } from './crdt.js';
+import { resolveSyncEncKey, encryptTranscript, decryptTranscriptBody } from './transcript-crypto.js';
 import { emptyManifest, parseManifest, hashContent, loadLedger, saveLedger, ledgerUnchanged, ledgerRecord, loadLocalManifest, saveLocalManifest, loadPullState, savePullState, sourceSignature, } from './manifest.js';
 const nowIso = () => new Date().toISOString();
 function specById(id) {
     return SYNC_AGENTS.find(s => s.id === id);
 }
 /** Upload this machine's changed transcripts and publish its manifest. */
-async function pushOwn(r2, me, opts, result) {
+async function pushOwn(r2, me, encKey, opts, result) {
     const ledger = loadLedger();
     const prev = loadLocalManifest();
     const manifest = emptyManifest(me, nowIso());
+    // The transcript body is sealed client-side before it leaves the machine
+    // (AES-256-GCM under the shared bundle key). Without a key we still upload —
+    // the feature predates encryption — but flag it LOUDLY once per cycle so an
+    // unencrypted upload never happens silently.
+    if (!encKey) {
+        result.warnings.push(`R2_SYNC_ENC_KEY not set in the r2.backups bundle — transcripts are uploaded UNENCRYPTED ` +
+            `(readable by anyone with bucket access). Add the shared key to enable client-side encryption.`);
+    }
     for (const spec of SYNC_AGENTS) {
         const agentManifest = {};
         for (const t of listLocalTranscripts(spec)) {
@@ -53,11 +62,16 @@ async function pushOwn(r2, me, opts, result) {
             catch {
                 continue;
             }
+            // Identity for CRDT merge is the PLAINTEXT hash (ciphertext is
+            // non-deterministic), so hash + manifest are computed on cleartext; only
+            // the stored object body is sealed.
             const hash = hashContent(content);
             const { lastTs } = transcriptStats(content);
             const entry = { relKey: t.relKey, size: stat.size, hash, lastTs };
+            const body = encKey ? encryptTranscript(content, encKey) : content;
+            const contentType = encKey ? 'application/json' : 'application/x-ndjson';
             try {
-                await r2.put(objectKey(me, spec.id, t.sessionId), content, 'application/x-ndjson');
+                await r2.put(objectKey(me, spec.id, t.sessionId), body, contentType);
                 ledgerRecord(ledger, t.absPath, stat.size, stat.mtimeMs, hash);
                 agentManifest[t.sessionId] = entry;
                 result.pushed++;
@@ -138,7 +152,7 @@ export function reconcileCopies(spec, copies, fetched) {
     return resolveMirrorWrite(spec, copies, contents);
 }
 /** Fetch other machines' manifests, union changed sessions into the mirror. */
-async function pullAndReconcile(r2, me, opts, result) {
+async function pullAndReconcile(r2, me, encKey, opts, result) {
     const prefixes = await r2.listPrefixes(SESSIONS_PREFIX); // sessions/<machine>/
     const machines = prefixes
         .map(p => p.slice(SESSIONS_PREFIX.length).replace(/\/$/, ''))
@@ -189,7 +203,11 @@ async function pullAndReconcile(r2, me, opts, result) {
         const fetched = [];
         for (const c of list) {
             try {
-                fetched.push(await r2.get(objectKey(c.machine, agentId, sessionId)));
+                const body = await r2.get(objectKey(c.machine, agentId, sessionId));
+                // Decrypt before the body reaches the CRDT union — the merge and the
+                // mirror always operate on plaintext. A legacy plaintext object passes
+                // through untouched; an envelope without a key throws (surfaced below).
+                fetched.push(body === null ? null : decryptTranscriptBody(body, encKey));
             }
             catch (err) {
                 result.errors.push(`get ${c.machine}/${sessionId}: ${err.message}`);
@@ -234,6 +252,7 @@ export async function syncSessions(opts = {}) {
     const cfg = loadR2Config();
     const me = machineId();
     const r2 = new R2Client(cfg);
+    const encKey = resolveSyncEncKey(cfg); // shared client-side transcript key, or null
     const result = {
         machine: me,
         pushed: 0,
@@ -242,10 +261,11 @@ export async function syncSessions(opts = {}) {
         merged: 0,
         pullSkipped: 0,
         errors: [],
+        warnings: [],
     };
     if (opts.push !== false)
-        await pushOwn(r2, me, opts, result);
+        await pushOwn(r2, me, encKey, opts, result);
     if (opts.pull !== false)
-        await pullAndReconcile(r2, me, opts, result);
+        await pullAndReconcile(r2, me, encKey, opts, result);
     return result;
 }

package/dist/lib/session/sync/transcript-crypto.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Client-side (zero-knowledge) encryption for session transcripts before they
+ * leave this machine for R2.
+ *
+ * R2 encrypts objects at rest server-side (AES-256, Cloudflare default), but
+ * that key is Cloudflare's — anyone with bucket-read access (or Cloudflare
+ * itself) can read the plaintext. Transcripts carry secrets, tokens, and
+ * absolute file paths, so "encrypted at rest by the provider" is not enough. We
+ * seal each transcript BODY client-side with AES-256-GCM under a key that never
+ * leaves the machines that share the sync bundle; Cloudflare only ever stores
+ * ciphertext.
+ *
+ * The key is a 32-byte secret (`R2_SYNC_ENC_KEY`) held in the same
+ * keychain-backed `r2.backups` bundle as the R2 credentials. Every machine in
+ * the sync fabric shares that bundle, so every machine derives the identical key
+ * and can decrypt its peers' objects. The key is deliberately SEPARATE from the
+ * R2 access key so that rotating the R2 token (RUSH-1464) never orphans
+ * transcripts already encrypted under the old one.
+ *
+ * Identity for CRDT merge stays over PLAINTEXT: the manifest hash is computed on
+ * the cleartext transcript (sync.ts), and pull decrypts before the G-Set union
+ * (crdt.ts) ever sees the bytes. Ciphertext is non-deterministic (a fresh random
+ * IV per seal), so it is never usable as an identity — which is exactly why the
+ * manifest, not the object body, carries the hash.
+ */
+import type { R2Config } from './config.js';
+/** Serialized envelope stored as the R2 object body when encryption is on. */
+export interface TranscriptEnvelope {
+    /** Envelope format version. */
+    v: 1;
+    alg: 'aes-256-gcm';
+    /** base64 12-byte GCM nonce, fresh per object. */
+    iv: string;
+    /** base64 ciphertext. */
+    ct: string;
+    /** base64 16-byte GCM auth tag. */
+    tag: string;
+}
+/**
+ * Decode the configured `R2_SYNC_ENC_KEY` into a 32-byte key, or null when the
+ * bundle does not carry one (encryption off — see pushOwn's warning path).
+ *
+ * Accepts hex (64 chars) or base64; both must decode to exactly 32 bytes. A key
+ * that is present but the wrong length THROWS rather than silently truncating —
+ * a malformed key is a configuration bug, not a reason to fall back to a weaker
+ * or wrong key.
+ */
+export declare function resolveSyncEncKey(cfg: Pick<R2Config, 'syncEncKey'>): Buffer | null;
+/** Generate a fresh 32-byte transcript key, base64-encoded (for provisioning). */
+export declare function generateSyncEncKey(): string;
+/** Seal a transcript body. Returns the serialized envelope to store in R2. */
+export declare function encryptTranscript(plaintext: string, key: Buffer): string;
+/**
+ * Parse a stored object body into an envelope, or null when it is not one.
+ *
+ * A plaintext transcript is NDJSON — many JSON objects, one per line — so it
+ * never parses as a single object carrying our `v`/`alg`/`ct`/`tag` fields. That
+ * makes envelope-vs-plaintext detection unambiguous and lets a puller read BOTH
+ * encrypted objects and any legacy plaintext already in the bucket (the beta
+ * uploaded plaintext before this landed). This is format-version handling for a
+ * real migration, not a "just in case" fallback.
+ */
+export declare function parseEnvelope(body: string): TranscriptEnvelope | null;
+/** True when a stored object body is one of our encryption envelopes. */
+export declare function isTranscriptEnvelope(body: string): boolean;
+/** Open a sealed envelope. Throws on a wrong key / tampered body (GCM tag mismatch). */
+export declare function decryptEnvelope(envelope: TranscriptEnvelope, key: Buffer): string;
+/**
+ * Return the plaintext transcript for a fetched object body, transparently
+ * decrypting when it is an envelope.
+ *
+ *  - Envelope + key  → decrypted plaintext.
+ *  - Envelope + no key → throws (the object is encrypted but this machine has no
+ *    key to read it — surfacing that beats silently mis-merging ciphertext).
+ *  - Plaintext body  → returned verbatim (legacy/unencrypted object).
+ */
+export declare function decryptTranscriptBody(body: string, key: Buffer | null): string;

package/dist/lib/session/sync/transcript-crypto.js

@@ -0,0 +1,147 @@
+/**
+ * Client-side (zero-knowledge) encryption for session transcripts before they
+ * leave this machine for R2.
+ *
+ * R2 encrypts objects at rest server-side (AES-256, Cloudflare default), but
+ * that key is Cloudflare's — anyone with bucket-read access (or Cloudflare
+ * itself) can read the plaintext. Transcripts carry secrets, tokens, and
+ * absolute file paths, so "encrypted at rest by the provider" is not enough. We
+ * seal each transcript BODY client-side with AES-256-GCM under a key that never
+ * leaves the machines that share the sync bundle; Cloudflare only ever stores
+ * ciphertext.
+ *
+ * The key is a 32-byte secret (`R2_SYNC_ENC_KEY`) held in the same
+ * keychain-backed `r2.backups` bundle as the R2 credentials. Every machine in
+ * the sync fabric shares that bundle, so every machine derives the identical key
+ * and can decrypt its peers' objects. The key is deliberately SEPARATE from the
+ * R2 access key so that rotating the R2 token (RUSH-1464) never orphans
+ * transcripts already encrypted under the old one.
+ *
+ * Identity for CRDT merge stays over PLAINTEXT: the manifest hash is computed on
+ * the cleartext transcript (sync.ts), and pull decrypts before the G-Set union
+ * (crdt.ts) ever sees the bytes. Ciphertext is non-deterministic (a fresh random
+ * IV per seal), so it is never usable as an identity — which is exactly why the
+ * manifest, not the object body, carries the hash.
+ */
+import * as crypto from 'crypto';
+const ALG = 'aes-256-gcm';
+const KEY_LEN = 32; // AES-256
+const IV_LEN = 12; // GCM standard nonce
+const TAG_LEN = 16;
+/**
+ * Decode the configured `R2_SYNC_ENC_KEY` into a 32-byte key, or null when the
+ * bundle does not carry one (encryption off — see pushOwn's warning path).
+ *
+ * Accepts hex (64 chars) or base64; both must decode to exactly 32 bytes. A key
+ * that is present but the wrong length THROWS rather than silently truncating —
+ * a malformed key is a configuration bug, not a reason to fall back to a weaker
+ * or wrong key.
+ */
+export function resolveSyncEncKey(cfg) {
+    const raw = cfg.syncEncKey?.trim();
+    if (!raw)
+        return null;
+    let key;
+    if (/^[0-9a-f]{64}$/i.test(raw)) {
+        key = Buffer.from(raw, 'hex');
+    }
+    else {
+        key = Buffer.from(raw, 'base64');
+    }
+    if (key.length !== KEY_LEN) {
+        throw new Error(`R2_SYNC_ENC_KEY must decode to ${KEY_LEN} bytes (got ${key.length}). ` +
+            `Provide 32 random bytes as hex (64 chars) or base64. ` +
+            `Generate one with: openssl rand -base64 32`);
+    }
+    return key;
+}
+/** Generate a fresh 32-byte transcript key, base64-encoded (for provisioning). */
+export function generateSyncEncKey() {
+    return crypto.randomBytes(KEY_LEN).toString('base64');
+}
+/** Seal a transcript body. Returns the serialized envelope to store in R2. */
+export function encryptTranscript(plaintext, key) {
+    const iv = crypto.randomBytes(IV_LEN);
+    const cipher = crypto.createCipheriv(ALG, key, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const envelope = {
+        v: 1,
+        alg: ALG,
+        iv: iv.toString('base64'),
+        ct: ct.toString('base64'),
+        tag: tag.toString('base64'),
+    };
+    return JSON.stringify(envelope);
+}
+/**
+ * Parse a stored object body into an envelope, or null when it is not one.
+ *
+ * A plaintext transcript is NDJSON — many JSON objects, one per line — so it
+ * never parses as a single object carrying our `v`/`alg`/`ct`/`tag` fields. That
+ * makes envelope-vs-plaintext detection unambiguous and lets a puller read BOTH
+ * encrypted objects and any legacy plaintext already in the bucket (the beta
+ * uploaded plaintext before this landed). This is format-version handling for a
+ * real migration, not a "just in case" fallback.
+ */
+export function parseEnvelope(body) {
+    const trimmed = body.trimStart();
+    if (!trimmed.startsWith('{'))
+        return null; // NDJSON first line is an object too, but…
+    let obj;
+    try {
+        obj = JSON.parse(body); // …the WHOLE body must be one JSON value to be an envelope
+    }
+    catch {
+        return null;
+    }
+    if (obj && typeof obj === 'object' &&
+        obj.v === 1 &&
+        obj.alg === ALG &&
+        typeof obj.iv === 'string' &&
+        typeof obj.ct === 'string' &&
+        typeof obj.tag === 'string') {
+        return obj;
+    }
+    return null;
+}
+/** True when a stored object body is one of our encryption envelopes. */
+export function isTranscriptEnvelope(body) {
+    return parseEnvelope(body) !== null;
+}
+/** Open a sealed envelope. Throws on a wrong key / tampered body (GCM tag mismatch). */
+export function decryptEnvelope(envelope, key) {
+    const iv = Buffer.from(envelope.iv, 'base64');
+    const ct = Buffer.from(envelope.ct, 'base64');
+    const tag = Buffer.from(envelope.tag, 'base64');
+    if (tag.length !== TAG_LEN) {
+        throw new Error(`Transcript envelope has a malformed auth tag (${tag.length} bytes).`);
+    }
+    const decipher = crypto.createDecipheriv(ALG, key, iv);
+    decipher.setAuthTag(tag);
+    try {
+        return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf-8');
+    }
+    catch {
+        throw new Error('Transcript decryption failed — wrong R2_SYNC_ENC_KEY or corrupt object.');
+    }
+}
+/**
+ * Return the plaintext transcript for a fetched object body, transparently
+ * decrypting when it is an envelope.
+ *
+ *  - Envelope + key  → decrypted plaintext.
+ *  - Envelope + no key → throws (the object is encrypted but this machine has no
+ *    key to read it — surfacing that beats silently mis-merging ciphertext).
+ *  - Plaintext body  → returned verbatim (legacy/unencrypted object).
+ */
+export function decryptTranscriptBody(body, key) {
+    const envelope = parseEnvelope(body);
+    if (!envelope)
+        return body; // legacy plaintext object
+    if (!key) {
+        throw new Error('Fetched an encrypted transcript but R2_SYNC_ENC_KEY is not set in the r2.backups bundle. ' +
+            'Add the shared key so this machine can decrypt peers\' sessions.');
+    }
+    return decryptEnvelope(envelope, key);
+}

package/dist/lib/startup/command-registry.d.ts

@@ -88,6 +88,8 @@ export declare const loadMessage: ModuleLoader;
 export declare const loadFeed: ModuleLoader;
 export declare const loadServe: ModuleLoader;
 export declare const loadAudit: ModuleLoader;
+export declare const loadWebhook: ModuleLoader;
+export declare const loadFunnel: ModuleLoader;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help

package/dist/lib/startup/command-registry.js

@@ -66,6 +66,8 @@ export const loadMessage = async () => (await import('../../commands/message.js'
 export const loadFeed = async () => (await import('../../commands/feed.js')).registerFeedCommand;
 export const loadServe = async () => (await import('../../commands/serve.js')).registerServeCommand;
 export const loadAudit = async () => (await import('../../commands/audit.js')).registerAuditCommands;
+export const loadWebhook = async () => (await import('../../commands/webhook.js')).registerWebhookCommand;
+export const loadFunnel = async () => (await import('../../commands/funnel.js')).registerFunnelCommand;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
@@ -151,8 +153,15 @@ export const COMMAND_LOADERS = {
     events: [loadEvents],
     ssh: [loadSsh],
     devices: [loadSsh],
+    // `fleet` is a commander alias of `devices` (see commands/ssh.ts); list it so
+    // lazy registration loads the devices tree when the user types `agents fleet`.
+    fleet: [loadSsh],
     pull: [loadPull],
     push: [loadPush],
+    // `repos` is the canonical command name; `repo` remains a convenience alias
+    // (see commands/repo.ts). List both so lazy registration loads the tree
+    // whichever the user types.
+    repos: [loadRepo],
     repo: [loadRepo],
     setup: [loadSetup],
     sessions: [loadSessions],
@@ -162,4 +171,6 @@ export const COMMAND_LOADERS = {
     feed: [loadFeed],
     serve: [loadServe],
     audit: [loadAudit],
+    webhook: [loadWebhook],
+    funnel: [loadFunnel],
 };

package/dist/lib/state.d.ts

@@ -109,13 +109,21 @@ export declare function getCacheDir(): string;
 export declare function getPackagesDir(): string;
 /** Path to routine YAML definitions (~/.agents/routines/). */
 export declare function getRoutinesDir(): string;
+/**
+ * Path to built-in routine definitions shipped in the system repo
+ * (`~/.agents/.system/routines/`). Unioned under the user routines dir by
+ * listJobs()/readJob(): a routine shipped here fires for every install, and a
+ * user routine of the same name overrides it (a user copy with `enabled: false`
+ * disables the built-in). The daemon fires these; the directory need not exist.
+ */
+export declare function getSystemRoutinesDir(): string;
 /**
  * Path to a project-scoped routines directory (`<project>/.agents/routines/`),
  * or null when no project `.agents/` is found by walking up from cwd.
  *
  * Project routines participate in `list`/`view`/`run` for inspection but are
- * NOT fired by the daemon (which runs from $HOME and only loads user routines).
- * Opt-in firing for project routines is tracked as a follow-up.
+ * NOT fired by the daemon (which runs from $HOME and loads only user + system
+ * routines). Opt-in firing for project routines is tracked as a follow-up.
  */
 export declare function getProjectRoutinesDir(cwd?: string): string | null;
 /** Path to routine execution logs (~/.agents/.history/runs/). */

package/dist/lib/state.js

@@ -69,6 +69,10 @@ const SYSTEM_PERMISSIONS_DIR = path.join(SYSTEM_AGENTS_DIR, 'permissions');
 const SYSTEM_SUBAGENTS_DIR = path.join(SYSTEM_AGENTS_DIR, 'subagents');
 const SYSTEM_WORKFLOWS_DIR = path.join(SYSTEM_AGENTS_DIR, 'workflows');
 const SYSTEM_PLUGINS_DIR = path.join(SYSTEM_AGENTS_DIR, 'plugins');
+// Built-in routines shipped in the system repo (gh:phnx-labs/.agents-system).
+// Unioned under user routines by listJobs()/readJob() so a routine shipped here
+// fires for every install, while a user routine of the same name overrides it.
+const SYSTEM_ROUTINES_DIR = path.join(SYSTEM_AGENTS_DIR, 'routines');
 const SYSTEM_PROMPTCUTS_FILE = path.join(SYSTEM_AGENTS_DIR, 'hooks', 'promptcuts.yaml');
 const SYSTEM_MCP_CONFIG_FILE = path.join(SYSTEM_AGENTS_DIR, 'mcp.json');
 const SYSTEM_INSTRUCTIONS_FILE = path.join(SYSTEM_AGENTS_DIR, 'instructions.md');
@@ -296,13 +300,21 @@ export function getCacheDir() { return CACHE_DIR; }
 export function getPackagesDir() { return PACKAGES_DIR; }
 /** Path to routine YAML definitions (~/.agents/routines/). */
 export function getRoutinesDir() { return ROUTINES_DIR; }
+/**
+ * Path to built-in routine definitions shipped in the system repo
+ * (`~/.agents/.system/routines/`). Unioned under the user routines dir by
+ * listJobs()/readJob(): a routine shipped here fires for every install, and a
+ * user routine of the same name overrides it (a user copy with `enabled: false`
+ * disables the built-in). The daemon fires these; the directory need not exist.
+ */
+export function getSystemRoutinesDir() { return SYSTEM_ROUTINES_DIR; }
 /**
  * Path to a project-scoped routines directory (`<project>/.agents/routines/`),
  * or null when no project `.agents/` is found by walking up from cwd.
  *
  * Project routines participate in `list`/`view`/`run` for inspection but are
- * NOT fired by the daemon (which runs from $HOME and only loads user routines).
- * Opt-in firing for project routines is tracked as a follow-up.
+ * NOT fired by the daemon (which runs from $HOME and loads only user + system
+ * routines). Opt-in firing for project routines is tracked as a follow-up.
  */
 export function getProjectRoutinesDir(cwd = process.cwd()) {
     const projectAgentsDir = getProjectAgentsDir(cwd);