@evomap/evolver-core 2.0.0-beta.9 → 2.0.0

package/dist/trace/learningTrace.js

@@ -0,0 +1,276 @@
+// Agent runtime trace instrumentation (Learning Ops slice 1).
+// Aligns with evomap-hub Learning Ops data plane contract (schemaVersion `trace_event.v0` /
+// `learning_packet.v0`): the runtime emits ordered TraceEvents over the agent-run lifecycle and
+// assembles a LearningPacket DRAFT locally. Hub delivery goes through the LearningPacketSink port —
+// core never hardcodes a hub endpoint (file/console/memory sinks let a run trace without hub access).
+import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+export const TRACE_EVENT_SCHEMA = 'trace_event.v0';
+export const LEARNING_PACKET_SCHEMA = 'learning_packet.v0';
+/** Lifecycle vocabulary for slice 1. Kept flat + closed so hub-side eventType stays queryable. */
+export const TRACE_EVENT_TYPES = [
+    'run.started',
+    'run.completed',
+    'model.called',
+    'tool.called',
+    'tool.failed',
+    'retry.attempted',
+    'reflection.recorded',
+    'intervention.received',
+];
+export class InMemoryTraceSink {
+    events = [];
+    emit(event) { this.events.push(event); }
+}
+/** JSONL append sink for local inspection / offline replay. */
+export class FileTraceSink {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    emit(event) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        appendFileSync(this.path, `${JSON.stringify(event)}\n`, 'utf8');
+    }
+}
+export class ConsoleTraceSink {
+    log;
+    constructor(log = (line) => console.error(line)) {
+        this.log = log;
+    }
+    emit(event) { this.log(`[trace] ${event.sequence} ${event.eventType} ${JSON.stringify(event.payload)}`); }
+}
+/**
+ * Per-run trace recorder: the single hook surface the runtime calls at lifecycle points.
+ * Sequence numbers are assigned here (monotonic per run), so downstream ordering never depends on
+ * sink latency or clock resolution.
+ */
+export class AgentRunTraceRecorder {
+    opts;
+    sequence = 0;
+    recorded = [];
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get events() { return this.recorded; }
+    runStarted(input = {}) {
+        return this.record('run.started', {
+            ...(input.taskSummary !== undefined ? { taskSummary: input.taskSummary } : {}),
+            ...(input.signals !== undefined ? { signals: [...input.signals] } : {}),
+            ...(input.geneId !== undefined ? { geneId: input.geneId } : {}),
+        }, input.metadata);
+    }
+    modelCalled(input = {}) {
+        return this.record('model.called', {
+            ...(input.provider !== undefined ? { provider: input.provider } : {}),
+            ...(input.model !== undefined ? { model: input.model } : {}),
+            ...(input.requestId !== undefined ? { requestId: input.requestId } : {}),
+            ...(input.latencyMs !== undefined ? { latencyMs: input.latencyMs } : {}),
+            ...(input.usage !== undefined ? { usage: input.usage } : {}),
+            ...(input.stopReason !== undefined ? { stopReason: input.stopReason } : {}),
+        });
+    }
+    toolCalled(input) {
+        return this.record('tool.called', {
+            toolName: input.toolName,
+            ...(input.callId !== undefined ? { callId: input.callId } : {}),
+            ...(input.durationMs !== undefined ? { durationMs: input.durationMs } : {}),
+        }, input.metadata);
+    }
+    toolFailed(input) {
+        return this.record('tool.failed', {
+            toolName: input.toolName,
+            ...(input.callId !== undefined ? { callId: input.callId } : {}),
+            error: input.error,
+        });
+    }
+    retryAttempted(input) {
+        return this.record('retry.attempted', {
+            attempt: input.attempt,
+            ...(input.reason !== undefined ? { reason: input.reason } : {}),
+            ...(input.target !== undefined ? { target: input.target } : {}),
+        });
+    }
+    reflectionRecorded(input) {
+        return this.record('reflection.recorded', {
+            outcome: input.outcome,
+            ...(input.action !== undefined ? { action: input.action } : {}),
+            ...(input.summary !== undefined ? { summary: input.summary } : {}),
+        });
+    }
+    interventionReceived(input) {
+        return this.record('intervention.received', {
+            kind: input.kind,
+            ...(input.actorId !== undefined ? { actorId: input.actorId } : {}),
+            ...(input.detail !== undefined ? { detail: input.detail } : {}),
+        });
+    }
+    runCompleted(input) {
+        return this.record('run.completed', {
+            status: input.status,
+            ...(input.score !== undefined ? { score: input.score } : {}),
+            ...(input.reason !== undefined ? { reason: input.reason } : {}),
+            ...(input.producedValue !== undefined ? { producedValue: input.producedValue } : {}),
+            ...(input.failureKind !== undefined ? { failureKind: input.failureKind } : {}),
+        });
+    }
+    /** Fold one normalized llm_turn (trace/trajectory.ts) into model.called + tool.called/tool.failed events. */
+    recordLlmTurn(turn) {
+        const out = [this.modelCalled({
+                ...(turn.provider !== null ? { provider: turn.provider } : {}),
+                ...(turn.chosen_model !== null ? { model: turn.chosen_model } : {}),
+                ...(turn.request_id !== null ? { requestId: turn.request_id } : {}),
+                ...(turn.latency_ms !== null ? { latencyMs: turn.latency_ms } : {}),
+                ...(turn.usage !== undefined ? { usage: { ...turn.usage } } : {}),
+                ...(typeof turn.stop_reason === 'string' ? { stopReason: turn.stop_reason } : {}),
+            })];
+        if (Array.isArray(turn.tool_calls)) {
+            for (const call of turn.tool_calls) {
+                const rec = call;
+                const toolName = typeof rec.name === 'string' && rec.name.length > 0 ? rec.name : 'unknown_tool';
+                const callId = typeof rec.id === 'string' ? rec.id : undefined;
+                out.push(typeof rec.error === 'string' && rec.error.length > 0
+                    ? this.toolFailed({ toolName, ...(callId !== undefined ? { callId } : {}), error: rec.error })
+                    : this.toolCalled({ toolName, ...(callId !== undefined ? { callId } : {}) }));
+            }
+        }
+        return out;
+    }
+    record(eventType, payload, metadata) {
+        this.sequence += 1;
+        const at = (this.opts.now ?? Date.now)();
+        const event = {
+            schemaVersion: TRACE_EVENT_SCHEMA,
+            eventId: (this.opts.eventIdFactory ?? ((seq) => `${this.opts.runId}-${String(seq).padStart(4, '0')}`))(this.sequence),
+            eventType,
+            traceId: this.opts.runId,
+            ...(this.opts.sessionId !== undefined ? { sessionId: this.opts.sessionId } : {}),
+            ...(this.opts.taskId !== undefined ? { taskId: this.opts.taskId } : {}),
+            sequence: this.sequence,
+            occurredAt: new Date(at).toISOString(),
+            payload,
+            metadata: metadata ?? {},
+        };
+        this.recorded.push(event);
+        this.opts.sink?.emit(event);
+        return event;
+    }
+}
+/* ── Root-event bridge: existing cycle lifecycle → trace events, via the sanctioned ObserverBus ── */
+const BRIDGED_EVENT_TYPES = [
+    'cycle.started', 'cycle.solidified', 'cycle.failed',
+    'reflection.recorded',
+    'actor.human.nudge', 'actor.human.intervene', 'actor.human.teach',
+    'actor.human.review.approve', 'actor.human.review.reject',
+];
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+/**
+ * Bypass-side bridge (never blocks the write path): maps the engine's existing root events onto the
+ * run's TraceEvent stream, so CycleEngine needs no code change for run start/completion, reflection,
+ * or human intervention coverage.
+ */
+export function learningTraceObserver(deps) {
+    const meta = {
+        name: 'learning_trace',
+        eventTypes: BRIDGED_EVENT_TYPES,
+        idempotent: true,
+        timeoutMs: deps.timeoutMs ?? 2_000,
+    };
+    return {
+        meta,
+        handle(event) {
+            const payload = asRecord(event.payload) ?? {};
+            if (event.type === 'cycle.started') {
+                deps.recorder.runStarted({ metadata: { cycleId: payload['cycleId'] ?? null } });
+                return;
+            }
+            if (event.type === 'cycle.solidified' || event.type === 'cycle.failed') {
+                const outcome = asRecord(payload['outcome']);
+                const status = event.type === 'cycle.solidified' ? 'success' : 'failed';
+                const score = typeof outcome?.['score'] === 'number' ? outcome['score'] : undefined;
+                const reason = typeof payload['error'] === 'string'
+                    ? payload['error']
+                    : typeof payload['reason'] === 'string' ? payload['reason'] : undefined;
+                deps.recorder.runCompleted({
+                    status,
+                    ...(score !== undefined ? { score } : {}),
+                    ...(reason !== undefined ? { reason } : {}),
+                    ...(typeof payload['producedValue'] === 'boolean' ? { producedValue: payload['producedValue'] } : {}),
+                    ...(typeof payload['failureKind'] === 'string' ? { failureKind: payload['failureKind'] } : {}),
+                });
+                return;
+            }
+            if (event.type === 'reflection.recorded') {
+                deps.recorder.reflectionRecorded({
+                    outcome: typeof payload['outcome'] === 'string' ? payload['outcome'] : 'unknown',
+                    ...(typeof payload['action'] === 'string' ? { action: payload['action'] } : {}),
+                    ...(typeof payload['summary'] === 'string' ? { summary: payload['summary'] } : {}),
+                });
+                return;
+            }
+            // actor.human.*: host/human intervention audit trail.
+            deps.recorder.interventionReceived({
+                kind: event.type.replace(/^actor\.human\./, ''),
+                ...(event.actor.id !== undefined ? { actorId: event.actor.id } : {}),
+                ...(typeof payload['detail'] === 'string' ? { detail: payload['detail'] } : {}),
+            });
+        },
+    };
+}
+export function buildLearningPacketDraft(recorder, input) {
+    const events = [...recorder.events].sort((a, b) => a.sequence - b.sequence);
+    const first = events[0];
+    const completed = [...events].reverse().find((e) => e.eventType === 'run.completed');
+    const completedStatus = completed?.payload['status'];
+    const failureKind = completed?.payload['failureKind'];
+    const started = events.find((e) => e.eventType === 'run.started');
+    const startedSummary = started?.payload['taskSummary'];
+    return {
+        schemaVersion: LEARNING_PACKET_SCHEMA,
+        status: 'draft',
+        source: { repo: input.sourceRepo, run: first?.traceId ?? 'unknown-run', type: 'agent_run', id: first?.traceId ?? 'unknown-run' },
+        task: {
+            taskId: first?.taskId ?? null,
+            summary: input.taskSummary ?? (typeof startedSummary === 'string' ? startedSummary : null),
+            signals: [...(input.signals ?? [])],
+        },
+        context: {
+            sessionId: first?.sessionId ?? null,
+            traceId: first?.traceId ?? 'unknown-run',
+            environment: input.environment ?? {},
+        },
+        trajectory: events,
+        artifacts: { placeholder: true, items: [] },
+        evaluation: {
+            placeholder: input.verification === undefined,
+            outcomeStatus: completedStatus === 'success' ? 'success' : completedStatus === 'failed' ? 'failed' : 'unknown',
+            verifier: input.verification?.verifier ?? null,
+            ...(input.verification !== undefined ? { verifierPassed: input.verification.passed } : {}),
+            ...(input.verification?.score !== undefined ? { verifierScore: input.verification.score } : {}),
+            failureCategory: typeof failureKind === 'string' ? failureKind : null,
+        },
+        governance: { placeholder: true, redactionStatus: 'metadata_only', consentStatus: 'unknown', trainingEligible: false, retentionPolicy: 'standard' },
+    };
+}
+export class InMemoryLearningPacketSink {
+    drafts = [];
+    async submit(draft) {
+        this.drafts.push(draft);
+        return { accepted: true };
+    }
+}
+/** Writes one JSON file per run — the offline/no-hub path (and a manual-inspection artifact). */
+export class FileLearningPacketSink {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    async submit(draft) {
+        mkdirSync(this.dir, { recursive: true });
+        const path = `${this.dir}/${draft.source.run}.learning-packet.json`;
+        writeFileSync(path, `${JSON.stringify(draft, null, 2)}\n`, 'utf8');
+        return { accepted: true, reason: path };
+    }
+}

