@faithfulalabi/agent-lens 0.2.0 → 0.4.0

package/README.md

@@ -55,15 +55,27 @@ only by the archive.
 agent-lens schedule install
 ```
 
-On macOS that sets up a launchd job that runs `agent-lens archive` every 15 minutes and logs each
-pass where `agent-lens doctor` reads it. Run it again any time — it replaces its own job rather
-than duplicating it. `agent-lens schedule status` reports the job and its last successful pass;
-`agent-lens schedule disable` turns it off cleanly, leaving the archive and its logs untouched. On
-other platforms, run `agent-lens archive` every ~15 minutes yourself via a systemd timer or cron.
+That sets up a recurring job that runs `agent-lens archive` every 15 minutes and logs each pass
+where `agent-lens doctor` reads it. Both supported platforms are handled for you: macOS gets a
+launchd agent, Linux gets a systemd **user** timer under `~/.config/systemd/user`. Run it again any
+time — it replaces its own job rather than duplicating it. `agent-lens schedule status` reports the
+job and its last successful pass; `agent-lens schedule disable` turns it off cleanly, leaving the
+archive and its logs untouched. On any other platform, run `agent-lens archive` every ~15 minutes
+yourself from whatever scheduler you have, such as a cron entry.
 
 One caveat worth knowing before you rely on an interval: a wall-clock schedule does not fire while
 the machine is asleep. Treat the interval as a bound on _wake_ time, not on elapsed time.
 
+One more on Linux, and it is the difference between a green report and a real archive:
+
+> **a systemd user timer does not run while you are logged out unless lingering is on for your user**
+
+`agent-lens schedule status` reports which state your user is in, and `schedule install` prints the
+one command that changes it — `loginctl enable-linger <uid>`. The command is printed and never run:
+it writes outside everything this tool owns. The two platforms also differ deliberately on catch-up.
+launchd runs a pass at load; the systemd timer uses `OnCalendar` with `Persistent=true`, so a slot
+missed while the machine was off runs once on resume.
+
 The pass is safe to run often: an advisory lock means a second concurrent pass copies nothing and
 exits 0, and an unchanged corpus copies zero bytes. When a source has been rewritten, the archived
 bytes are **kept** and the file is marked `diverged` rather than overwritten. `agent-lens archive

package/dist/src/archive/paths.js

