@maolon/pi-watcher 0.0.0-stage → 0.1.1

package/dist/source/agent-check/adapter.js

@@ -0,0 +1,224 @@
+/**
+ * agent-check SourceAdapter — agent-declared bounded check command
+ * (agent-declared check source).
+ *
+ * Target: { kind:'run', sourceId:'agent-check', taskId:'check',
+ *           runId:'chk-<digest16>', attemptId:'attempt-1', check:{...} }
+ *
+ * The adapter RUNS the declared command at the watch's poll cadence (engine
+ * schedules read(); read executes). This is bounded probing, never a business
+ * action: timeoutMs hard kill (SIGTERM→SIGKILL 2s), byte-capped capture.
+ *
+ * Verdict mapping (nonzero exit is three-valued; agent declares the mapping):
+ * - broken  : spawn error / exit 126|127 / timeout → state 'unknown' + gap
+ *             (health degraded) — the CHECK is broken; never a task verdict.
+ * - failed  : exitCode ∈ failCodes OR failPattern matches stdout — explicit
+ *             declared failure evidence.
+ * - succeeded: okPattern declared → match required; otherwise exit 0
+ *             (marker philosophy: exit code is explicit evidence).
+ * - pending : any other outcome → 'running' (condition not yet met).
+ * Ordering: broken → declared-fail → declared-ok → pending.
+ *
+ * Evidence economy: log_delta only when output digest changes ("no new
+ * information" is the Jev signal, not a journal row); status only on state
+ * change. Silence therefore means "output and state unchanged for
+ * maxSilenceMs" — stuck-pending surfaces via the silence episode.
+ *
+ * Single-flight per target: overlapping sweeps skip (never double-run).
+ */
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+const MAX_STDOUT_BYTES = 16 * 1024;
+const MAX_STDERR_BYTES = 2 * 1024;
+const MAX_DELTA_LINES = 40;
+const KILL_GRACE_MS = 2000;
+function normalizeCursor(cursor) {
+    const c = cursor;
+    return {
+        lastSeq: typeof c?.lastSeq === 'number' ? c.lastSeq : 0,
+        lastState: typeof c?.lastState === 'string' ? c.lastState : '',
+        lastOutputDigest: typeof c?.lastOutputDigest === 'string' ? c.lastOutputDigest : '',
+        done: c?.done === true
+    };
+}
+const digestOf = (s) => createHash('sha256').update(s).digest('hex').slice(0, 16);
+export class AgentCheckAdapter {
+    adapterId = 'agent-check';
+    capabilities = {
+        stableAttempt: true,
+        terminalEvents: true,
+        incrementalCursor: true,
+        exclusiveNotificationOwner: true
+    };
+    inflight = new Set();
+    runCheck(cmd, cwd, timeoutMs) {
+        return new Promise(resolve => {
+            const startedAt = Date.now();
+            let stdout = '';
+            let stderr = '';
+            let timedOut = false;
+            let settled = false;
+            const child = spawn(cmd, {
+                shell: true,
+                cwd: cwd && cwd.trim() !== '' ? cwd : undefined,
+                env: process.env,
+                windowsHide: true
+            });
+            const finish = (exitCode, spawnError) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(killTimer);
+                clearTimeout(termTimer);
+                resolve({
+                    exitCode,
+                    timedOut,
+                    spawnError,
+                    stdout: stdout.slice(-MAX_STDOUT_BYTES),
+                    stderr: stderr.slice(-MAX_STDERR_BYTES),
+                    durationMs: Date.now() - startedAt
+                });
+            };
+            child.stdout?.on('data', (d) => { if (stdout.length < MAX_STDOUT_BYTES * 2)
+                stdout += d.toString('utf8'); });
+            child.stderr?.on('data', (d) => { if (stderr.length < MAX_STDERR_BYTES * 2)
+                stderr += d.toString('utf8'); });
+            child.on('error', e => finish(null, e.message));
+            child.on('close', code => finish(code, null));
+            // Timeout: SIGTERM, then SIGKILL after 2s; close always arrives after kill (fallback resolve)
+            const termTimer = setTimeout(() => {
+                timedOut = true;
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch { /* already dead */ }
+            }, timeoutMs);
+            const killTimer = setTimeout(() => {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* already dead */ }
+            }, timeoutMs + KILL_GRACE_MS);
+        });
+    }
+    verdictOf(run, check) {
+        // 1. broken -- the check itself is unavailable: never sentence the task to death
+        if (run.spawnError !== null) {
+            return { taskState: 'unknown', exitCode: null, broken: true, summary: `check broken: spawn error — ${run.spawnError}` };
+        }
+        if (run.timedOut) {
+            return { taskState: 'unknown', exitCode: null, broken: true, summary: `check broken: timed out after ${run.durationMs}ms` };
+        }
+        if (run.exitCode === 126 || run.exitCode === 127) {
+            return { taskState: 'unknown', exitCode: run.exitCode, broken: true, summary: `check broken: exit ${run.exitCode} (command not found / not executable)` };
+        }
+        // 2. declared-fail: explicitly declared failure evidence (the pattern also applies to exit 0)
+        if (check.failCodes && run.exitCode !== null && check.failCodes.includes(run.exitCode)) {
+            return { taskState: 'failed', exitCode: run.exitCode, broken: false, summary: `check failed: exit ${run.exitCode} (declared failCode)` };
+        }
+        if (check.failPattern && new RegExp(check.failPattern).test(run.stdout)) {
+            return { taskState: 'failed', exitCode: run.exitCode, broken: false, summary: `check failed: failPattern matched (${summarizeOutput(run)})` };
+        }
+        // 3. declared-ok / exit 0
+        if (check.okPattern) {
+            if (new RegExp(check.okPattern).test(run.stdout)) {
+                return { taskState: 'succeeded', exitCode: run.exitCode, broken: false, summary: `check ok: okPattern matched (${summarizeOutput(run)})` };
+            }
+        }
+        else if (run.exitCode === 0) {
+            return { taskState: 'succeeded', exitCode: 0, broken: false, summary: 'check ok: exit 0' };
+        }
+        // 4. pending
+        return { taskState: 'running', exitCode: run.exitCode, broken: false, summary: `pending: check exit ${run.exitCode ?? 'null'} (${summarizeOutput(run)})` };
+    }
+    async read(target, cursor, _signal) {
+        const check = target.check;
+        const cur = normalizeCursor(cursor);
+        const next = { ...cur };
+        if (!check || typeof check.cmd !== 'string' || check.cmd === '') {
+            // no command to execute: do not fabricate facts
+            return { observations: [], nextCursor: next, gap: true };
+        }
+        if (cur.done) {
+            return { observations: [], nextCursor: next, gap: false }; // terminal already reported
+        }
+        const key = `${target.sourceId}:${target.taskId}:${target.runId}:${target.attemptId}`;
+        if (this.inflight.has(key)) {
+            return { observations: [], nextCursor: next, gap: false }; // single-flight: skip this round
+        }
+        this.inflight.add(key);
+        let run;
+        try {
+            run = await this.runCheck(check.cmd, check.cwd, Math.min(Math.max(check.timeoutMs ?? 10_000, 1_000), 30_000));
+        }
+        finally {
+            this.inflight.delete(key);
+        }
+        const verdict = this.verdictOf(run, check);
+        const observations = [];
+        const now = new Date().toISOString();
+        // log_delta only when output changes (no new information is not an evidence line; feeds Jev's repeating signal)
+        const outputDigest = digestOf(run.stdout + '\u0000' + run.stderr);
+        if (outputDigest !== cur.lastOutputDigest) {
+            const lines = [...run.stdout.split('\n'), ...(run.stderr.trim() !== '' ? [run.stderr.trim()] : [])]
+                .filter(l => l !== '')
+                .slice(-MAX_DELTA_LINES);
+            if (lines.length > 0) {
+                next.lastSeq += 1;
+                observations.push({
+                    schemaVersion: 1,
+                    observationId: `obs-check-${randomUUID()}`,
+                    target,
+                    sourceSeq: next.lastSeq,
+                    observedAt: now,
+                    kind: 'log_delta',
+                    payload: { lines, exitCode: run.exitCode, durationMs: run.durationMs },
+                    evidenceRefs: []
+                });
+            }
+        }
+        next.lastOutputDigest = outputDigest;
+        // status only when the state changes
+        if (verdict.taskState !== cur.lastState) {
+            next.lastSeq += 1;
+            next.lastState = verdict.taskState;
+            observations.push({
+                schemaVersion: 1,
+                observationId: `obs-check-${randomUUID()}`,
+                target,
+                sourceSeq: next.lastSeq,
+                observedAt: now,
+                kind: 'status',
+                payload: {
+                    state: verdict.taskState,
+                    stage: 'check',
+                    exitCode: verdict.exitCode,
+                    summary: verdict.summary
+                },
+                evidenceRefs: []
+            });
+        }
+        if (verdict.taskState === 'succeeded' || verdict.taskState === 'failed') {
+            next.done = true;
+        }
+        // broken -> source degraded (health degraded); not a terminal state, not a task verdict
+        return { observations, nextCursor: next, gap: verdict.broken };
+    }
+    async probes(_target, _basis) {
+        // A check command has no passive artifact to read: the evidence window comes from read()'s log_delta journal;
+        // an active probe would run the command again (double cost), and read() already provides new output at the polling cadence.
+        return [];
+    }
+    async execute(_probe, _signal) {
+        return [];
+    }
+    async close() { }
+}
+function summarizeOutput(run) {
+    const last = run.stdout.trim().split('\n').filter(l => l !== '').slice(-1)[0] ?? '';
+    return last !== '' ? `last: ${last.slice(0, 120)}` : 'no output';
+}
+/** runId of the watch-check tool action: stable digest of the command + verdict mapping (for dedup) */
+export function checkRunId(cmd, verdict) {
+    return `chk-${digestOf(cmd + '\u0000' + (verdict.okPattern ?? '') + '\u0000' + (verdict.failPattern ?? '') + '\u0000' + (verdict.failCodes ?? []).join(','))}`;
+}

