cognitive-core 0.2.4 → 0.3.1

package/dist/learning/replay-executor.d.ts

@@ -0,0 +1,64 @@
+/**
+ * AgentReplayExecutor — the live-rollout half of {@link LiveReplay}.
+ *
+ * Re-runs an experience's task with a *specific candidate playbook* forced
+ * into the agent's context, then verifies the real outcome and maps it to a
+ * score on [0, 1]. This is what makes `LiveReplay` usable: the judge adapter
+ * delegates the actual execution here.
+ *
+ * It reuses the same primitives `atlas.solve()` chains for forward solving —
+ * `AgentManager.spawn` + an `OutcomeVerifier` — but in *replay* form: instead
+ * of letting the router select playbooks, it pins `injectedKnowledge` to the
+ * candidate so the rollout tests THAT playbook specifically.
+ *
+ * ## Statefulness caveat
+ * An `Experience` records the task input and outcome, not the environment it
+ * ran in (repo commit, workspace files, ...). For **stateless** tasks
+ * (benchmark-style: the task text fully determines the problem) the replay is
+ * faithful and a domain `OutcomeVerifier` gives a real score. For **stateful**
+ * tasks the original environment isn't reconstructed, so the score reflects a
+ * fresh run rather than the exact original conditions. Supply a verifier that
+ * matches your domain; the default {@link PassThroughOutcomeVerifier} yields a
+ * binary self-reported-success score (1.0 / 0.0).
+ */
+import type { Playbook } from '../types/playbook.js';
+import type { Experience } from '../types/memory.js';
+import type { Task } from '../types/task.js';
+import type { AgentManager } from '../runtime/manager.js';
+import type { OutcomeVerifier } from '../search/evaluator.js';
+import type { ReplayExecutor } from './replay.js';
+import type { EnvironmentProvider } from './replay-types.js';
+export interface AgentReplayExecutorConfig {
+    /** Agent type to spawn (e.g. 'claude-code', 'mock'). Required. */
+    agentType: string;
+    /** Verifier mapping the rollout outcome to acceptable/not (default: pass-through). */
+    verifier?: OutcomeVerifier;
+    /** Per-rollout timeout (ms), forwarded to the spawn config. */
+    timeoutMs?: number;
+    /** Reconstruct a Task from an Experience (default: taskInput + domain). */
+    reconstructTask?: (experience: Experience) => Task;
+    /**
+     * Rebuilds the per-experience environment (env-MCP, cwd, verifier) so the
+     * rollout runs under the original conditions. When omitted, replays run
+     * statelessly (faithful only for hermetic tasks). The reconstructed env's
+     * fields override the executor defaults for that run.
+     */
+    environmentProvider?: EnvironmentProvider;
+}
+export declare class AgentReplayExecutor implements ReplayExecutor {
+    private readonly agentManager;
+    private readonly agentType;
+    private readonly verifier;
+    private readonly timeoutMs?;
+    private readonly reconstructTask;
+    private readonly environmentProvider?;
+    constructor(agentManager: AgentManager, config: AgentReplayExecutorConfig);
+    /**
+     * Re-solve the experience's task with `playbook` pinned in context and
+     * return a score on [0, 1] for the verified outcome. When an environment
+     * provider reconstructs the original env, the rollout runs under it.
+     */
+    run(playbook: Playbook, experience: Experience): Promise<number>;
+}
+export declare function createAgentReplayExecutor(agentManager: AgentManager, config: AgentReplayExecutorConfig): AgentReplayExecutor;
+//# sourceMappingURL=replay-executor.d.ts.map

package/dist/learning/replay-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-executor.d.ts","sourceRoot":"","sources":["../../src/learning/replay-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,MAAM,WAAW,yBAAyB;IACxC,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;IACnD;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C;AAED,qBAAa,mBAAoB,YAAW,cAAc;IACxD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmC;IACnE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAsB;gBAE/C,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,yBAAyB;IAWzE;;;;OAIG;IACG,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;CA6CvE;AAED,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,yBAAyB,GAChC,mBAAmB,CAErB"}

package/dist/learning/replay-executor.js

