cognitive-core 0.2.4 → 0.3.1

package/dist/learning/workspace-snapshot.js

@@ -0,0 +1,269 @@
+/**
+ * Workspace snapshotting — Phase 2 of stateful live replay (Regime B).
+ *
+ * Phase 1 reconstructs environments that regenerate from a handle (env-MCP).
+ * Many real coding tasks instead mutate an *ephemeral* working tree whose
+ * initial state is gone by the time we'd replay. This captures that initial
+ * state at task start and rematerializes it for a faithful rollout.
+ *
+ * The capture/materialize mechanism is abstracted behind
+ * {@link WorkspaceSnapshotStore} so the gating logic is testable with a fake
+ * and degrades gracefully (non-git dirs → no snapshot → fall back to the
+ * cheap judge). The git implementation snapshots the *full* working state
+ * (tracked + untracked, minus .gitignore) into the repo's object DB without
+ * touching HEAD or the user's index, anchored by a ref so it survives gc.
+ *
+ * DEFERRED — hermeticity (Phase 2.5, not yet implemented):
+ * This captures the *filesystem*, not the *network/external* boundary, so a
+ * rollout that reaches the network or mutates an external system is not
+ * fully hermetic. The field's standard mitigations (none of which replay
+ * true side effects — they contain or mock them) map onto seams ccore
+ * already has:
+ *   - Run replays in a sandbox with egress denied, turning "captured FS"
+ *     into "hermetic FS". `agent-workspace`'s `SandboxConfig` (allowed-domains
+ *     list) is the seam — materialize into a sandboxed workspace for gating.
+ *   - Record dependency interactions at solve time and replay them on
+ *     rollout (HTTP/LLM "cassettes", keyed by request / prompt hash); mock or
+ *     exclude genuinely irreproducible effects (email, payments, ...).
+ * Deferred deliberately: Phase 2 (FS snapshot) covers the common
+ * code-agent case, and non-hermetic tasks degrade safely to the cheaper
+ * judge today. Revisit when there's demand for gating network/stateful-
+ * backend tasks.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { VerificationRunner } from '../search/verification-runner.js';
+import { readReplayDescriptor, } from './replay-types.js';
+const exec = promisify(execFile);
+/**
+ * Git-backed snapshot store. Capture writes a tree of the full working state
+ * to the object DB (via a throwaway index, so HEAD/index are untouched),
+ * wraps it in a parent-less commit, and anchors it under `refs/cc-replay/*`.
+ * Materialize `git archive`s that ref into a fresh temp dir.
+ */
+/**
+ * Default denylist of credential-shaped paths excluded from every snapshot,
+ * on top of the repo's own git ignore rules. Prevents un-gitignored secrets
+ * (e.g. a stray `.env`) from being persisted into long-lived git objects.
+ */
+export const DEFAULT_SNAPSHOT_EXCLUDES = [
+    '.env',
+    '.env.*',
+    '*.pem',
+    '*.key',
+    '*.pfx',
+    '*.p12',
+    'id_rsa',
+    'id_dsa',
+    'id_ecdsa',
+    'id_ed25519',
+    '.npmrc',
+    '.netrc',
+    '.pypirc',
+    '*.credentials',
+    'credentials.json',
+    'secrets.*',
+    '*.secret',
+];
+export class GitWorkspaceSnapshotStore {
+    /** Repos captured into this session — lets GC visit repos whose backing
+     *  experiences have all been evicted (in-memory; relearned after restart). */
+    captured = new Set();
+    /** Git exclude pathspecs applied to every capture (denylist + caller adds). */
+    excludePathspecs;
+    constructor(options) {
+        const extra = options?.excludePathspecs ?? [];
+        const base = options?.replaceExcludes ? [] : [...DEFAULT_SNAPSHOT_EXCLUDES];
+        this.excludePathspecs = [...base, ...extra].map((p) => `:(exclude,glob)${p}`);
+    }
+    knownRepos() {
+        return [...this.captured];
+    }
+    async capture(dir) {
+        try {
+            await this.git(dir, ['rev-parse', '--is-inside-work-tree']);
+        }
+        catch {
+            return null; // not a git work tree
+        }
+        const idxDir = await mkdtemp(join(tmpdir(), 'cc-snap-idx-'));
+        const idxEnv = { GIT_INDEX_FILE: join(idxDir, 'index') };
+        try {
+            // Stage everything except the secret denylist into the throwaway index,
+            // then snapshot it as a tree → parent-less commit → anchor ref. NOTE:
+            // `git add -A` honors ALL active git excludes (repo .gitignore,
+            // .git/info/exclude, and the user's global core.excludesFile), so the
+            // snapshot can differ from the raw working tree by more than .gitignore.
+            await this.git(dir, ['add', '-A', '--', '.', ...this.excludePathspecs], idxEnv);
+            const tree = (await this.git(dir, ['write-tree'], idxEnv)).trim();
+            const commit = (await this.git(dir, ['commit-tree', tree, '-m', 'cc-replay snapshot'], {
+                GIT_AUTHOR_NAME: 'cc-replay',
+                GIT_AUTHOR_EMAIL: 'cc-replay@local',
+                GIT_COMMITTER_NAME: 'cc-replay',
+                GIT_COMMITTER_EMAIL: 'cc-replay@local',
+            })).trim();
+            await this.git(dir, ['update-ref', `refs/cc-replay/${commit}`, commit]);
+            this.captured.add(dir);
+            return { ref: commit, repo: dir };
+        }
+        catch {
+            return null;
+        }
+        finally {
+            await rm(idxDir, { recursive: true, force: true });
+        }
+    }
+    async listRefs(repo) {
+        let out;
+        try {
+            out = await this.git(repo, [
+                'for-each-ref',
+                '--format=%(objectname) %(committerdate:unix)',
+                'refs/cc-replay/',
+            ]);
+        }
+        catch {
+            return [];
+        }
+        const refs = [];
+        for (const line of out.split('\n')) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            const [sha, unix] = t.split(/\s+/);
+            refs.push({ ref: sha, committedAt: new Date(Number(unix) * 1000) });
+        }
+        return refs;
+    }
+    async prune(repo, opts) {
+        const { keepRefs, minAgeMs = 0, gc = false } = opts;
+        const now = Date.now();
+        let deleted = 0;
+        for (const { ref, committedAt } of await this.listRefs(repo)) {
+            if (keepRefs?.has(ref))
+                continue; // still referenced by a live experience
+            if (now - committedAt.getTime() < minAgeMs)
+                continue; // grace floor
+            try {
+                await this.git(repo, ['update-ref', '-d', `refs/cc-replay/${ref}`]);
+                deleted++;
+            }
+            catch {
+                // ref vanished concurrently — ignore
+            }
+        }
+        // Deleting refs only makes objects unreachable; reclaim them on request.
+        if (gc && deleted > 0) {
+            try {
+                await this.git(repo, ['gc', '--prune=now', '--quiet']);
+            }
+            catch {
+                // gc is best-effort
+            }
+        }
+        return deleted;
+    }
+    /**
+     * Materialize a snapshot into a fresh temp worktree via `git archive | tar`.
+     * Fidelity notes: symlinks and executable bits are preserved; empty
+     * directories are NOT (git doesn't track them), file mtimes reset to
+     * extraction time, and the result is a plain directory, not a git repo (a
+     * `verifyCommand` that runs `git ...` will fail). Cleans up on failure.
+     */
+    async materialize(snapshot) {
+        const dest = await mkdtemp(join(tmpdir(), 'cc-replay-ws-'));
+        const tarDir = await mkdtemp(join(tmpdir(), 'cc-replay-tar-'));
+        const tarPath = join(tarDir, 'snap.tar');
+        try {
+            await this.git(snapshot.repo, ['archive', '--format=tar', '-o', tarPath, snapshot.ref]);
+            await exec('tar', ['-xf', tarPath, '-C', dest]);
+        }
+        catch (e) {
+            // Don't leak the dest worktree if archive/extract fails.
+            await rm(dest, { recursive: true, force: true });
+            throw e;
+        }
+        finally {
+            await rm(tarDir, { recursive: true, force: true });
+        }
+        return {
+            path: dest,
+            dispose: async () => {
+                await rm(dest, { recursive: true, force: true });
+            },
+        };
+    }
+    async git(cwd, args, extraEnv) {
+        const { stdout } = await exec('git', ['-C', cwd, ...args], {
+            env: { ...process.env, ...extraEnv },
+            maxBuffer: 1 << 26,
+        });
+        return stdout;
+    }
+}
+export function createGitWorkspaceSnapshotStore() {
+    return new GitWorkspaceSnapshotStore();
+}
+/**
+ * EnvironmentProvider (Regime B): rematerializes a captured workspace
+ * snapshot into a fresh worktree and scores the replayed end-state with the
+ * descriptor's verification command, run in that worktree. The materialized
+ * copy is disposed after the rollout via `ReplayEnvironment.dispose`.
+ */
+export class WorkspaceSnapshotProvider {
+    store;
+    opts;
+    constructor(store, opts) {
+        this.store = store;
+        this.opts = opts;
+    }
+    isReplayable(experience) {
+        const snap = readReplayDescriptor(experience)?.snapshot;
+        return !!(snap?.ref && snap.repo); // both needed to materialize
+    }
+    async reconstruct(experience) {
+        const snap = readReplayDescriptor(experience)?.snapshot;
+        if (!snap?.ref || !snap.repo)
+            return null;
+        let materialized;
+        try {
+            materialized = await this.store.materialize({ ref: snap.ref, repo: snap.repo });
+        }
+        catch {
+            return null; // can't rebuild → caller falls back
+        }
+        const verifier = snap.verifyCommand
+            ? buildCommandVerifier(snap.verifyCommand, materialized.path, snap.successPattern, this.opts?.verifyTimeoutMs)
+            : undefined;
+        return {
+            cwd: materialized.path,
+            agentType: this.opts?.agentType,
+            verifier,
+            dispose: () => materialized.dispose(),
+        };
+    }
+}
+/**
+ * Build an OutcomeVerifier that runs `command` in `cwd` (via
+ * {@link VerificationRunner}) and maps pass/fail to acceptable. Used to score
+ * a replayed worktree by its build/tests rather than self-reported success.
+ */
+export function buildCommandVerifier(command, cwd, successPattern, timeoutMs) {
+    const runner = new VerificationRunner({ cwd, timeout: timeoutMs });
+    const fn = runner.createVerifier({
+        command,
+        cwd,
+        successPattern: successPattern ? new RegExp(successPattern) : undefined,
+        timeout: timeoutMs,
+    });
+    return {
+        verify: async (task, _agentResult, trajectory) => {
+            const result = await fn(trajectory, task);
+            return { acceptable: result.passed, reason: result.details };
+        },
+    };
+}
+//# sourceMappingURL=workspace-snapshot.js.map