package/dist/source/agent-file/adapter.d.ts

@@ -0,0 +1,57 @@
+/**
+ * agent-file SourceAdapter — agent-declared file evidence (universal monitor
+ * mode).
+ *
+ * Target: { kind:'run', sourceId:'agent-file', taskId:'file',
+ *           runId:'file-<digest16>', attemptId:'attempt-1',
+ *           file:{ path, okPattern?, failPattern? } }
+ *
+ * Replaces the removed unified-exec adapter: the agent pins the exact file
+ * path (it holds log_path in the exec tool result), so no foreign-library
+ * naming heuristics, no runId namespace scans, no cross-process collisions.
+ * Exit detection is declared patterns over content — e.g. watching an exec
+ * session log with okPattern='__EXEC_EXIT__:0', failPattern='__EXEC_EXIT__:-?[1-9]'
+ * (the marker itself is a pi-watcher convention injected by the extension).
+ *
+ * Facts (honest, conservative):
+ * - file missing → 'unknown' + gap (degraded) — NOT terminal; may appear later
+ * - rotation/truncation (size < cursor offset) → cursor reset + gap
+ * - growth → bounded incremental log_delta (progress evidence; feeds silence)
+ * - failPattern match on tail window → failed; okPattern match → succeeded
+ *   (fail ordered first: explicit failure evidence outranks ok)
+ * - no pattern hit → 'running' (liveness via lsof fd holders is informational
+ *   only — a generic file's "no holder" is NOT exit evidence, writers may
+ *   write per-open; the removed exec adapter's exited-unknown fabrication
+ *   does not generalize and is gone)
+ * - terminal (pattern) → cursor.done; source stops reading (engine anneals
+ *   and auto-closes)
+ */
+import type { Json, Observation, Probe, RunTarget, SourceAdapter, SourceCapabilities } from '../../contracts/interfaces.js';
+export interface AgentFileCursor {
+    offset: number;
+    lastSeq: number;
+    lastState: string;
+    /** terminal already reported → stop reading */
+    done: boolean;
+}
+export declare class AgentFileAdapter implements SourceAdapter {
+    readonly adapterId = "agent-file";
+    readonly capabilities: SourceCapabilities;
+    /** fd holders (lsof): only running summary info; unavailable -> null (no inference) */
+    private holders;
+    private verdictOf;
+    read(target: RunTarget, cursor: Json | undefined, _signal: AbortSignal): Promise<{
+        observations: Observation[];
+        nextCursor: Json;
+        gap: boolean;
+    }>;
+    private statusObservation;
+    probes(target: RunTarget, _basis: unknown): Promise<readonly Probe[]>;
+    execute(probe: Probe, _signal: AbortSignal): Promise<Observation[]>;
+    close(): Promise<void>;
+}
+/** runId of the watch-file tool action: stable digest of path + patterns (for dedup) */
+export declare function fileRunId(path: string, patterns: {
+    okPattern?: string;
+    failPattern?: string;
+}): string;