@@ -0,0 +1,92 @@
+/**
+ * AgentReplayExecutor — the live-rollout half of {@link LiveReplay}.
+ *
+ * Re-runs an experience's task with a *specific candidate playbook* forced
+ * into the agent's context, then verifies the real outcome and maps it to a
+ * score on [0, 1]. This is what makes `LiveReplay` usable: the judge adapter
+ * delegates the actual execution here.
+ *
+ * It reuses the same primitives `atlas.solve()` chains for forward solving —
+ * `AgentManager.spawn` + an `OutcomeVerifier` — but in *replay* form: instead
+ * of letting the router select playbooks, it pins `injectedKnowledge` to the
+ * candidate so the rollout tests THAT playbook specifically.
+ *
+ * ## Statefulness caveat
+ * An `Experience` records the task input and outcome, not the environment it
+ * ran in (repo commit, workspace files, ...). For **stateless** tasks
+ * (benchmark-style: the task text fully determines the problem) the replay is
+ * faithful and a domain `OutcomeVerifier` gives a real score. For **stateful**
+ * tasks the original environment isn't reconstructed, so the score reflects a
+ * fresh run rather than the exact original conditions. Supply a verifier that
+ * matches your domain; the default {@link PassThroughOutcomeVerifier} yields a
+ * binary self-reported-success score (1.0 / 0.0).
+ */
+import { createTask } from '../types/task.js';
+import { PassThroughOutcomeVerifier } from '../search/evaluator.js';
+export class AgentReplayExecutor {
+    agentManager;
+    agentType;
+    verifier;
+    timeoutMs;
+    reconstructTask;
+    environmentProvider;
+    constructor(agentManager, config) {
+        this.agentManager = agentManager;
+        this.agentType = config.agentType;
+        this.verifier = config.verifier ?? new PassThroughOutcomeVerifier();
+        this.timeoutMs = config.timeoutMs;
+        this.reconstructTask =
+            config.reconstructTask ??
+                ((exp) => createTask({ description: exp.taskInput, domain: exp.domain }));
+        this.environmentProvider = config.environmentProvider;
+    }
+    /**
+     * Re-solve the experience's task with `playbook` pinned in context and
+     * return a score on [0, 1] for the verified outcome. When an environment
+     * provider reconstructs the original env, the rollout runs under it.
+     */
+    async run(playbook, experience) {
+        const task = this.reconstructTask(experience);
+        const env = (await this.environmentProvider?.reconstruct(experience)) ?? null;
+        try {
+            const result = await this.agentManager.spawn({
+                agentType: env?.agentType ?? this.agentType,
+                task,
+                timeout: this.timeoutMs,
+                // Isolated replay: a stateful delegate is pointed at THIS task and its
+                // cost/current-task state is saved+restored around the rollout, so a
+                // replay can't corrupt the solve path (see AgentSpawnConfig.replay).
+                replay: true,
+                // Re-attach the captured per-task environment (env-MCP and/or a
+                // rematerialized workspace) so the rollout sees the original world.
+                // cwd/mcpServers are env-absolute by design (no executor default to
+                // fall back to); only agentType/verifier have executor defaults.
+                mcpServers: env?.mcpServers,
+                cwd: env?.cwd,
+                // Force exactly this candidate into the agent's context — bypasses the
+                // router's queryV2 selection so the rollout tests THIS playbook.
+                injectedKnowledge: {
+                    experiences: [],
+                    playbooks: [{ playbook, score: 1, matchType: 'situation' }],
+                },
+            });
+            const verifier = env?.verifier ?? this.verifier;
+            const verdict = await verifier.verify(task, { success: result.success, trajectory: result.trajectory }, result.trajectory);
+            return verdict.acceptable ? 1 : 0;
+        }
+        finally {
+            // Release any allocated env (e.g. a materialized worktree). Swallow a
+            // dispose error so it can't mask the real spawn/verify result or error.
+            try {
+                await env?.dispose?.();
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+}
+export function createAgentReplayExecutor(agentManager, config) {
+    return new AgentReplayExecutor(agentManager, config);
+}
+//# sourceMappingURL=replay-executor.js.map

package/dist/learning/replay-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-executor.js","sourceRoot":"","sources":["../../src/learning/replay-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAsBpE,MAAM,OAAO,mBAAmB;IACb,YAAY,CAAe;IAC3B,SAAS,CAAS;IAClB,QAAQ,CAAkB;IAC1B,SAAS,CAAU;IACnB,eAAe,CAAmC;IAClD,mBAAmB,CAAuB;IAE3D,YAAY,YAA0B,EAAE,MAAiC;QACvE,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,IAAI,0BAA0B,EAAE,CAAC;QACpE,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,eAAe;YAClB,MAAM,CAAC,eAAe;gBACtB,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC5E,IAAI,CAAC,mBAAmB,GAAG,MAAM,CAAC,mBAAmB,CAAC;IACxD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAG,CAAC,QAAkB,EAAE,UAAsB;QAClD,MAAM,IAAI,GAAG,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;QAC9C,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC,IAAI,IAAI,CAAC;QAE9E,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC;gBAC3C,SAAS,EAAE,GAAG,EAAE,SAAS,IAAI,IAAI,CAAC,SAAS;gBAC3C,IAAI;gBACJ,OAAO,EAAE,IAAI,CAAC,SAAS;gBACvB,uEAAuE;gBACvE,qEAAqE;gBACrE,qEAAqE;gBACrE,MAAM,EAAE,IAAI;gBACZ,gEAAgE;gBAChE,oEAAoE;gBACpE,oEAAoE;gBACpE,iEAAiE;gBACjE,UAAU,EAAE,GAAG,EAAE,UAAU;gBAC3B,GAAG,EAAE,GAAG,EAAE,GAAG;gBACb,uEAAuE;gBACvE,iEAAiE;gBACjE,iBAAiB,EAAE;oBACjB,WAAW,EAAE,EAAE;oBACf,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;iBAC5D;aACF,CAAC,CAAC;YAEH,MAAM,QAAQ,GAAG,GAAG,EAAE,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC;YAChD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,CACnC,IAAI,EACJ,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,EAC1D,MAAM,CAAC,UAAU,CAClB,CAAC;YAEF,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC;gBAAS,CAAC;YACT,sEAAsE;YACtE,wEAAwE;YACxE,IAAI,CAAC;gBACH,MAAM,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACP,sBAAsB;YACxB,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,MAAM,UAAU,yBAAyB,CACvC,YAA0B,EAC1B,MAAiC;IAEjC,OAAO,IAAI,mBAAmB,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;AACvD,CAAC"}

package/dist/learning/replay-types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Replay environment reconstruction — Phase 1 of stateful live replay.
+ *
+ * `LiveReplay` re-runs a task to score a candidate playbook, but a faithful
+ * re-run needs the original *environment*, not just the task text. This
+ * module captures a compact, reconstructable descriptor of that environment
+ * at solve time (stored on `experience.metadata.replay`) and rebuilds it at
+ * replay time.
+ *
+ * Scope (Phase 1): environments that can be re-attached from a descriptor —
+ * per-task env-MCP servers and/or a working directory, optionally enriched
+ * by the caller with a stable `envHandle` + `verifierId`. Environments that
+ * can't be reconstructed (most ephemeral coding tasks) yield `null` from the
+ * provider, and the gating layer falls back to a cheaper judge rather than
+ * scoring an unfaithful rollout.
+ */
+import type { McpServerSpec } from '../runtime/types.js';
+import type { OutcomeVerifier } from '../search/evaluator.js';
+import type { Experience } from '../types/memory.js';
+/** Where the descriptor lives on an experience. */
+export declare const REPLAY_METADATA_KEY = "replay";
+/**
+ * Compact, persisted description of the environment a task ran in — enough
+ * to re-attach it for a faithful replay. Stored at
+ * `experience.metadata.replay`. Data-only (no functions): verifier
+ * resolution goes through a registry keyed by `verifierId`.
+ */
+export interface ReplayDescriptor {
+    /** Schema version (forward-compat). */
+    v: 1;
+    /**
+     * Whether this environment can be faithfully reconstructed. When false,
+     * the provider returns null and gating falls back to a cheaper judge.
+     */
+    reconstructable: boolean;
+    /** Agent type used at solve time. */
+    agentType?: string;
+    /** Working directory the task ran in (fs-backed tasks). */
+    cwd?: string;
+    /**
+     * Per-task env-MCP spec to re-mount on replay. SECRETS ARE STRIPPED
+     * (`env` / `headers`) before persisting — see `secretsRedacted`. A domain
+     * whose env needs credentials must supply a custom {@link EnvironmentProvider}
+     * that re-injects them from a handle.
+     */
+    mcpServers?: McpServerSpec[];
+    /** True if credential fields were removed from `mcpServers`. */
+    secretsRedacted?: boolean;
+    /**
+     * Regime B: a captured workspace snapshot to rematerialize for a faithful
+     * rollout (ephemeral coding tasks). `ref`/`repo` are the snapshot handle;
+     * the verification command scores the replayed end-state in the
+     * materialized worktree.
+     */
+    snapshot?: {
+        /** Git commit sha anchoring the snapshot (filled by capture). */
+        ref?: string;
+        /** Repo the snapshot's objects live in (filled by capture). */
+        repo?: string;
+        /** Command run in the materialized worktree; success ⇒ score 1. */
+        verifyCommand?: string;
+        /** Optional regex (source) the command output must match to pass. */
+        successPattern?: string;
+    };
+    /**
+     * Stable, domain-defined handle for rebuilding the env (preferred over the
+     * literal, possibly-ephemeral `mcpServers`). E.g. `{ bench, taskId, seed }`.
+     * Opaque to cognitive-core; consumed only by a custom provider.
+     */
+    envHandle?: Record<string, unknown>;
+    /** Key into the verifier registry; falls back to pass-through if unknown. */
+    verifierId?: string;
+}
+/** A reconstructed environment, merged into the replay spawn config. */
+export interface ReplayEnvironment {
+    mcpServers?: McpServerSpec[];
+    cwd?: string;
+    agentType?: string;
+    verifier?: OutcomeVerifier;
+    /** Release resources allocated for this env (e.g. a materialized worktree). */
+    dispose?(): Promise<void>;
+}
+/**
+ * Rebuilds the environment for an experience. `isReplayable` is a cheap,
+ * synchronous check used for routing (don't allocate just to decide);
+ * `reconstruct` does the real (possibly async, resource-allocating) work and
+ * returns an env with an optional `dispose`, or null when faithful replay
+ * isn't possible. The seam for domains to rebuild envs from a handle.
+ */
+export interface EnvironmentProvider {
+    isReplayable(experience: Experience): boolean;
+    reconstruct(experience: Experience): Promise<ReplayEnvironment | null>;
+}
+/** Registry mapping `verifierId` → concrete verifier (keeps the DB data-only). */
+export declare class ReplayVerifierRegistry {
+    private readonly map;
+    register(id: string, verifier: OutcomeVerifier): void;
+    get(id: string | undefined): OutcomeVerifier | undefined;
+}
+/** Read + validate the descriptor off an experience, or null. */
+export declare function readReplayDescriptor(experience: Experience): ReplayDescriptor | null;
+/**
+ * Default provider: reconstructs from the persisted descriptor and resolves
+ * the verifier from a registry. Returns null unless `reconstructable`.
+ * Returns the (redacted) `mcpServers` as-is — sufficient for envs that need
+ * no credentials; cred-bearing envs need a custom provider.
+ */
+export declare class DefaultEnvironmentProvider implements EnvironmentProvider {
+    private readonly verifiers?;
+    constructor(verifiers?: ReplayVerifierRegistry | undefined);
+    isReplayable(experience: Experience): boolean;
+    reconstruct(experience: Experience): Promise<ReplayEnvironment | null>;
+}
+/**
+ * Tries each provider in order; the first that reports `isReplayable`
+ * handles the experience. Lets Phase 1 (env-MCP) and Phase 2 (workspace
+ * snapshot) providers coexist — put the more specific (snapshot) first.
+ */
+export declare class CompositeEnvironmentProvider implements EnvironmentProvider {
+    private readonly providers;
+    constructor(providers: EnvironmentProvider[]);
+    isReplayable(experience: Experience): boolean;
+    reconstruct(experience: Experience): Promise<ReplayEnvironment | null>;
+}
+/**
+ * Build a descriptor from the env used at solve time. `reconstructable`
+ * defaults to "an env-MCP was attached" — a conservative default that keeps
+ * ephemeral, env-less tasks (which we can't tell apart from stateful ones)
+ * out of faithful replay. A caller that knows better enriches via `hint`
+ * (e.g. a stable `envHandle`, a `verifierId`, or an explicit `reconstructable`).
+ */
+export declare function buildReplayDescriptor(env: {
+    mcpServers?: McpServerSpec[];
+    cwd?: string;
+    agentType?: string;
+}, hint?: Partial<ReplayDescriptor>): ReplayDescriptor;
+/**
+ * Strip credentials from MCP specs before persisting:
+ *   - stdio: drop `env`; scrub secret-shaped `args` (`--token X`, `--api-key=X`)
+ *   - http/sse: drop `headers`; scrub `url` userinfo + secret query params
+ * Returns the cleaned (copied — caller's objects untouched) specs plus whether
+ * anything was removed. Note: a server that genuinely needs the stripped
+ * credential won't relaunch from the redacted spec — a domain that needs that
+ * must supply a custom EnvironmentProvider that re-injects from a handle.
+ */
+export declare function redactMcpSecrets(specs: McpServerSpec[]): {
+    specs: McpServerSpec[];
+    redacted: boolean;
+};
+//# sourceMappingURL=replay-types.d.ts.map

package/dist/learning/replay-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-types.d.ts","sourceRoot":"","sources":["../../src/learning/replay-types.ts"],"names":[],"mappings":"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"}

package/dist/learning/replay-types.js

@@ -0,0 +1,207 @@
+/**
+ * Replay environment reconstruction — Phase 1 of stateful live replay.
+ *
+ * `LiveReplay` re-runs a task to score a candidate playbook, but a faithful
+ * re-run needs the original *environment*, not just the task text. This
+ * module captures a compact, reconstructable descriptor of that environment
+ * at solve time (stored on `experience.metadata.replay`) and rebuilds it at
+ * replay time.
+ *
+ * Scope (Phase 1): environments that can be re-attached from a descriptor —
+ * per-task env-MCP servers and/or a working directory, optionally enriched
+ * by the caller with a stable `envHandle` + `verifierId`. Environments that
+ * can't be reconstructed (most ephemeral coding tasks) yield `null` from the
+ * provider, and the gating layer falls back to a cheaper judge rather than
+ * scoring an unfaithful rollout.
+ */
+/** Where the descriptor lives on an experience. */
+export const REPLAY_METADATA_KEY = 'replay';
+/** Registry mapping `verifierId` → concrete verifier (keeps the DB data-only). */
+export class ReplayVerifierRegistry {
+    map = new Map();
+    register(id, verifier) {
+        this.map.set(id, verifier);
+    }
+    get(id) {
+        return id ? this.map.get(id) : undefined;
+    }
+}
+/** Read + validate the descriptor off an experience, or null. */
+export function readReplayDescriptor(experience) {
+    const raw = experience.metadata?.[REPLAY_METADATA_KEY];
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const d = raw;
+    return d.v === 1 ? d : null;
+}
+/**
+ * Default provider: reconstructs from the persisted descriptor and resolves
+ * the verifier from a registry. Returns null unless `reconstructable`.
+ * Returns the (redacted) `mcpServers` as-is — sufficient for envs that need
+ * no credentials; cred-bearing envs need a custom provider.
+ */
+export class DefaultEnvironmentProvider {
+    verifiers;
+    constructor(verifiers) {
+        this.verifiers = verifiers;
+    }
+    isReplayable(experience) {
+        const d = readReplayDescriptor(experience);
+        return !!d && d.reconstructable;
+    }
+    async reconstruct(experience) {
+        const d = readReplayDescriptor(experience);
+        if (!d || !d.reconstructable)
+            return null;
+        return {
+            mcpServers: d.mcpServers,
+            cwd: d.cwd,
+            agentType: d.agentType,
+            verifier: this.verifiers?.get(d.verifierId),
+        };
+    }
+}
+/**
+ * Tries each provider in order; the first that reports `isReplayable`
+ * handles the experience. Lets Phase 1 (env-MCP) and Phase 2 (workspace
+ * snapshot) providers coexist — put the more specific (snapshot) first.
+ */
+export class CompositeEnvironmentProvider {
+    providers;
+    constructor(providers) {
+        this.providers = providers;
+    }
+    isReplayable(experience) {
+        return this.providers.some((p) => p.isReplayable(experience));
+    }
+    async reconstruct(experience) {
+        // Try each replayable provider in order; if one's reconstruct yields null
+        // (e.g. a snapshot that can't be materialized), fall through to the next
+        // rather than giving up — so a usable env-MCP fallback isn't masked.
+        for (const p of this.providers) {
+            if (!p.isReplayable(experience))
+                continue;
+            const env = await p.reconstruct(experience);
+            if (env)
+                return env;
+        }
+        return null;
+    }
+}
+/**
+ * Build a descriptor from the env used at solve time. `reconstructable`
+ * defaults to "an env-MCP was attached" — a conservative default that keeps
+ * ephemeral, env-less tasks (which we can't tell apart from stateful ones)
+ * out of faithful replay. A caller that knows better enriches via `hint`
+ * (e.g. a stable `envHandle`, a `verifierId`, or an explicit `reconstructable`).
+ */
+export function buildReplayDescriptor(env, hint) {
+    const redaction = env.mcpServers ? redactMcpSecrets(env.mcpServers) : undefined;
+    const hasEnvMcp = !!(redaction && redaction.specs.length > 0);
+    // A snapshot is usable for replay only with BOTH a ref and its repo.
+    const hasSnapshot = !!(hint?.snapshot?.ref && hint?.snapshot?.repo);
+    // Whitelist the hint's contribution to metadata fields (reconstructable,
+    // verifierId, envHandle, snapshot) — captured fields (mcpServers/
+    // secretsRedacted/cwd/agentType) are pinned so a hint can't desync the
+    // redaction flag from the actual mcpServers content.
+    return {
+        v: 1,
+        reconstructable: hint?.reconstructable ?? (hasEnvMcp || hasSnapshot),
+        agentType: env.agentType,
+        cwd: env.cwd,
+        mcpServers: redaction?.specs,
+        secretsRedacted: redaction?.redacted || undefined,
+        verifierId: hint?.verifierId,
+        envHandle: hint?.envHandle,
+        snapshot: hint?.snapshot,
+    };
+}
+/** Names of flags/keys whose values are treated as credentials. */
+const SECRET_KEY = /(token|secret|password|passwd|api[-_]?key|access[-_]?key|auth|credential|bearer)/i;
+/**
+ * Strip credentials from MCP specs before persisting:
+ *   - stdio: drop `env`; scrub secret-shaped `args` (`--token X`, `--api-key=X`)
+ *   - http/sse: drop `headers`; scrub `url` userinfo + secret query params
+ * Returns the cleaned (copied — caller's objects untouched) specs plus whether
+ * anything was removed. Note: a server that genuinely needs the stripped
+ * credential won't relaunch from the redacted spec — a domain that needs that
+ * must supply a custom EnvironmentProvider that re-injects from a handle.
+ */
+export function redactMcpSecrets(specs) {
+    let redacted = false;
+    const cleaned = specs.map((s) => {
+        const copy = { ...s };
+        if (copy.env !== undefined) {
+            delete copy.env;
+            redacted = true;
+        }
+        if (copy.headers !== undefined) {
+            delete copy.headers;
+            redacted = true;
+        }
+        if (Array.isArray(copy.args)) {
+            const r = scrubArgs(copy.args);
+            if (r.redacted) {
+                copy.args = r.args;
+                redacted = true;
+            }
+        }
+        if (typeof copy.url === 'string') {
+            const r = scrubUrl(copy.url);
+            if (r.redacted) {
+                copy.url = r.url;
+                redacted = true;
+            }
+        }
+        return copy;
+    });
+    return { specs: cleaned, redacted };
+}
+/** Replace values following a secret-shaped flag (and inline `--flag=value`). */
+function scrubArgs(args) {
+    let redacted = false;
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const inline = a.match(/^(-{1,2}[^=]*)=(.*)$/);
+        if (inline && SECRET_KEY.test(inline[1])) {
+            out.push(`${inline[1]}=***`);
+            redacted = true;
+            continue;
+        }
+        out.push(a);
+        if (/^-{1,2}/.test(a) &&
+            SECRET_KEY.test(a) &&
+            i + 1 < args.length &&
+            !args[i + 1].startsWith('-')) {
+            out.push('***');
+            i++;
+            redacted = true;
+        }
+    }
+    return { args: out, redacted };
+}
+/** Strip userinfo and secret-shaped query params from a URL. */
+function scrubUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { url, redacted: false };
+    }
+    let redacted = false;
+    if (parsed.username || parsed.password) {
+        parsed.username = '';
+        parsed.password = '';
+        redacted = true;
+    }
+    for (const key of [...parsed.searchParams.keys()]) {
+        if (SECRET_KEY.test(key)) {
+            parsed.searchParams.set(key, '***');
+            redacted = true;
+        }
+    }
+    return { url: parsed.toString(), redacted };
+}
+//# sourceMappingURL=replay-types.js.map

package/dist/learning/replay-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-types.js","sourceRoot":"","sources":["../../src/learning/replay-types.ts"],"names":[],"mappings":"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"}