@@ -53,6 +53,18 @@ export function resolveLaunchAgentsDir(homeDir = homedir()) {
 export function resolvePlistPath(label, homeDir = homedir()) {
     return join(resolveLaunchAgentsDir(homeDir), `${label}.plist`);
 }
+export function resolveSystemdUserDir(homeDir = homedir(), configHome) {
+    const base = configHome !== undefined && configHome !== '' && isAbsolute(configHome)
+        ? configHome
+        : join(homeDir, '.config');
+    return join(base, 'systemd', 'user');
+}
+export function resolveSystemdUnitPath(name, homeDir, configHome) {
+    return join(resolveSystemdUserDir(homeDir, configHome), name);
+}
+export function resolveSystemdWantsPath(name, homeDir, configHome) {
+    return join(resolveSystemdUserDir(homeDir, configHome), 'timers.target.wants', name);
+}
 export function resolveScheduleWrapperPath(dataDir) {
     return join(resolveDataDir(dataDir), 'schedule', 'archive.sh');
 }

package/dist/src/cli/commands/schedule.js

@@ -3,23 +3,40 @@ import { chmodSync, existsSync, mkdirSync, renameSync, rmdirSync, unlinkSync, wr
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { assertNotUnderRoot, lstatSafe, resolveCronLogPath, resolveDataDir, resolvePlistPath, resolveScheduleWrapperPath, resolveTranscriptRoot, TRANSCRIPT_ROOT_LABEL, } from '../../archive/paths.js';
+import { assertNotUnderRoot, lstatSafe, resolveCronLogPath, resolveDataDir, resolvePlistPath, resolveScheduleWrapperPath, resolveSystemdUnitPath, resolveSystemdUserDir, resolveSystemdWantsPath, resolveTranscriptRoot, TRANSCRIPT_ROOT_LABEL, } from '../../archive/paths.js';
 import { parseStringFlag } from './archive.js';
 export const SCHEDULE_LABEL = 'com.agent-lens.archive';
 export const LEGACY_LABEL = 'com.faithful.agent-lens.archive';
 const START_INTERVAL_SECONDS = 900;
 export const CRON_STAMP_FORMAT = '+%Y-%m-%dT%H:%M:%S%z';
 export const WAKE_TIME_CAVEAT = 'a wall-clock schedule does not fire while the machine is asleep — treat the interval as a bound on wake time, not on elapsed time';
+export const LINGER_CAVEAT = 'a systemd user timer does not run while you are logged out unless lingering is on for your user';
+export const SYSTEMD_UNIT_BASE = 'agent-lens-archive';
+const SYSTEMD_SERVICE = `${SYSTEMD_UNIT_BASE}.service`;
+const SYSTEMD_TIMER = `${SYSTEMD_UNIT_BASE}.timer`;
+const SYSTEMD_CALENDAR = '*:0/15';
+const SYSTEMD_TIMER_PROPERTIES = [
+    'ActiveState',
+    'UnitFileState',
+    'NextElapseUSecRealtime',
+    'LastTriggerUSec',
+    'Result',
+];
 const ACTIONS = 'install | status | disable';
-const NON_MACOS_POINTER = 'the recurring job uses launchd, which is macOS-only. Elsewhere, run `agent-lens archive` ' +
-    'every ~15 minutes yourself — a systemd timer or cron entry — per the README section ' +
-    '"Keeping the archive current".';
-function realLaunchctl(args) {
-    const result = spawnSync('launchctl', args, { encoding: 'utf8' });
-    return {
-        status: result.status,
-        stdout: result.stdout ?? '',
-        stderr: result.error === undefined ? (result.stderr ?? '') : String(result.error.message),
+const UNSUPPORTED_PLATFORM_POINTER = 'the recurring job uses launchd on macOS and a systemd user timer on Linux, and this platform ' +
+    'is neither. Run `agent-lens archive` every ~15 minutes from whatever scheduler it does have — ' +
+    'a cron entry, for instance — per the README section "Keeping the archive current". No cron ' +
+    'fallback ships here on purpose: the two backends above are the two this command sets up for you.';
+const BUS_HINT = '  hint: run this from a logged-in session — `systemctl --user` needs a user D-Bus, with ' +
+    'XDG_RUNTIME_DIR pointing at /run/user/<uid>';
+function realRunner(bin) {
+    return (args) => {
+        const result = spawnSync(bin, args, { encoding: 'utf8' });
+        return {
+            status: result.status,
+            stdout: result.stdout ?? '',
+            stderr: result.error === undefined ? (result.stderr ?? '') : String(result.error.message),
+        };
     };
 }
 function realDeps() {
@@ -29,7 +46,10 @@ function realDeps() {
         homeDir: homedir(),
         uid: process.getuid?.() ?? 0,
         moduleUrl: import.meta.url,
-        launchctl: realLaunchctl,
+        launchctl: realRunner('launchctl'),
+        systemctl: realRunner('systemctl'),
+        loginctl: realRunner('loginctl'),
+        configHome: process.env.XDG_CONFIG_HOME,
         now: Date.now,
     };
 }
@@ -184,6 +204,56 @@ export function buildPlist(opts) {
 </plist>
 `;
 }
+export function escapeUnitValue(value) {
+    if (/[\n\r]/.test(value)) {
+        throw new Error('refusing to write a systemd unit: a line break in a unit value would split the ' +
+            `directive — ${JSON.stringify(value)}`);
+    }
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/%/g, '%%')
+        .replace(/\$/g, '$$$$');
+}
+export function buildSystemdService(opts) {
+    return `[Unit]
+Description=agent-lens archive — unattended pass, every ${START_INTERVAL_SECONDS / 60} minutes
+#
+# GENERATED by \`agent-lens schedule\` — do not edit. Turning the job on again
+# rewrites this file in full, which is what keeps it current with the package
+# that shipped it.
+#
+# Coverage is wake-time-bounded: ${escapeUnitValue(WAKE_TIME_CAVEAT)}.
+#
+# Exit codes are the archive command's own: 0 clean, 1 usage error / crash,
+# 3 archive-side errors. 2 is RESERVED product-wide and must never appear.
+
+[Service]
+Type=oneshot
+ExecStart=/bin/sh "${escapeUnitValue(opts.wrapperPath)}"
+`;
+}
+export function buildSystemdTimer() {
+    return `[Unit]
+Description=agent-lens archive — timer for ${escapeUnitValue(SYSTEMD_SERVICE)}
+#
+# GENERATED by \`agent-lens schedule\` — do not edit. Turning the job on again
+# rewrites this file in full.
+#
+# Coverage is wake-time-bounded: ${escapeUnitValue(WAKE_TIME_CAVEAT)}.
+#
+# And ${escapeUnitValue(LINGER_CAVEAT)} — \`agent-lens schedule status\` reports which.
+
+[Timer]
+OnCalendar=${escapeUnitValue(SYSTEMD_CALENDAR)}
+Persistent=true
+AccuracySec=1min
+Unit=${escapeUnitValue(SYSTEMD_SERVICE)}
+
+[Install]
+WantedBy=timers.target
+`;
+}
 function ensureDirOutsideCorpus(dir, mode, transcriptRoot) {
     assertNotUnderRoot(dir, transcriptRoot, TRANSCRIPT_ROOT_LABEL);
     mkdirSync(dir, { recursive: true, mode });
@@ -202,12 +272,22 @@ function removeIfPresent(path, transcriptRoot) {
     unlinkSync(path);
     return true;
 }
+function removeEmptyDir(dir, transcriptRoot) {
+    assertNotUnderRoot(dir, transcriptRoot, TRANSCRIPT_ROOT_LABEL);
+    try {
+        rmdirSync(dir);
+    }
+    catch {
+    }
+}
 function gui(deps, label) {
     return `gui/${deps.uid}/${label}`;
 }
 function install(dataDirFlag, deps) {
+    if (deps.platform === 'linux')
+        return installSystemd(dataDirFlag, deps);
     if (deps.platform !== 'darwin') {
-        console.error(`agent-lens schedule: nothing was set up — ${NON_MACOS_POINTER}`);
+        console.error(`agent-lens schedule: nothing was set up — ${UNSUPPORTED_PLATFORM_POINTER}`);
         return 1;
     }
     const dataDir = resolveDataDir(dataDirFlag);
@@ -247,8 +327,10 @@ function install(dataDirFlag, deps) {
     return 0;
 }
 async function status(dataDirFlag, deps) {
+    if (deps.platform === 'linux')
+        return statusSystemd(dataDirFlag, deps);
     if (deps.platform !== 'darwin') {
-        console.log(`agent-lens schedule: ${NON_MACOS_POINTER}`);
+        console.log(`agent-lens schedule: ${UNSUPPORTED_PLATFORM_POINTER}`);
         console.log(`note: ${WAKE_TIME_CAVEAT}`);
         return 0;
     }
@@ -275,8 +357,10 @@ async function status(dataDirFlag, deps) {
     return 0;
 }
 function disable(dataDirFlag, deps) {
+    if (deps.platform === 'linux')
+        return disableSystemd(dataDirFlag, deps);
     if (deps.platform !== 'darwin') {
-        console.error(`agent-lens schedule: nothing was removed — ${NON_MACOS_POINTER}`);
+        console.error(`agent-lens schedule: nothing was removed — ${UNSUPPORTED_PLATFORM_POINTER}`);
         return 1;
     }
     const transcriptRoot = resolveTranscriptRoot();
@@ -291,11 +375,7 @@ function disable(dataDirFlag, deps) {
         removed.push(plistPath);
     if (removeIfPresent(wrapperPath, transcriptRoot))
         removed.push(wrapperPath);
-    try {
-        rmdirSync(dirname(wrapperPath));
-    }
-    catch {
-    }
+    removeEmptyDir(dirname(wrapperPath), transcriptRoot);
     if (removed.length === 0) {
         console.log('recurring archive job: not installed — nothing to remove');
     }
@@ -305,6 +385,155 @@ function disable(dataDirFlag, deps) {
     }
     return 0;
 }
+function systemdPaths(deps) {
+    return {
+        unitDir: resolveSystemdUserDir(deps.homeDir, deps.configHome),
+        servicePath: resolveSystemdUnitPath(SYSTEMD_SERVICE, deps.homeDir, deps.configHome),
+        timerPath: resolveSystemdUnitPath(SYSTEMD_TIMER, deps.homeDir, deps.configHome),
+        wantsPath: resolveSystemdWantsPath(SYSTEMD_TIMER, deps.homeDir, deps.configHome),
+    };
+}
+function detailOf(result) {
+    return (result.stderr || result.stdout).trim() || `systemctl exited ${String(result.status)}`;
+}
+function parseProperties(stdout) {
+    const properties = new Map();
+    for (const line of stdout.split('\n')) {
+        const split = line.indexOf('=');
+        if (split > 0)
+            properties.set(line.slice(0, split).trim(), line.slice(split + 1).trim());
+    }
+    return properties;
+}
+function reported(value) {
+    return value === undefined || value === '' ? 'unknown — systemd reported nothing' : value;
+}
+function readLingerState(deps) {
+    const result = deps.loginctl(['show-user', String(deps.uid), '--property=Linger']);
+    if (result.status !== 0)
+        return 'unknown';
+    const value = parseProperties(result.stdout).get('Linger');
+    if (value === 'yes')
+        return 'on';
+    if (value === 'no')
+        return 'off';
+    return 'unknown';
+}
+function lingerLines(deps) {
+    const state = readLingerState(deps);
+    if (state === 'on') {
+        return ['  lingering: on — the timer keeps running while you are logged out'];
+    }
+    return [
+        `  lingering: ${state} — ${LINGER_CAVEAT}`,
+        `  turn lingering on with: loginctl enable-linger ${deps.uid}`,
+    ];
+}
+function installSystemd(dataDirFlag, deps) {
+    const dataDir = resolveDataDir(dataDirFlag);
+    const transcriptRoot = resolveTranscriptRoot();
+    const wrapperPath = resolveScheduleWrapperPath(dataDir);
+    const cronLogPath = resolveCronLogPath(dataDir);
+    const { unitDir, servicePath, timerPath } = systemdPaths(deps);
+    for (const path of [wrapperPath, cronLogPath, unitDir, servicePath, timerPath]) {
+        assertNotUnderRoot(path, transcriptRoot, TRANSCRIPT_ROOT_LABEL);
+    }
+    const invocation = resolveArchiveInvocation(deps.moduleUrl);
+    const wrapperText = buildWrapperScript({
+        nodePath: deps.execPath,
+        invocation,
+        dataDir,
+        cronLogPath,
+    });
+    const serviceText = buildSystemdService({ wrapperPath });
+    const timerText = buildSystemdTimer();
+    ensureDirOutsideCorpus(dirname(wrapperPath), 0o700, transcriptRoot);
+    ensureDirOutsideCorpus(dirname(cronLogPath), 0o700, transcriptRoot);
+    ensureDirOutsideCorpus(unitDir, 0o700, transcriptRoot);
+    atomicWrite(wrapperPath, wrapperText, 0o700, transcriptRoot);
+    atomicWrite(servicePath, serviceText, 0o644, transcriptRoot);
+    atomicWrite(timerPath, timerText, 0o644, transcriptRoot);
+    const armed = [
+        ['--user', 'daemon-reload'],
+        ['--user', 'enable', SYSTEMD_TIMER],
+        ['--user', 'restart', SYSTEMD_TIMER],
+    ];
+    for (const argv of armed) {
+        const result = deps.systemctl(argv);
+        if (result.status !== 0) {
+            console.error(`agent-lens schedule: \`systemctl ${argv.join(' ')}\` failed — ${detailOf(result)}`);
+            if (/Failed to connect to bus/.test(result.stderr))
+                console.error(BUS_HINT);
+            return 1;
+        }
+    }
+    const firstPass = deps.systemctl(['--user', 'start', '--no-block', SYSTEMD_SERVICE]);
+    const lines = [];
+    if (firstPass.status !== 0) {
+        lines.push(`warning: the first pass could not be started — ${detailOf(firstPass)}`);
+    }
+    lines.push(`recurring archive job on — ${SYSTEMD_TIMER}, every ` +
+        `${START_INTERVAL_SECONDS / 60} minutes (${invocation.kind} layout)`, `  timer    ${timerPath}`, `  service  ${servicePath}`, `  wrapper  ${wrapperPath}`, `  passes   ${cronLogPath}`, `  unit log journalctl --user -u ${SYSTEMD_SERVICE}`, `note: ${WAKE_TIME_CAVEAT}`, ...lingerLines(deps));
+    console.log(lines.join('\n'));
+    return 0;
+}
+async function statusSystemd(dataDirFlag, deps) {
+    const { servicePath, timerPath } = systemdPaths(deps);
+    const lines = [];
+    if (lstatSafe(timerPath)?.isFile() === true) {
+        lines.push(`recurring archive job: installed — ${timerPath}`);
+        lines.push(`  service  ${servicePath}`);
+        const shown = deps.systemctl([
+            '--user',
+            'show',
+            SYSTEMD_TIMER,
+            `--property=${SYSTEMD_TIMER_PROPERTIES.join(',')}`,
+        ]);
+        const properties = parseProperties(shown.stdout);
+        lines.push(`  timer state: ${reported(properties.get('ActiveState'))}`, `  unit file: ${reported(properties.get('UnitFileState'))}`, `  next trigger: ${reported(properties.get('NextElapseUSecRealtime'))}`, `  last trigger: ${reported(properties.get('LastTriggerUSec'))}`, `  last result: ${reported(properties.get('Result'))}`);
+    }
+    else {
+        lines.push('recurring archive job: not installed');
+        lines.push('  turn it on with: agent-lens schedule install');
+    }
+    lines.push(...lingerLines(deps));
+    const [{ formatLastPassSection }, { readCronLogStatus }] = await Promise.all([
+        import('./doctor.js'),
+        import('../../archive/cron-log.js'),
+    ]);
+    lines.push(...formatLastPassSection(readCronLogStatus(dataDirFlag), deps.now()));
+    lines.push('', `note: ${WAKE_TIME_CAVEAT}`);
+    console.log(lines.join('\n'));
+    return 0;
+}
+function disableSystemd(dataDirFlag, deps) {
+    const transcriptRoot = resolveTranscriptRoot();
+    const wrapperPath = resolveScheduleWrapperPath(resolveDataDir(dataDirFlag));
+    const { servicePath, timerPath, wantsPath } = systemdPaths(deps);
+    const wasInstalled = lstatSafe(timerPath) !== undefined || lstatSafe(servicePath) !== undefined;
+    const stopped = deps.systemctl(['--user', 'stop', SYSTEMD_TIMER]);
+    const disabled = deps.systemctl(['--user', 'disable', SYSTEMD_TIMER]);
+    const removed = [];
+    for (const path of [timerPath, servicePath, wantsPath, wrapperPath]) {
+        if (removeIfPresent(path, transcriptRoot))
+            removed.push(path);
+    }
+    deps.systemctl(['--user', 'daemon-reload']);
+    removeEmptyDir(dirname(wrapperPath), transcriptRoot);
+    const lines = [];
+    const refused = [stopped, disabled].find((result) => result.status !== 0);
+    if (refused !== undefined && wasInstalled) {
+        lines.push(`warning: systemctl --user could not stop the timer — ${detailOf(refused)}`, '  the unit files were removed anyway, so nothing is left to fire');
+    }
+    if (removed.length === 0) {
+        lines.push('recurring archive job: not installed — nothing to remove');
+    }
+    else {
+        lines.push('recurring archive job off — removed:', ...removed.map((path) => `  ${path}`), '  cron.log and the archive itself are untouched');
+    }
+    console.log(lines.join('\n'));
+    return 0;
+}
 export async function schedule(args = [], deps = realDeps()) {
     const action = parseScheduleAction(args);
     const dataDir = parseStringFlag(args, 'dataDir');

package/dist/src/transcript/line.js

@@ -46,6 +46,14 @@ const LINE_TYPES = new Map([
                 'attributionPlugin',
                 'isApiErrorMessage',
                 'error',
+                'perTurnEffort',
+                'apiBlockIndex',
+                'advisorModel',
+                'serverClassifierRequest',
+                'wireToolInputs',
+                'wireIngestContext',
+                'apiErrorStatus',
+                'quotaLimits',
             ]),
         },
     ],