package/dist/source/agent-file/adapter.js

@@ -0,0 +1,217 @@
+/**
+ * agent-file SourceAdapter — agent-declared file evidence (universal monitor
+ * mode).
+ *
+ * Target: { kind:'run', sourceId:'agent-file', taskId:'file',
+ *           runId:'file-<digest16>', attemptId:'attempt-1',
+ *           file:{ path, okPattern?, failPattern? } }
+ *
+ * Replaces the removed unified-exec adapter: the agent pins the exact file
+ * path (it holds log_path in the exec tool result), so no foreign-library
+ * naming heuristics, no runId namespace scans, no cross-process collisions.
+ * Exit detection is declared patterns over content — e.g. watching an exec
+ * session log with okPattern='__EXEC_EXIT__:0', failPattern='__EXEC_EXIT__:-?[1-9]'
+ * (the marker itself is a pi-watcher convention injected by the extension).
+ *
+ * Facts (honest, conservative):
+ * - file missing → 'unknown' + gap (degraded) — NOT terminal; may appear later
+ * - rotation/truncation (size < cursor offset) → cursor reset + gap
+ * - growth → bounded incremental log_delta (progress evidence; feeds silence)
+ * - failPattern match on tail window → failed; okPattern match → succeeded
+ *   (fail ordered first: explicit failure evidence outranks ok)
+ * - no pattern hit → 'running' (liveness via lsof fd holders is informational
+ *   only — a generic file's "no holder" is NOT exit evidence, writers may
+ *   write per-open; the removed exec adapter's exited-unknown fabrication
+ *   does not generalize and is gone)
+ * - terminal (pattern) → cursor.done; source stops reading (engine anneals
+ *   and auto-closes)
+ */
+import * as fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+const TAIL_BYTES = 4096;
+const MAX_DELTA_BYTES = 16 * 1024;
+const MAX_DELTA_LINES = 200;
+function normalizeCursor(cursor) {
+    const c = cursor;
+    return {
+        offset: typeof c?.offset === 'number' ? c.offset : 0,
+        lastSeq: typeof c?.lastSeq === 'number' ? c.lastSeq : 0,
+        lastState: typeof c?.lastState === 'string' ? c.lastState : '',
+        done: c?.done === true
+    };
+}
+const digestOf = (s) => createHash('sha256').update(s).digest('hex').slice(0, 16);
+function readTail(logPath) {
+    try {
+        const size = fs.statSync(logPath).size;
+        const len = Math.min(size, TAIL_BYTES);
+        const fh = fs.openSync(logPath, 'r');
+        try {
+            const buf = Buffer.alloc(len);
+            const n = fs.readSync(fh, buf, 0, len, size - len);
+            return buf.subarray(0, n).toString('utf8');
+        }
+        finally {
+            fs.closeSync(fh);
+        }
+    }
+    catch {
+        return '';
+    }
+}
+export class AgentFileAdapter {
+    adapterId = 'agent-file';
+    capabilities = {
+        stableAttempt: true,
+        terminalEvents: true,
+        incrementalCursor: true,
+        exclusiveNotificationOwner: true
+    };
+    /** fd holders (lsof): only running summary info; unavailable -> null (no inference) */
+    holders(filePath) {
+        const r = spawnSync('lsof', ['-t', '--', filePath], { timeout: 2000, encoding: 'utf8' });
+        if (r.error)
+            return null;
+        if (r.status !== 0 && r.status !== 1)
+            return null;
+        return (r.stdout ?? '').trim();
+    }
+    verdictOf(filePath, file, grew) {
+        const tail = readTail(filePath);
+        const lastLine = (tail.split('\n').filter(l => l !== '').slice(-1)[0] ?? '').slice(0, 120);
+        if (file.failPattern && new RegExp(file.failPattern).test(tail)) {
+            return { taskState: 'failed', summary: `failPattern matched in tail (${lastLine})`, gap: false };
+        }
+        if (file.okPattern && new RegExp(file.okPattern).test(tail)) {
+            return { taskState: 'succeeded', summary: `okPattern matched in tail (${lastLine})`, gap: false };
+        }
+        const holder = this.holders(filePath);
+        const liveness = holder === null ? 'liveness unknown (lsof unavailable)' : holder !== '' ? 'writer holds the file' : 'no fd holder (writer may write per-open)';
+        return { taskState: 'running', summary: grew ? `file growing; ${liveness}` : `no new content; ${liveness}`, gap: false };
+    }
+    async read(target, cursor, _signal) {
+        const file = target.file;
+        const cur = normalizeCursor(cursor);
+        const next = { ...cur };
+        if (!file || typeof file.path !== 'string' || file.path === '') {
+            return { observations: [], nextCursor: next, gap: true };
+        }
+        if (cur.done) {
+            return { observations: [], nextCursor: next, gap: false };
+        }
+        let size;
+        try {
+            size = fs.statSync(file.path).size;
+        }
+        catch {
+            // File missing: degraded, non-terminal (may not be created yet)
+            const observations = [];
+            if (cur.lastState !== 'unknown') {
+                next.lastState = 'unknown';
+                next.lastSeq += 1;
+                observations.push(this.statusObservation(target, next.lastSeq, 'unknown', `file not found: ${file.path}`));
+            }
+            return { observations, nextCursor: next, gap: true };
+        }
+        // Rotation/truncation: cursor reset, gap notice
+        let gap = false;
+        if (size < cur.offset) {
+            next.offset = 0;
+            gap = true;
+        }
+        const observations = [];
+        let grew = false;
+        if (size > next.offset) {
+            grew = true;
+            const len = Math.min(size - next.offset, MAX_DELTA_BYTES);
+            let text = '';
+            try {
+                const fh = fs.openSync(file.path, 'r');
+                try {
+                    const buf = Buffer.alloc(len);
+                    const n = fs.readSync(fh, buf, 0, len, next.offset);
+                    text = buf.subarray(0, n).toString('utf8');
+                }
+                finally {
+                    fs.closeSync(fh);
+                }
+            }
+            catch {
+                return { observations, nextCursor: next, gap: true }; // raced away; retry next sweep
+            }
+            let lines = text.split('\n');
+            lines.pop(); // trailing partial line (writer mid-write) — next sweep re-reads from offset
+            if (lines.length > MAX_DELTA_LINES) {
+                lines = [`[... ${lines.length - MAX_DELTA_LINES} earlier lines truncated ...]`, ...lines.slice(-MAX_DELTA_LINES)];
+            }
+            if (lines.length > 0) {
+                next.lastSeq += 1;
+                observations.push({
+                    schemaVersion: 1,
+                    observationId: `obs-file-${randomUUID()}`,
+                    target,
+                    sourceSeq: next.lastSeq,
+                    observedAt: new Date().toISOString(),
+                    kind: 'log_delta',
+                    payload: { lines },
+                    evidenceRefs: []
+                });
+            }
+            next.offset = size;
+        }
+        const verdict = this.verdictOf(file.path, file, grew);
+        if (verdict.taskState !== cur.lastState) {
+            next.lastSeq += 1;
+            next.lastState = verdict.taskState;
+            observations.push(this.statusObservation(target, next.lastSeq, verdict.taskState, verdict.summary));
+        }
+        if (verdict.taskState === 'succeeded' || verdict.taskState === 'failed') {
+            next.done = true;
+        }
+        return { observations, nextCursor: next, gap: gap || verdict.gap };
+    }
+    statusObservation(target, seq, state, summary) {
+        return {
+            schemaVersion: 1,
+            observationId: `obs-file-${randomUUID()}`,
+            target,
+            sourceSeq: seq,
+            observedAt: new Date().toISOString(),
+            kind: 'status',
+            payload: { state, stage: 'file', summary },
+            evidenceRefs: []
+        };
+    }
+    async probes(target, _basis) {
+        return [{
+                probeId: `probe-file-tail-${randomUUID()}`,
+                revision: 1,
+                target,
+                kind: 'read-log-delta',
+                scopeId: 'file-tail',
+                expiresAt: new Date(Date.now() + 30_000).toISOString(),
+                timeoutMs: 2000,
+                maxBytes: TAIL_BYTES
+            }];
+    }
+    async execute(probe, _signal) {
+        const path = probe.target.file?.path;
+        const tail = path ? readTail(path) : '';
+        return [{
+                schemaVersion: 1,
+                observationId: `obs-file-${randomUUID()}`,
+                target: probe.target,
+                sourceSeq: 0,
+                observedAt: new Date().toISOString(),
+                kind: 'log_delta',
+                payload: { probe: 'file-tail', lines: tail.split('\n').slice(-40) },
+                evidenceRefs: []
+            }];
+    }
+    async close() { }
+}
+/** runId of the watch-file tool action: stable digest of path + patterns (for dedup) */
+export function fileRunId(path, patterns) {
+    return `file-${digestOf(path + '\u0000' + (patterns.okPattern ?? '') + '\u0000' + (patterns.failPattern ?? ''))}`;
+}