package/dist/trace/proxyTurns.d.ts

@@ -0,0 +1,31 @@
+import { type TraceReadOptions } from './trajectoryExport.js';
+import { type TraceTurnDraft } from './trajectory.js';
+/** One agent run's wall-clock window (epoch ms, same host clock as the proxy's ts). */
+export interface RunTurnWindow {
+    startMs: number;
+    endMs: number;
+}
+export interface SelectRunLlmTurnsOptions {
+    /**
+     * Exact-match correlation key: when the caller knows the spawned agent's session id, only that session's
+     * turns are returned (the window heuristic is skipped — the id is authoritative).
+     */
+    sessionId?: string;
+}
+export interface CollectRunLlmTurnsOptions extends SelectRunLlmTurnsOptions {
+    /** Decryption material forwarded to readTraceRowsFromJsonl. allowPartial is always forced on. */
+    readOptions?: TraceReadOptions;
+}
+/**
+ * Pure selector (unit-testable without fs): pick the turns that belong to the run per the correlation
+ * contract above, sorted by ts ascending (stable — equal timestamps keep day-file append order, and the
+ * recorder's fold order becomes the sequence order).
+ */
+export declare function selectRunLlmTurns(turns: readonly TraceTurnDraft[], window: RunTurnWindow, opts?: SelectRunLlmTurnsOptions): TraceTurnDraft[];
+/**
+ * Read the proxy trace day-files in `dir` and return this run's llm_turns (see the correlation contract
+ * above), ready to fold via recordLlmTurn. Reuses readTraceRowsFromJsonl (decryption + row parsing) and
+ * traceRecordToTurnDraft (normalization). Never throws: any failure — no proxy, missing dir, unreadable
+ * file, undecryptable rows — degrades to [].
+ */
+export declare function collectRunLlmTurns(dir: string, window: RunTurnWindow, opts?: CollectRunLlmTurnsOptions): TraceTurnDraft[];

