@tea-agent/loop-agent 0.13.0-alpha.0 → 0.13.0

package/dist/commands/eval.js

@@ -0,0 +1,235 @@
+import path from "node:path";
+import { writeTextAtomic } from "../infrastructure/harness/atomic-write.js";
+import { readReplayScorecard } from "../infrastructure/evaluation/store.js";
+import { formatReplayMarkdown, replayEvaluation, } from "../application/evaluation/replay.js";
+import { formatCandidateMarkdown, listCandidates, registerCandidate, showCandidate, transitionCandidate, } from "../application/evaluation/candidate.js";
+import { lifecycleStateSchema, } from "../application/evaluation/types.js";
+const USAGE = "usage: eval <replay|report|candidate> ...; candidate <register|show|list|transition> [--json|--markdown]";
+function parseFormatFlags(args) {
+    const json = args.includes("--json");
+    const markdown = args.includes("--markdown");
+    if (json && markdown) {
+        throw new Error("eval accepts only one of --json or --markdown");
+    }
+    return { json: json || !markdown, markdown };
+}
+function flagValue(args, flag) {
+    const index = args.indexOf(flag);
+    if (index >= 0) {
+        const value = args[index + 1];
+        if (!value || value.startsWith("-")) {
+            throw new Error(`${flag} requires a value`);
+        }
+        return value;
+    }
+    const prefix = `${flag}=`;
+    return args.find((arg) => arg.startsWith(prefix))?.slice(prefix.length);
+}
+function assertKnownFlags(args, allowed) {
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (!arg.startsWith("-"))
+            continue;
+        const key = arg.split("=", 1)[0];
+        if (!allowed.includes(key)) {
+            throw new Error(`unknown eval argument: ${arg}`);
+        }
+        if ([
+            "--spec",
+            "--output",
+            "--replay-id",
+            "--manifest",
+            "--candidate-id",
+            "--to",
+            "--reason",
+        ].includes(key) &&
+            !arg.includes("=")) {
+            i += 1;
+        }
+    }
+}
+function parseCandidateArgs(rest) {
+    const [action, ...tail] = rest;
+    if (action === "register") {
+        assertKnownFlags(tail, ["--manifest", "--json", "--markdown"]);
+        const manifestPath = flagValue(tail, "--manifest");
+        if (!manifestPath) {
+            throw new Error("eval candidate register requires --manifest <path>");
+        }
+        return {
+            command: "candidate",
+            action: "register",
+            manifestPath,
+            ...parseFormatFlags(tail),
+        };
+    }
+    if (action === "show") {
+        assertKnownFlags(tail, ["--candidate-id", "--json", "--markdown"]);
+        const candidateId = flagValue(tail, "--candidate-id");
+        if (!candidateId) {
+            throw new Error("eval candidate show requires --candidate-id <id>");
+        }
+        return {
+            command: "candidate",
+            action: "show",
+            candidateId,
+            ...parseFormatFlags(tail),
+        };
+    }
+    if (action === "list") {
+        assertKnownFlags(tail, ["--json", "--markdown"]);
+        return {
+            command: "candidate",
+            action: "list",
+            ...parseFormatFlags(tail),
+        };
+    }
+    if (action === "transition") {
+        assertKnownFlags(tail, [
+            "--candidate-id",
+            "--to",
+            "--reason",
+            "--json",
+            "--markdown",
+        ]);
+        const candidateId = flagValue(tail, "--candidate-id");
+        const toRaw = flagValue(tail, "--to");
+        const reason = flagValue(tail, "--reason");
+        if (!candidateId) {
+            throw new Error("eval candidate transition requires --candidate-id <id>");
+        }
+        if (!toRaw) {
+            throw new Error("eval candidate transition requires --to <state>");
+        }
+        if (!reason) {
+            throw new Error("eval candidate transition requires --reason <text>");
+        }
+        const to = lifecycleStateSchema.parse(toRaw);
+        return {
+            command: "candidate",
+            action: "transition",
+            candidateId,
+            to,
+            reason,
+            ...parseFormatFlags(tail),
+        };
+    }
+    throw new Error("usage: eval candidate <register|show|list|transition> ...");
+}
+export function parseEvalArgs(args) {
+    const [command, ...rest] = args;
+    if (command === "replay") {
+        assertKnownFlags(rest, ["--spec", "--output", "--json", "--markdown"]);
+        const specPath = flagValue(rest, "--spec");
+        if (!specPath)
+            throw new Error("eval replay requires --spec <path>");
+        return {
+            command,
+            specPath,
+            outputPath: flagValue(rest, "--output"),
+            ...parseFormatFlags(rest),
+        };
+    }
+    if (command === "report") {
+        assertKnownFlags(rest, ["--replay-id", "--json", "--markdown"]);
+        const replayId = flagValue(rest, "--replay-id");
+        if (!replayId)
+            throw new Error("eval report requires --replay-id <id>");
+        return { command, replayId, ...parseFormatFlags(rest) };
+    }
+    if (command === "candidate") {
+        return parseCandidateArgs(rest);
+    }
+    throw new Error(USAGE);
+}
+function printScorecard(input) {
+    if (input.json) {
+        console.log(JSON.stringify(input.scorecard, null, 2));
+        return;
+    }
+    process.stdout.write(input.markdown);
+}
+function printCandidate(input) {
+    if (input.json) {
+        console.log(JSON.stringify(input.record, null, 2));
+        return;
+    }
+    process.stdout.write(formatCandidateMarkdown(input.record));
+}
+export async function runEval(repoRoot, args) {
+    const parsed = parseEvalArgs(args);
+    if (parsed.command === "replay") {
+        const result = await replayEvaluation({
+            repoRoot,
+            specPath: parsed.specPath,
+        });
+        if (parsed.outputPath) {
+            const outputPath = path.resolve(repoRoot, parsed.outputPath);
+            await writeTextAtomic(outputPath, parsed.markdown
+                ? result.markdown
+                : `${JSON.stringify(result.scorecard, null, 2)}\n`, { repoRoot });
+        }
+        printScorecard({
+            scorecard: result.scorecard,
+            markdown: result.markdown,
+            json: parsed.json,
+        });
+        return;
+    }
+    if (parsed.command === "report") {
+        const scorecard = (await readReplayScorecard(repoRoot, parsed.replayId));
+        const markdown = formatReplayMarkdown(scorecard);
+        printScorecard({ scorecard, markdown, json: parsed.json });
+        return;
+    }
+    // candidate subcommands
+    if (parsed.action === "register") {
+        const result = await registerCandidate({
+            repoRoot,
+            manifestPath: parsed.manifestPath,
+        });
+        if (parsed.json) {
+            console.log(JSON.stringify({
+                idempotent: result.idempotent,
+                manifestPath: result.manifestPath,
+                lifecyclePath: result.lifecyclePath,
+                record: result.record,
+            }, null, 2));
+            return;
+        }
+        process.stdout.write(`${result.idempotent ? "idempotent " : ""}registered ${result.record.manifest.candidateId}\n${formatCandidateMarkdown(result.record)}`);
+        return;
+    }
+    if (parsed.action === "show") {
+        const record = await showCandidate({
+            repoRoot,
+            candidateId: parsed.candidateId,
+        });
+        printCandidate({ record, json: parsed.json });
+        return;
+    }
+    if (parsed.action === "list") {
+        const rows = await listCandidates({ repoRoot });
+        if (parsed.json) {
+            console.log(JSON.stringify(rows, null, 2));
+            return;
+        }
+        const lines = [
+            "# Candidates",
+            "",
+            ...rows.map((row) => `- \`${row.candidateId}\` status=\`${row.status}\` hash=\`${row.bundleHash}\` promotionApplied=false`),
+            "",
+        ];
+        process.stdout.write(`${lines.join("\n")}\n`);
+        return;
+    }
+    if (parsed.action === "transition") {
+        const record = await transitionCandidate({
+            repoRoot,
+            candidateId: parsed.candidateId,
+            to: parsed.to,
+            reason: parsed.reason,
+        });
+        printCandidate({ record, json: parsed.json });
+    }
+}