package/dist/learning/workspace-snapshot.js.map

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

package/dist/mcp/playbook-server.d.ts

@@ -13,6 +13,30 @@
 import type { PlaybookLibrary } from '../memory/playbook.js';
 import type { SkillLibrary } from '../surfacing/skill-library.js';
 import type { MCPServerConfig } from '../types/config.js';
+import type { Trajectory } from '../types/trajectory.js';
+import type { ImmediateResult, UnifiedBatchResult } from '../learning/unified-pipeline.js';
+/**
+ * Minimal in-process learning surface (G7).
+ *
+ * The read-only tools only need a {@link PlaybookLibrary}. The
+ * ingest/extract/promote tools additionally need to drive the *same-process*
+ * learning loop. An {@link Atlas} instance satisfies this structurally, so the
+ * server stays decoupled from the full Atlas class while still being able to
+ * drive `processTrajectory` -> `runBatchLearning` -> `refreshTiers`.
+ *
+ * Because the server is long-running and holds one Atlas instance, the
+ * ingest tool populates the *in-memory batch accumulator* via same-process
+ * `processTrajectory` calls — sidestepping the fresh-process-empties-the-
+ * accumulator problem that a CLI-per-trajectory ingest hits.
+ */
+export interface LearningSurface {
+    /** Process one trajectory through the immediate loop + batch accumulator. */
+    processTrajectory(trajectory: Trajectory): Promise<ImmediateResult>;
+    /** Run batch learning over the accumulated trajectories (on-demand extract). */
+    runBatchLearning(): Promise<UnifiedBatchResult>;
+    /** Skill library for tier promotion / maintenance (G5 eval-gate). */
+    getSkillLibrary(): SkillLibrary | null;
+}
 /**
  * MCP Tool definition
  */