@@ -68,6 +76,11 @@ const LINE_TYPES = new Map([
                 'toolEndsTurn',
                 'toolDenialKind',
                 'imagePasteIds',
+                'serverClassifierContext',
+                'turnOrigin',
+                'queueSkipAttachments',
+                'turnPosition',
+                'turnCompanion',
             ]),
         },
     ],
@@ -96,13 +109,23 @@ const LINE_TYPES = new Map([
             ]),
         },
     ],
-    ['attachment', { kind: 'attachment', knownFields: fields(ENVELOPE, ['attachment']) }],
+    [
+        'attachment',
+        {
+            kind: 'attachment',
+            knownFields: fields(ENVELOPE, [
+                'attachment',
+                'rendered',
+                'renderedInHumanTurn',
+            ]),
+        },
+    ],
     ['mode', { kind: 'mode', knownFields: fields(['type', 'mode', 'sessionId']) }],
     [
         'last-prompt',
         {
             kind: 'last-prompt',
-            knownFields: fields(['type', 'lastPrompt', 'leafUuid', 'sessionId']),
+            knownFields: fields(['type', 'lastPrompt', 'leafUuid', 'sessionId', 'explicit']),
         },
     ],
     [
@@ -138,7 +161,7 @@ const LINE_TYPES = new Map([
         'queue-operation',
         {
             kind: 'queue-operation',
-            knownFields: fields(['type', 'operation', 'content', 'timestamp', 'sessionId']),
+            knownFields: fields(['type', 'operation', 'content', 'timestamp', 'sessionId', 'reason']),
         },
     ],
     [
@@ -150,6 +173,40 @@ const LINE_TYPES = new Map([
     ],
     ['started', { kind: 'started', knownFields: fields(['type', 'key', 'agentId']) }],
     ['result', { kind: 'result', knownFields: fields(['type', 'key', 'agentId', 'result']) }],
+    ['atis-latch', { kind: 'atis-latch', knownFields: fields(['type', 'atis', 'sessionId']) }],
+    [
+        'cost-state',
+        {
+            kind: 'cost-state',
+            knownFields: fields([
+                'type',
+                'sessionId',
+                'startTime',
+                'totalCostUSD',
+                'totalDuration',
+                'totalAPIDuration',
+                'totalAPIDurationWithoutRetries',
+                'totalToolDuration',
+                'totalLinesAdded',
+                'totalLinesRemoved',
+                'modelUsage',
+                'hasUnknownModelCost',
+            ]),
+        },
+    ],
+    [
+        'fork-context-ref',
+        {
+            kind: 'fork-context-ref',
+            knownFields: fields([
+                'type',
+                'agentId',
+                'parentSessionId',
+                'parentLastUuid',
+                'contextLength',
+            ]),
+        },
+    ],
 ]);
 const EMPTY_RECORD = Object.freeze({});
 function rawTypeKey(value) {

package/dist/src/transcript/version.js

@@ -1 +1 @@
-export const PROJECTOR_VERSION = 10;
+export const PROJECTOR_VERSION = 11;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faithfulalabi/agent-lens",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Local-first agentic tracing platform: inspect everything your agent did in a session.",
   "type": "module",
   "license": "MIT",