package/dist/commands/init.js

@@ -679,9 +679,34 @@ function buildManagedAgentsBlock(input) {
         "- 保留无关的用户改动，不要回退自己没有做的修改。",
         "- 委托模型写入前，必须把写入边界写成结构化 `task.json.allowedPaths` / `task.json.forbiddenPaths`，再审查生成 DAG 的 writer `writeSet`；不要只依赖 `source/执行约束.md` 的自然语言约束。",
         "",
+        "### 自然语言入口路由",
+        "",
+        "用户用中文表达意图时，按以下三类入口路由；只读与写入必须严格区分。",
+        "",
+        "| 用户表达 | 入口 | 执行动作 |",
+        "|---|---|---|",
+        "| loop-agent 初始化 / loop agent 初始化 / loop agent初始化 / 初始化 loop-agent | 初始化 | 完成确定性初始化闭环 |",
+        "| 初始化更新校验 / 检查初始化更新 / loop-agent 初始化更新校验 / loop agent初始化更新校验 | 更新校验 | 只读报告，不写入 |",
+        "| 初始化安全更新 / 应用初始化更新 / loop-agent 初始化安全更新 / loop agent初始化安全更新 | 安全更新 | check-update 后只执行确定性安全动作 |",
+        "",
+        "**更新校验（只读）**：用户说“初始化更新校验”“检查初始化更新”时，只读执行下面命令，汇报 deterministic actions、model merge、human decisions 和 next steps。**这一步不得自动执行 `apply-safe` 或模型合并。**",
+        "",
+        "```bash",
+        "loop-agent init check-update --repo-root . --markdown",
+        "```",
+        "",
+        "**安全更新（写入型）**：用户明确说“初始化安全更新”“应用初始化更新”时，先 check-update，再执行确定性安全动作；surface 缺失时先 bootstrap，存在 human decisions 时停下等用户决策。model merge 任务必须带 allowed/forbidden paths，且不得自动决策。安全更新完成后必须复查 `loop-agent init doctor --repo-root .`、`loop-agent inspect --repo-root .`、`loop-agent docs audit --repo-root .` 与目标项目治理检查（如 `bash scripts/check-repo.sh`）。",
+        "",
+        "```bash",
+        "loop-agent init check-update --repo-root . --markdown",
+        "loop-agent init update --repo-root . --apply-safe",
+        "```",
+        "",
+        "仅当 check-update 报告 surface 缺失时才执行 `loop-agent init update --repo-root . --bootstrap-surface`。",
+        "",
         "### 初始化闭环",
         "",
-        `当用户要求在本仓库初始化 loop-agent，或发现 \`README.md\` / \`${input.governanceRoot}/verification-matrix.md\` 仍停留在通用初始化状态时，模型应在同一轮工作中完成初始化闭环，不要把补全文档和验证矩阵留给用户交互。`,
+        `当用户要求初始化 loop-agent（“初始化 loop-agent”“loop agent 初始化”“loop agent初始化”“loop-agent 初始化”），或发现 \`README.md\` / \`${input.governanceRoot}/verification-matrix.md\` 仍停留在通用初始化状态时，模型应在同一轮工作中完成初始化闭环，不要把补全文档和验证矩阵留给用户交互。`,
         "",
         "标准流程：",
         "",
@@ -731,6 +756,22 @@ function buildManagedAgentsBlock(input) {
         "",
         "执行 DAG 前必须审查 profile routing、governance profile、writer 的 `writeSet`、`allowedPaths`、`forbiddenPaths`、shell verification 和 decision gate mode。不要执行占位或过宽的写入范围。",
         "",
+        "### 任务类型路由（taskKind）",
+        "",
+        "- 用户明确提出后端测试、接口/API 测试、pytest，或语境明确为后端的自动化测试时，必须把 `.harness/tasks/<task-id>/task.json` 的 `taskKind` 设置为 `\"backend-test\"`，不得保留默认 `standard`。",
+        "- `backend-test` 是 `taskKind`，不是 `--profile` 的可选值；运行 `dag run-task` 时继续使用 `--profile auto`，也可按需显式选择 `minimal` / `standard` / `reviewed` / `supervised`，不要把业务模板名当作 profile。",
+        "- 仅出现“自动化测试”且无法判断前后端时，先阅读任务源与目标项目技术栈再决定，禁止无条件路由到 `backend-test`。",
+        "",
+        "### 运行看板（只读）",
+        "",
+        "启动本地只读运行看板：",
+        "",
+        "```bash",
+        "agent-worker observe serve --repo . --port 8787",
+        "```",
+        "",
+        "浏览器打开 `http://127.0.0.1:8787/`。看板只读，默认只绑定本机 `127.0.0.1`；不要直接暴露到公开网络。",
+        "",
         "### DAG 诊断与收口",
         "",
         "执行后优先使用 `loop-agent dag report --run-id <run-id> --markdown` 读取 run facts；失败或 paused run 使用 `loop-agent dag doctor --run-id <run-id> --markdown` 诊断。失败 DAG run 不应写成成功 closeout，应使用 `loop-agent dag closeout-draft --run-id <run-id>` 生成 failure handoff，保留 what failed、evidence、classification、recommended follow-up、safe retry conditions 和 human decision needed。",
@@ -805,6 +846,12 @@ export function buildManagedGitignoreBlock() {
         "# one-shot executor runs",
         ".harness/runs/*",
         "!.harness/runs/.gitkeep",
+        "!.harness/runs/active/",
+        "!.harness/runs/active/.gitkeep",
+        "!.harness/runs/completed/",
+        "!.harness/runs/completed/.gitkeep",
+        "!.harness/runs/failed/",
+        "!.harness/runs/failed/.gitkeep",
         "",
         "# session / cache / logs / recomputable surface state",
         ".harness/live/",
@@ -816,6 +863,9 @@ export function buildManagedGitignoreBlock() {
         ".harness/task-pool/*",
         ".task-pool/",
         "",
+        "# repo-local skill dependencies installed inside projected skills",
+        ".agents/skills/*/node_modules/",
+        "",
         "# multi-worktree parallel mode",
         ".worktrees/",
         GITIGNORE_BLOCK_END,
@@ -980,6 +1030,26 @@ async function ensureHarnessDirs(repoRoot, written) {
         await mkdir(path.join(repoRoot, dir), { recursive: true });
         written.push(dir);
     }
+    const placeholders = [
+        ".harness/tasks/.gitkeep",
+        ".harness/dag-runs/active/.gitkeep",
+        ".harness/dag-runs/completed/.gitkeep",
+        ".harness/dag-runs/paused/.gitkeep",
+        ".harness/runs/.gitkeep",
+        ".harness/runs/active/.gitkeep",
+        ".harness/runs/completed/.gitkeep",
+        ".harness/runs/failed/.gitkeep",
+    ];
+    for (const relativePath of placeholders) {
+        const target = path.join(repoRoot, relativePath);
+        try {
+            await access(target);
+        }
+        catch {
+            await writeFile(target, "", "utf8");
+            written.push(relativePath);
+        }
+    }
 }
 async function writeCompatPrompts(input) {
     for (const [name, content] of Object.entries(COMPAT_PROMPTS)) {
@@ -1216,7 +1286,7 @@ async function buildCurrentSurfaceState(input) {
             repoRoot: input.repoRoot,
             projectName: input.projectName,
             governanceRoot: input.governanceRoot,
-            entry,
+            entry: manifestEntry,
         });
         const sourceSha256 = desired.content === undefined ? undefined : sha256Text(desired.content);
         const base = {
@@ -1292,6 +1362,19 @@ async function buildCurrentSurfaceState(input) {
 }
 async function writeInitSurfaceState(input) {
     const state = await buildCurrentSurfaceState(input);
+    if (input.stateKind === "recorded" && input.preserveOwnershipFrom) {
+        for (const [pathName, file] of Object.entries(state.files)) {
+            if (file.relationship !== "local-existing-unknown")
+                continue;
+            const priorHash = input.preserveOwnershipFrom.files[pathName]?.currentSha256;
+            if (priorHash !== undefined) {
+                file.currentSha256 = priorHash;
+            }
+            else {
+                delete file.currentSha256;
+            }
+        }
+    }
     const target = path.join(input.repoRoot, INIT_SURFACE_STATE_PATH);
     await mkdir(path.dirname(target), { recursive: true });
     await writeFile(target, `${JSON.stringify(state, null, 2)}\n`, "utf-8");
@@ -1824,14 +1907,45 @@ function buildTargetFeatureWorkflow(input) {
         DAG_HARD_GATE_TRIGGER,
         "",
         "Before executing a DAG, review profile routing, governance profile, writer writeSet, allowed paths, forbidden paths, shell verification, and decision gate mode.",
+        "Generated DAGs bind authoritative task-source paths, SHA-256 hashes, and explicit REQ/BR/AC identifiers. Frontend plans with explicit identifiers pass a deterministic coverage gate before final design review and implementation.",
+        "After an interrupted run, repair the task source and regenerate the complete DAG. Do not construct an impl-only recovery DAG from an upstream summary; strict governance rejects a v3 orphan writer without sourceBinding or a read-only planner ancestor.",
         "",
         "## Specialized Task Kinds",
         "",
-        "Set `taskKind` in `.harness/tasks/<task-id>/task.json` to route a task to a dedicated DAG profile instead of the default auto profile:",
+        "- standard tasks are classified conservatively from the task title, `source/需求.md`, and structured `allowedPaths`.",
+        "- Only high-confidence frontend implementation demands select the frontend DAG automatically; backend, mixed, negated, and unknown demands keep the template selected by the normal governance profile.",
+        "- `frontend-mock-assess-pi` reads Mock/API/schema evidence and selects `native|browser-intercept|request-adapter|not-needed|blocked` before frontend planning; its deterministic gate rejects blocked or malformed output, while the existing frontend implementer remains the only writer.",
+        "- Mock-backed verification never proves real API integration. When the backend was not exercised, closeout must retain the gap and name `<task-id>-real-api-integration-verify`; that follow-up is explicitly created/run after backend readiness, never automatic.",
+        "- Automatic frontend classification never replaces a supervised template selected by an explicit profile, workflowPolicy, or the supervised quality gate.",
+        "- A backend implementation does not select the backend test DAG. `backend-test` remains an explicit test-engineering workflow.",
+        "- Explicit specialized `taskKind` values remain compatible and take precedence over task-source classification.",
         "",
+        "Set an explicit specialized `taskKind` in `.harness/tasks/<task-id>/task.json` only when the dedicated workflow itself is part of the task contract:",
+        "",
+        "- `taskKind: \"frontend-implementation\"` explicitly selects the frontend DAG for compatibility or intentional override. Optional `frontendMock` config sets `policy: auto|required|disabled`, an existing `serviceRoot`, and generation-time-frozen `verifyCommands`; an unsafe or incomplete explicit required contract produces an assessment-only DAG with no writer, while a complete required contract adds Mock-specific verification only when trusted commands exist. Auto API tasks without a native service may use an existing browser interception harness or reversible request adapter, then continue through static and behavior verification.",
         "- `taskKind: \"backend-test\"` selects the dedicated backend test DAG. Its Pi nodes analyze requirements, generate and review backend cases, generate pytest, and retrospect on results; shell gate/execution nodes enforce the review verdict and run the target project's pytest. The backend test templates (`backend-test-dag.json` and the `backend-test-dag.*.prompt.md` files) ship inside the loop-agent package as static references and are projected to target projects under the governance `templates/` directory.",
+        "- `taskKind: \"knowledge-sync\"` selects the Feature-scoped test-knowledge write-back DAG (collect → draft → validate → apply → pointer). Bind `featureId` in `task.json` (or hardConstraints / requirement text). It writes only under `features/<featureId>/…` after final verification evidence exists.",
+        "- `taskKind: \"knowledge-graph-bootstrap\"` selects the business knowledge-graph bootstrap DAG (preflight → inventory → propose → validate → review → gate → promote → materialize). AI writes only `knowledge/bootstrap/staging/**`; promote is merge-new-only.",
+        "- `taskKind: \"frontend-test\"` selects the FE-test RAG DAG. It writes a traceable frontend RAG package and Markdown case manifest, then executes manifest cases serially with `playwright-cli` in isolated test environments and retains per-case evidence. It never generates pytest or Playwright source code. `frontendTest.maxCasesPerBatch` defaults to 20 (maximum 50); optional `maxTokensPerCase` and `maxTotalTokens` stop only later cases after a completed case's token usage is recorded, marking them `blocked: token-budget-exhausted`. Generated browser startup uses `playwright-cli open --browser=chrome --headed <base-url>`; the generic playwright-cli skill is unchanged.",
         "- Only eligible read-only Pi nodes (planner, scout, reviewer, verifier, closeout with no write-capable tool profile) receive the conservative automatic retry policy. Supervisor, implementer, writer, docs-only, dynamic, shell, static, and decision-gate nodes are not retried automatically. Eligible nodes cannot write repository files; the controller only records immutable attempt evidence under `.harness/dag-runs/<state>/<run-id>/<node-id>/attempt-<n>.json`.",
         "",
+        "Use the package-backed public knowledge CLI for graph operations. Do not require target projects to run package-only kb runtime scripts:",
+        "",
+        "```bash",
+        "loop-agent knowledge graph-init --product-name <name>",
+        "# edit knowledge/bootstrap/scope.yaml, then:",
+        "loop-agent dag run-task <task-id>   # taskKind: knowledge-graph-bootstrap",
+        "loop-agent knowledge query --mode by_feature --feature F-2026-004 --json",
+        "loop-agent knowledge query --mode by_id --id SVC-order --json",
+        "loop-agent knowledge query --mode search --text \"keyword\" --json",
+        "loop-agent knowledge graph-incremental-prepare --feature F-2026-004 --service <service>",
+        "# review the prepared scope/staging; for a manual reviewed promotion:",
+        "loop-agent knowledge graph-promote",
+        "loop-agent knowledge graph-materialize",
+        "```",
+        "",
+        "Daily Feature test-knowledge write-back still uses `taskKind: \"knowledge-sync\"` with a bound `featureId`, separate from graph bootstrap/incremental entry points.",
+        "",
         "## Verification",
         "",
         `Use \`${input.governanceRoot}/verification-matrix.md\` to choose the narrowest command that proves the claim.`,
@@ -2525,38 +2639,31 @@ export async function applyInitUpdate(input) {
         });
     }
     if (input.applySafe) {
+        const existingSurface = await readExistingSurfaceState(repoRoot);
+        // Preserve source strength: recorded stays recorded so unchanged owned files
+        // remain deterministic refresh candidates; bootstrap/inferred stays inferred.
+        const preservedStateKind = existingSurface?.stateKind === "recorded" ? "recorded" : "inferred-baseline";
         const report = await checkInitUpdate({ repoRoot, projectName, governanceRoot });
         for (const action of report.deterministicActions) {
             if (action.type === "bootstrap-surface") {
                 skipped.push(action);
                 continue;
             }
-            if (action.type !== "strip-pi-requires-api-key" &&
-                action.type !== "add-harness-schema-ref" &&
-                action.type !== "refresh-owned-file" &&
-                action.type !== "migrate-harness-governance-root" &&
-                action.type !== "migrate-harness-model-fields" &&
-                action.type !== "migrate-owned-file" &&
-                action.type !== "remove-owned-file" &&
-                action.type !== "remove-empty-directory") {
-                const currentState = await buildCurrentSurfaceState({
-                    repoRoot,
-                    projectName,
-                    governanceRoot,
-                    stateKind: "inferred-baseline",
-                });
-                const relationship = currentState.files[action.path]?.relationship;
-                if (relationship === "local-existing-unknown") {
-                    skipped.push(action);
-                    continue;
-                }
-            }
+            // The report was produced immediately before this batch. Each action also
+            // performs its own target check; missing-file writes refuse existing paths,
+            // while managed blocks merge into the latest user-authored content.
             if (await applySafeAction({ repoRoot, projectName, governanceRoot, action }))
                 applied.push(action);
             else
                 skipped.push(action);
         }
-        await writeInitSurfaceState({ repoRoot, projectName, governanceRoot, stateKind: "inferred-baseline" });
+        await writeInitSurfaceState({
+            repoRoot,
+            projectName,
+            governanceRoot,
+            stateKind: preservedStateKind,
+            preserveOwnershipFrom: existingSurface,
+        });
     }
     return {
         applied,

package/dist/executors/pi-sdk-executor.js

@@ -51,31 +51,38 @@ export function setPiSdkImportOverrideForTests(fn) {
 export function setPiSdkModuleOverrideForTests(fn) {
     sdkModuleOverrideForTests = fn;
 }
-/** Check whether the Pi SDK optional dependency is importable. */
+/** Check whether the Pi SDK optional dependency satisfies the 0.80.10 runtime contract. */
 export async function checkPiSdkAvailability(_repoRoot) {
     if (sdkSessionFactoryOverride) {
         return { ok: true, detail: 'pi SDK session factory override active' };
     }
     try {
-        if (sdkImportOverrideForTests) {
-            await sdkImportOverrideForTests();
+        const imported = sdkImportOverrideForTests
+            ? await sdkImportOverrideForTests()
+            : await loadPiSdkModule();
+        const sdk = imported;
+        const ModelRuntime = sdk.ModelRuntime;
+        if (typeof sdk.createAgentSession !== 'function'
+            || typeof sdk.getAgentDir !== 'function'
+            || typeof ModelRuntime?.create !== 'function') {
+            return {
+                ok: false,
+                detail: 'pi SDK incompatible: requires createAgentSession, getAgentDir, and ModelRuntime.create (0.80.10 contract)',
+            };
         }
-        else {
-            await import('@earendil-works/pi-coding-agent');
-        }
-        return { ok: true, detail: 'pi SDK available' };
+        return { ok: true, detail: 'pi SDK 0.80.10 contract available' };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         return { ok: false, detail: `pi SDK not available: ${message}` };
     }
 }
-async function resolveModelViaRegistry(modelRegistry, provider, modelId) {
-    const fromRegistry = modelRegistry.find(provider, modelId);
-    if (fromRegistry)
-        return fromRegistry;
+async function resolveModel(modelRuntime, provider, modelId) {
+    const fromRuntime = modelRuntime.getModel(provider, modelId);
+    if (fromRuntime)
+        return fromRuntime;
     try {
-        const piAi = await import('@earendil-works/pi-ai');
+        const piAi = await import('@earendil-works/pi-ai/compat');
         return piAi.getModel?.(provider, modelId);
     }
     catch {
@@ -93,12 +100,16 @@ async function getOrCreateSharedResources(state) {
         return state.resources;
     const sdk = await loadPiSdkModule();
     const getAgentDir = sdk.getAgentDir;
-    const AuthStorage = sdk.AuthStorage;
-    const ModelRegistry = sdk.ModelRegistry;
+    const ModelRuntime = sdk.ModelRuntime;
+    if (typeof ModelRuntime?.create !== 'function') {
+        throw new Error('incompatible pi SDK: ModelRuntime.create is unavailable');
+    }
     const agentDir = getAgentDir();
-    const authStorage = AuthStorage.create();
-    const modelRegistry = ModelRegistry.create(authStorage);
-    state.resources = { agentDir, authStorage, modelRegistry };
+    const modelRuntime = await ModelRuntime.create({
+        authPath: path.join(agentDir, 'auth.json'),
+        modelsPath: path.join(agentDir, 'models.json'),
+    });
+    state.resources = { agentDir, modelRuntime };
     return state.resources;
 }
 async function createSdkSession(sdk, input, shared) {
@@ -106,13 +117,17 @@ async function createSdkSession(sdk, input, shared) {
     const SessionManager = sdk.SessionManager;
     const DefaultResourceLoader = sdk.DefaultResourceLoader;
     const getAgentDir = sdk.getAgentDir;
-    const AuthStorage = sdk.AuthStorage;
-    const ModelRegistry = sdk.ModelRegistry;
+    const ModelRuntime = sdk.ModelRuntime;
     const agentDir = shared?.agentDir ?? getAgentDir();
-    const authStorage = shared?.authStorage ?? AuthStorage.create();
-    const modelRegistry = shared?.modelRegistry ?? ModelRegistry.create(authStorage);
+    if (!shared && typeof ModelRuntime?.create !== 'function') {
+        throw new Error('incompatible pi SDK: ModelRuntime.create is unavailable');
+    }
+    const modelRuntime = shared?.modelRuntime ?? await ModelRuntime.create({
+        authPath: path.join(agentDir, 'auth.json'),
+        modelsPath: path.join(agentDir, 'models.json'),
+    });
     const model = input.provider && input.model
-        ? await resolveModelViaRegistry(modelRegistry, input.provider, input.model)
+        ? await resolveModel(modelRuntime, input.provider, input.model)
         : undefined;
     const loader = new DefaultResourceLoader({
         cwd: input.cwd,
@@ -127,8 +142,7 @@ async function createSdkSession(sdk, input, shared) {
         sessionManager: SessionManager.inMemory(input.cwd),
         resourceLoader: loader,
         tools: input.toolNames,
-        authStorage,
-        modelRegistry,
+        modelRuntime,
         ...(model ? { model } : {}),
         ...(input.thinking ? { thinkingLevel: input.thinking } : {}),
     });