@@ -63,7 +87,13 @@ export interface PlaybookSearchResult {
 export declare class PlaybookMCPServer {
     private playbooks;
     private config;
-    constructor(playbooks: PlaybookLibrary, _skillLibrary?: SkillLibrary, config?: Partial<MCPServerConfig>);
+    private learning;
+    constructor(playbooks: PlaybookLibrary, _skillLibrary?: SkillLibrary, config?: Partial<MCPServerConfig>, learning?: LearningSurface);
+    /**
+     * Whether the write-side tools (ingest/extract/promote, G7) are available.
+     * They require an in-process {@link LearningSurface} (an Atlas instance).
+     */
+    hasLearningSurface(): boolean;
     /**
      * Get available MCP tools
      */
@@ -88,6 +118,35 @@ export declare class PlaybookMCPServer {
      * Handle get_playbooks_by_domain tool call
      */
     private handleGetPlaybooksByDomain;
+    /**
+     * Handle ingest_trajectory tool call (G7).
+     *
+     * Validates against the cross-language TrajectorySchema, then drives the
+     * in-process pipeline. Invalid payloads return a structured MCP error
+     * (isError) rather than throwing — the server survives.
+     */
+    private handleIngestTrajectory;
+    /**
+     * Handle extract_playbooks tool call (G7).
+     *
+     * Triggers batch learning over the accumulated trajectories — the
+     * on-demand extraction the CLI-per-trajectory path lacked.
+     */
+    private handleExtractPlaybooks;
+    /**
+     * Handle promote_skills tool call (G7).
+     *
+     * Runs the tier promotion / maintenance step (refreshTiers), which is
+     * gated by the eval-gate (G5). When an external harness has registered a
+     * held-out PromotionJudge via skillLibrary.setPromotionJudge(...), that
+     * judge gates promotion here.
+     */
+    private handlePromoteSkills;
+    /**
+     * Structured error returned when a write-side tool is called without a
+     * learning surface (read-only deployment).
+     */
+    private noLearningSurfaceError;
     /**
      * Format playbook match for search results
      */
@@ -116,5 +175,5 @@ export declare class PlaybookMCPServer {
 /**
  * Create an MCP playbook server
  */
-export declare function createPlaybookMCPServer(playbooks: PlaybookLibrary, skillLibrary?: SkillLibrary, config?: Partial<MCPServerConfig>): PlaybookMCPServer;
+export declare function createPlaybookMCPServer(playbooks: PlaybookLibrary, skillLibrary?: SkillLibrary, config?: Partial<MCPServerConfig>, learning?: LearningSurface): PlaybookMCPServer;
 //# sourceMappingURL=playbook-server.d.ts.map

package/dist/mcp/playbook-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playbook-server.d.ts","sourceRoot":"","sources":["../../src/mcp/playbook-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,uBAAuB,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAQ1D;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAeD;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,MAAM,CAAkB;gBAG9B,SAAS,EAAE,eAAe,EAC1B,aAAa,CAAC,EAAE,YAAY,EAC5B,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC;IAMnC;;OAEG;IACH,QAAQ,IAAI,OAAO,EAAE;IAuErB;;OAEG;IACG,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IA8B/D;;OAEG;YACW,qBAAqB;IA2CnC;;OAEG;YACW,wBAAwB;IA6BtC;;OAEG;YACW,iBAAiB;IA6B/B;;OAEG;YACW,0BAA0B;IAsCxC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAkB/B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA6BhC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAgB7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAwG7B;;OAEG;IACH,aAAa,IAAI;QACf,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;KACrB;CAQF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,eAAe,EAC1B,YAAY,CAAC,EAAE,YAAY,EAC3B,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAChC,iBAAiB,CAEnB"}
+{"version":3,"file":"playbook-server.d.ts","sourceRoot":"","sources":["../../src/mcp/playbook-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,uBAAuB,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,+BAA+B,CAAC;AACrF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAQ3F;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACpE,gFAAgF;IAChF,gBAAgB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAChD,qEAAqE;IACrE,eAAe,IAAI,YAAY,GAAG,IAAI,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAeD;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,QAAQ,CAAyB;gBAGvC,SAAS,EAAE,eAAe,EAC1B,aAAa,CAAC,EAAE,YAAY,EAC5B,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,EACjC,QAAQ,CAAC,EAAE,eAAe;IAO5B;;;OAGG;IACH,kBAAkB,IAAI,OAAO;IAI7B;;OAEG;IACH,QAAQ,IAAI,OAAO,EAAE;IA6HrB;;OAEG;IACG,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAoC/D;;OAEG;YACW,qBAAqB;IAmCnC;;OAEG;YACW,wBAAwB;IAuBtC;;OAEG;YACW,iBAAiB;IA6B/B;;OAEG;YACW,0BAA0B;IAkCxC;;;;;;OAMG;YACW,sBAAsB;IAuCpC;;;;;OAKG;YACW,sBAAsB;IAmBpC;;;;;;;OAOG;YACW,mBAAmB;IAuCjC;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAY9B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAkB/B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA6BhC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAgB7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAqG7B;;OAEG;IACH,aAAa,IAAI;QACf,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;KACrB;CAQF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,eAAe,EAC1B,YAAY,CAAC,EAAE,YAAY,EAC3B,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,EACjC,QAAQ,CAAC,EAAE,eAAe,GACzB,iBAAiB,CAEnB"}

package/dist/mcp/playbook-server.js

@@ -10,6 +10,7 @@
  * allowing agents to search for specific guidance beyond what's in their
  * system prompt.
  */
+import { TrajectorySchema } from '../types/trajectory.js';
 import { validateMCPArgs, MCPSearchPlaybooksSchema, MCPGetPlaybookDetailsSchema, MCPGetPlaybooksByDomainSchema, } from '../utils/validation.js';
 /**
  * Default configuration
@@ -30,15 +31,24 @@ const DEFAULT_CONFIG = {
 export class PlaybookMCPServer {
     playbooks;
     config;
-    constructor(playbooks, _skillLibrary, config) {
+    learning;
+    constructor(playbooks, _skillLibrary, config, learning) {
         this.playbooks = playbooks;
         this.config = { ...DEFAULT_CONFIG, ...config };
+        this.learning = learning ?? null;
+    }
+    /**
+     * Whether the write-side tools (ingest/extract/promote, G7) are available.
+     * They require an in-process {@link LearningSurface} (an Atlas instance).
+     */
+    hasLearningSurface() {
+        return this.learning !== null;
     }
     /**
      * Get available MCP tools
      */
     getTools() {
-        return [
+        const tools = [
             {
                 name: 'search_playbooks',
                 description: 'Search for playbooks that provide guidance for solving a problem. ' +
@@ -104,6 +114,49 @@ export class PlaybookMCPServer {
                 },
             },
         ];
+        // G7: write-side tools. Only registered when an in-process learning
+        // surface (Atlas instance) is wired, so the read-only deployment stays
+        // read-only. An external/cross-language harness drives the full
+        // ingest -> extract -> promote loop over MCP against the long-running
+        // server's single Atlas instance (which keeps the batch accumulator warm).
+        if (this.learning) {
+            tools.push({
+                name: 'ingest_trajectory',
+                description: 'Ingest one agent trajectory into the in-process learning loop. ' +
+                    'The trajectory is validated against the cross-language TrajectorySchema, ' +
+                    'then fed to the same-process pipeline (populating the batch accumulator). ' +
+                    'Returns the trajectory id and current accumulator status.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        trajectory: {
+                            type: 'object',
+                            description: 'A trajectory object matching TrajectorySchema (id, task, steps, outcome, agentId, ...).',
+                        },
+                    },
+                    required: ['trajectory'],
+                },
+            }, {
+                name: 'extract_playbooks',
+                description: 'Trigger batch learning over the accumulated trajectories on-demand. ' +
+                    'This is the explicit extraction trigger the CLI-per-trajectory path lacked. ' +
+                    'Returns the number of playbooks extracted/updated plus batch summary.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            }, {
+                name: 'promote_skills',
+                description: 'Run the tier promotion / maintenance step (refreshTiers), gated by the ' +
+                    'eval-gate (G5). An external held-out judge registered on the skill library ' +
+                    'acts as the PromotionJudge. Returns promoted/demoted playbook ids.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            });
+        }
+        return tools;
     }
     /**
      * Handle an MCP tool call
@@ -119,6 +172,12 @@ export class PlaybookMCPServer {
                     return await this.handleListDomains();
                 case 'get_playbooks_by_domain':
                     return await this.handleGetPlaybooksByDomain(call.arguments);
+                case 'ingest_trajectory':
+                    return await this.handleIngestTrajectory(call.arguments);
+                case 'extract_playbooks':
+                    return await this.handleExtractPlaybooks();
+                case 'promote_skills':
+                    return await this.handlePromoteSkills();
                 default:
                     return {
                         content: [{ type: 'text', text: `Unknown tool: ${call.name}` }],
@@ -243,13 +302,125 @@ export class PlaybookMCPServer {
                 ],
             };
         }
-        const formatted = domainPlaybooks
-            .map((p) => this.formatPlaybookSummary(p))
-            .join('\n\n');
+        const formatted = domainPlaybooks.map((p) => this.formatPlaybookSummary(p)).join('\n\n');
         return {
             content: [{ type: 'text', text: formatted }],
         };
     }
+    /**
+     * Handle ingest_trajectory tool call (G7).
+     *
+     * Validates against the cross-language TrajectorySchema, then drives the
+     * in-process pipeline. Invalid payloads return a structured MCP error
+     * (isError) rather than throwing — the server survives.
+     */
+    async handleIngestTrajectory(args) {
+        if (!this.learning) {
+            return this.noLearningSurfaceError('ingest_trajectory');
+        }
+        // Validate against the zod TrajectorySchema (the cross-language contract).
+        const parsed = TrajectorySchema.safeParse(args.trajectory);
+        if (!parsed.success) {
+            const firstError = parsed.error.errors[0];
+            const where = firstError?.path.join('.') || 'trajectory';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Invalid trajectory: ${where}: ${firstError?.message ?? 'does not match TrajectorySchema'}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const trajectory = parsed.data;
+        const result = await this.learning.processTrajectory(trajectory);
+        const lines = [];
+        lines.push(`Ingested trajectory: ${trajectory.id}`);
+        lines.push(`Batch triggered: ${result.batchTriggered}`);
+        if (result.batchTriggered && result.batchResult) {
+            lines.push(`Playbooks extracted (auto-batch): ${result.batchResult.playbooksExtracted}`);
+            lines.push('Accumulator: flushed by auto-batch');
+        }
+        else {
+            lines.push('Accumulator: trajectory added (pending extract_playbooks)');
+        }
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+        };
+    }
+    /**
+     * Handle extract_playbooks tool call (G7).
+     *
+     * Triggers batch learning over the accumulated trajectories — the
+     * on-demand extraction the CLI-per-trajectory path lacked.
+     */
+    async handleExtractPlaybooks() {
+        if (!this.learning) {
+            return this.noLearningSurfaceError('extract_playbooks');
+        }
+        const batch = await this.learning.runBatchLearning();
+        const lines = [];
+        lines.push(`Batch learning complete.`);
+        lines.push(`Trajectories processed: ${batch.trajectoriesProcessed}`);
+        lines.push(`Playbooks extracted/updated: ${batch.playbooksExtracted}`);
+        lines.push(`Knowledge notes extracted: ${batch.knowledgeExtracted}`);
+        lines.push(`Batch success rate: ${Math.round(batch.successRate * 100)}%`);
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+        };
+    }
+    /**
+     * Handle promote_skills tool call (G7).
+     *
+     * Runs the tier promotion / maintenance step (refreshTiers), which is
+     * gated by the eval-gate (G5). When an external harness has registered a
+     * held-out PromotionJudge via skillLibrary.setPromotionJudge(...), that
+     * judge gates promotion here.
+     */
+    async handlePromoteSkills() {
+        if (!this.learning) {
+            return this.noLearningSurfaceError('promote_skills');
+        }
+        const skillLibrary = this.learning.getSkillLibrary();
+        if (!skillLibrary) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Promotion unavailable: skill library is not initialized (playbooks not enabled).',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const refresh = await skillLibrary.refreshTiers();
+        const judgeWired = skillLibrary.getPromotionJudge() !== null;
+        const lines = [];
+        lines.push('Tier refresh complete (eval-gated, G5).');
+        lines.push(`External promotion judge: ${judgeWired ? 'registered' : 'none (default frontier-dominance gate)'}`);
+        lines.push(`Promoted: ${refresh.promoted.length}${refresh.promoted.length > 0 ? ` (${refresh.promoted.join(', ')})` : ''}`);
+        lines.push(`Demoted: ${refresh.demoted.length}${refresh.demoted.length > 0 ? ` (${refresh.demoted.join(', ')})` : ''}`);
+        lines.push(`Core skill count: ${refresh.coreCount}`);
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+        };
+    }
+    /**
+     * Structured error returned when a write-side tool is called without a
+     * learning surface (read-only deployment).
+     */
+    noLearningSurfaceError(toolName) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Tool "${toolName}" requires an in-process learning surface (Atlas instance). This server is read-only.`,
+                },
+            ],
+            isError: true,
+        };
+    }
     /**
      * Format playbook match for search results
      */
@@ -389,8 +560,7 @@ export class PlaybookMCPServer {
         lines.push(`- Failures: ${failureCount}`);
         lines.push('');
         // Refinements (if enabled)
-        if (this.config.includeRefinements &&
-            playbook.evolution.refinements.length > 0) {
+        if (this.config.includeRefinements && playbook.evolution.refinements.length > 0) {
             lines.push('## Context-Specific Refinements');
             for (const ref of playbook.evolution.refinements) {
                 lines.push(`- **${ref.context}**: ${ref.addition}`);
@@ -421,7 +591,7 @@ export class PlaybookMCPServer {
 /**
  * Create an MCP playbook server
  */
-export function createPlaybookMCPServer(playbooks, skillLibrary, config) {
-    return new PlaybookMCPServer(playbooks, skillLibrary, config);
+export function createPlaybookMCPServer(playbooks, skillLibrary, config, learning) {
+    return new PlaybookMCPServer(playbooks, skillLibrary, config, learning);
 }
 //# sourceMappingURL=playbook-server.js.map