package/dist/trace/proxyTurns.js

@@ -0,0 +1,137 @@
+// Proxy llm_turn → run fold (Learning Ops slice 5): collect the per-request llm_turn records the LLM proxy
+// captured DURING one agent run's wall-clock window, normalized as TraceTurnDrafts ready for
+// AgentRunTraceRecorder.recordLlmTurn. This is what upgrades a run's trajectory from the bridge's single
+// coarse model.called (the headless runner is a black box) to real per-request fidelity
+// (provider/model/usage/latency/stop_reason + tool-call detail).
+//
+// Correlation contract (why time window + session-first-turn, not session_id alone): the headless runner does
+// not report its session id back to the bridge (`claude -p --output-format text` is opaque), and llm_turn rows
+// carry no cwd — so the run has no exact key to look up. What the run DOES own is its wall-clock window on the
+// same host the proxy writes from (one shared clock, no skew). A turn belongs to the run iff:
+//   1. its ts falls inside [startMs, endMs], AND
+//   2. its session's FIRST observed turn also falls inside the window — a session spawned by this run cannot
+//      have traffic predating the run, while a concurrent interactive session (started earlier) is excluded by
+//      its pre-window history. Sessionless turns (session_id null) fall back to the window test alone.
+// Callers that DO know the spawned agent's session id (e.g. a future runner passing --session-id) can pass
+// `sessionId` for exact-match correlation instead of the heuristic.
+//
+// Residual risk, accepted + documented: an interactive session whose very first request starts inside the run
+// window is indistinguishable from the run's own agent. On an unattended daemon host this is rare, and the
+// fold is observability-only — it can bias a trace, never a verdict.
+//
+// Everything degrades silently to [] (missing dir, unreadable file, undecryptable envelope, bad ts): the
+// learning trace must never fail or slow a task.
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readTraceRowsFromJsonl } from './trajectoryExport.js';
+import { traceRecordToTurnDraft } from './trajectory.js';
+/** Any proxy day-file (`llm-trace-*.jsonl`). */
+const TRACE_FILE_RE = /^llm-trace-.*\.jsonl$/i;
+/** The canonical day-stamped name the proxy's JsonlTraceSink writes (`llm-trace-YYYYMMDD.jsonl`, UTC). */
+const DAY_STAMPED_FILE_RE = /^llm-trace-(\d{8})\.jsonl$/i;
+function utcDayStamp(ms) {
+    const d = new Date(ms);
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}`;
+}
+/**
+ * Keep day-stamped files that could contain the window's turns. Heuristic correlation must inspect all earlier
+ * day files to prove that an in-window session did not start before the run; exact session-id correlation only
+ * needs files that overlap the run window.
+ * Non-day-stamped `llm-trace-*.jsonl` names (custom sinks/tests) are kept conservatively — the ts window
+ * filter below is the authority; the filename filter only trims read volume.
+ */
+function fileCoversWindow(name, window, includeSessionHistory) {
+    const match = DAY_STAMPED_FILE_RE.exec(name);
+    if (!match)
+        return true;
+    const stamp = match[1];
+    return (includeSessionHistory || stamp >= utcDayStamp(window.startMs)) && stamp <= utcDayStamp(window.endMs);
+}
+function turnTsMs(turn) {
+    if (turn.ts === null)
+        return null;
+    const ms = Date.parse(turn.ts);
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * Pure selector (unit-testable without fs): pick the turns that belong to the run per the correlation
+ * contract above, sorted by ts ascending (stable — equal timestamps keep day-file append order, and the
+ * recorder's fold order becomes the sequence order).
+ */
+export function selectRunLlmTurns(turns, window, opts = {}) {
+    const stamped = turns
+        .map((turn) => ({ turn, tsMs: turnTsMs(turn) }))
+        .filter((entry) => entry.tsMs !== null);
+    let selected;
+    if (opts.sessionId !== undefined) {
+        selected = stamped.filter(({ turn }) => turn.session_id === opts.sessionId);
+    }
+    else {
+        // First observed turn per session across ALL provided turns (including pre-window rows from the same
+        // day files) — this is what tells an in-run spawned session apart from an older concurrent one.
+        const firstTsBySession = new Map();
+        for (const { turn, tsMs } of stamped) {
+            if (turn.session_id === null)
+                continue;
+            const prev = firstTsBySession.get(turn.session_id);
+            if (prev === undefined || tsMs < prev)
+                firstTsBySession.set(turn.session_id, tsMs);
+        }
+        selected = stamped.filter(({ turn, tsMs }) => {
+            if (tsMs < window.startMs || tsMs > window.endMs)
+                return false;
+            if (turn.session_id === null)
+                return true;
+            const firstTs = firstTsBySession.get(turn.session_id);
+            return firstTs !== undefined && firstTs >= window.startMs;
+        });
+    }
+    return selected
+        .map((entry, index) => ({ ...entry, index }))
+        .sort((a, b) => a.tsMs - b.tsMs || a.index - b.index)
+        .map(({ turn }) => turn);
+}
+/**
+ * Read the proxy trace day-files in `dir` and return this run's llm_turns (see the correlation contract
+ * above), ready to fold via recordLlmTurn. Reuses readTraceRowsFromJsonl (decryption + row parsing) and
+ * traceRecordToTurnDraft (normalization). Never throws: any failure — no proxy, missing dir, unreadable
+ * file, undecryptable rows — degrades to [].
+ */
+export function collectRunLlmTurns(dir, window, opts = {}) {
+    try {
+        if (!(window.endMs >= window.startMs))
+            return [];
+        const names = readdirSync(dir)
+            .filter((name) => TRACE_FILE_RE.test(name) && fileCoversWindow(name, window, opts.sessionId === undefined))
+            .sort();
+        const turns = [];
+        for (const name of names) {
+            const dayMatch = DAY_STAMPED_FILE_RE.exec(name);
+            const isHistoricalDay = opts.sessionId === undefined
+                && dayMatch !== null
+                && dayMatch[1] < utcDayStamp(window.startMs);
+            let text;
+            try {
+                text = readFileSync(join(dir, name), 'utf8');
+            }
+            catch {
+                continue;
+            }
+            // allowPartial forced on: an undecryptable envelope is a coverage gap, never a fold failure.
+            const { rows } = readTraceRowsFromJsonl(text, { ...(opts.readOptions ?? {}), allowPartial: true });
+            for (const row of rows) {
+                const turn = traceRecordToTurnDraft(row);
+                if (turn !== null) {
+                    // Older day files establish that a session predates this run; they can never contribute candidate
+                    // turns even if a malformed row carries an in-window timestamp.
+                    turns.push(isHistoricalDay ? { ...turn, ts: new Date(window.startMs - 1).toISOString() } : turn);
+                }
+            }
+        }
+        return selectRunLlmTurns(turns, window, opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {});
+    }
+    catch {
+        return [];
+    }
+}

package/dist/verify/sandboxRunner.d.ts

@@ -19,13 +19,41 @@ export interface SandboxOptions {
      * unprivileged mount namespaces are unavailable. Binaries live outside these dirs, so the command still runs.
      */
     hideHomeSecrets?: boolean;
+    /** Remount the inherited filesystem read-only inside the mount namespace, leaving only an isolated /tmp writable. */
+    readOnlyFilesystem?: boolean;
+    /** Host scratch directory exposed as the sandbox's only writable filesystem. */
+    writableTmpDir?: string;
+    /** Read-only checkout root remounted at its original absolute path after HOME and /tmp are hidden. */
+    readOnlyRoot?: string;
+    /** Put the full command tree in a bounded cgroup v2. Required by verified Skill execution. */
+    resourceLimits?: boolean;
     /** Injected unshare-availability probe (test seam). Default: a real `unshare -r -m -n true` check (cached). */
     unshareCheck?: () => boolean;
+    /** Injected cgroup allocator (test seam). */
+    resourceGroupFactory?: () => SandboxResourceGroup | null;
 }
+export interface SandboxResourceGroup {
+    procsFile: string;
+    cleanup: () => void;
+}
+/** Configure an already-created cgroup. Kept separate so limit values are testable without resource exhaustion. */
+export declare function configureSandboxResourceGroup(path: string): boolean;
+/** Allocate a delegated cgroup v2 for one validation command. Returns null unless every limit is enforceable. */
+export declare function createSandboxResourceGroup(): SandboxResourceGroup | null;
+/** Join the cgroup before exec, so attacker-controlled code never runs outside the aggregate resource budget. */
+export declare function resourceLimitedCommand(cmd: string, args: readonly string[], procsFile: string): {
+    cmd: string;
+    args: string[];
+};
+export declare function sandboxResourceLimitsAvailable(): boolean;
 /** Wrap an (executable,args) in unprivileged namespaces per the requested isolation (pure — testable). */
 export declare function isolationCommand(bin: string, args: readonly string[], opts: {
     noNetwork?: boolean;
     hideHomeSecrets?: boolean;
+    readOnlyFilesystem?: boolean;
+    writableTmpDir?: string;
+    readOnlyRoot?: string;
+    cwd?: string;
 }): {
     cmd: string;
     args: string[];