package/dist/source/task-status-v1/adapter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * task-status-v1 read-only SourceAdapter (design 4.1/4.2).
+ * - snapshot is published via atomic replace; journal is JSONL with stable sequence numbers
+ * - cursor stores file identity + byte offset + lastSeq + snapshotSeq
+ * - only complete JSON lines are accepted; a partial line waits for the next round
+ * - truncation/rotation changes the stream generation -> gap=true; the old cursor is not applied directly
+ */
+import type { Json, Basis, Observation, Probe, RunTarget, SourceAdapter, SourceCapabilities } from '../../contracts/interfaces.js';
+export interface TaskStatusV1Cursor {
+    fileId: string | null;
+    offset: number;
+    lastSeq: number;
+    snapshotSeq: number;
+}
+export interface TaskStatusV1AdapterOptions {
+    adapterId?: string;
+    defaultTimeoutMs?: number;
+    defaultMaxBytes?: number;
+}
+export declare class TaskStatusV1Adapter implements SourceAdapter {
+    private readonly rootDir;
+    readonly adapterId: string;
+    readonly capabilities: SourceCapabilities;
+    private readonly timeoutMs;
+    private readonly maxBytes;
+    constructor(rootDir: string, options?: TaskStatusV1AdapterOptions);
+    private targetDir;
+    read(target: RunTarget, cursor: Json | undefined, signal: AbortSignal): Promise<{
+        observations: Observation[];
+        nextCursor: Json;
+        gap: boolean;
+    }>;
+    probes(target: RunTarget, _basis: Basis): Promise<readonly Probe[]>;
+    execute(probe: Probe, signal: AbortSignal): Promise<Observation[]>;
+    close(): Promise<void>;
+}