psyclaw 0.25.2 → 0.26.1

package/dist/src/research/brief.js

@@ -0,0 +1,81 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { checkEvidenceSufficiency } from "../core/evidence-policy.js";
+import { projectPaths } from "../project/paths.js";
+import { loadLedger, readProject } from "./ledger.js";
+import { writeHandoff } from "../project/bootstrap.js";
+import { atomicWriteFile } from "../project/jsonl.js";
+import { RunEventLog } from "../panel/events.js";
+export async function runOfflineBrief(root) {
+    const paths = projectPaths(root);
+    const runId = `run_${randomUUID().replaceAll("-", "")}`;
+    const project = await readProject(root);
+    const ledger = await loadLedger(root);
+    const gates = checkEvidenceSufficiency({ ...ledger, paradigm: project.paradigm });
+    const blocked = gates.filter((gate) => !gate.ok);
+    const eventLog = new RunEventLog(root, runId);
+    const eventAt = new Date().toISOString();
+    await eventLog.append({ type: "planned", at: eventAt });
+    for (const gate of gates)
+        await eventLog.append({ type: "gate", at: eventAt, message: gate.reason });
+    await eventLog.append({
+        type: blocked.length === 0 ? "completed" : "blocked",
+        at: eventAt,
+        message: blocked.length === 0 ? "all evidence gates passed" : "evidence gates blocked",
+    });
+    const manifest = {
+        schemaVersion: "psyclaw/brief-manifest/v1",
+        runId,
+        inputs: ledger.evidence.map((item) => ({ id: item.id, sha256: item.sha256, locator: item.source.locator })),
+        claims: ledger.claims.map((claim) => ({ id: claim.id, status: claim.status, evidenceIds: claim.evidenceIds })),
+        gates,
+        generatedAt: new Date().toISOString(),
+    };
+    await mkdir(paths.manifests, { recursive: true });
+    const manifestPath = join(paths.manifests, `${runId}.json`);
+    await atomicWriteFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    let briefPath;
+    if (blocked.length === 0) {
+        const goal = project.goal;
+        const lines = [
+            "# Research Brief",
+            "",
+            `Research goal: ${goal}`,
+            "",
+            "## Audited Claims",
+            "",
+            ...ledger.claims.map((claim) => `- ${claim.text} [${claim.status}]`),
+            "",
+            "Evidence and limitations are recorded in the manifest and ledger.",
+            "",
+        ];
+        briefPath = join(paths.outputs, "brief.md");
+        await atomicWriteFile(briefPath, lines.join("\n"));
+    }
+    const verdictPath = join(paths.manifests, `${runId}.verdict.json`);
+    const verdict = {
+        schemaVersion: "psyclaw/verdict/v1",
+        runId,
+        verdict: blocked.length === 0 ? "pass" : "blocked",
+        manifestPath,
+        ...(briefPath ? { briefPath } : {}),
+        gateCount: gates.length,
+        blockedGateCount: blocked.length,
+        generatedAt: new Date().toISOString(),
+    };
+    await atomicWriteFile(verdictPath, `${JSON.stringify(verdict, null, 2)}\n`);
+    const handoff = await writeHandoff(root, {
+        projectId: project.id,
+        runId,
+        goal: project.goal,
+        completed: ["evidence ledger loaded", "evidence sufficiency gates evaluated"],
+        verified: blocked.length === 0 ? ["brief.md", "manifest", "verdict"] : ["manifest", "verdict"],
+        blocked: blocked.map((gate) => gate.reason),
+        nextSteps: blocked.length === 0 ? ["human review before external use"] : ["resolve blocked evidence gates"],
+        verificationCommands: ["pnpm typecheck", "pnpm test"],
+        generatedAt: new Date().toISOString(),
+    });
+    return { runId, verdict: blocked.length === 0 ? "pass" : "blocked", gates, ...(briefPath ? { briefPath } : {}), manifestPath, verdictPath, handoff };
+}
+//# sourceMappingURL=brief.js.map

package/dist/src/research/brief.js.map

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

package/dist/src/research/ledger.d.ts

@@ -0,0 +1,12 @@
+import type { Claim, ClaimEvidenceLink, Evidence } from "../core/contracts.js";
+export interface LedgerSnapshot {
+    evidence: Evidence[];
+    claims: Claim[];
+    links: ClaimEvidenceLink[];
+}
+export declare function loadLedger(root: string): Promise<LedgerSnapshot>;
+export declare function appendEvidence(root: string, evidence: Evidence): Promise<void>;
+export declare function appendClaim(root: string, claim: Claim): Promise<void>;
+export declare function appendClaimEvidenceLink(root: string, link: ClaimEvidenceLink): Promise<void>;
+export declare function readProjectGoal(root: string): Promise<string>;
+export declare function readProject(root: string): Promise<import("../core/contracts.js").ResearchProject>;

package/dist/src/research/ledger.js

@@ -0,0 +1,43 @@
+import { readFile } from "node:fs/promises";
+import { appendJsonl, readJsonl } from "../project/jsonl.js";
+import { projectPaths } from "../project/paths.js";
+import { asClaim, asClaimEvidenceLink, asEvidence, asProject } from "../core/schemas.js";
+export async function loadLedger(root) {
+    const paths = projectPaths(root);
+    const evidence = (await readJsonl(paths.evidence)).map((value) => asEvidence(value));
+    const claims = [];
+    const links = [];
+    for (const value of await readJsonl(paths.claims)) {
+        if (typeof value !== "object" || value === null)
+            throw new Error("Invalid claims record");
+        if ("relation" in value && "claimId" in value && "evidenceId" in value) {
+            links.push(asClaimEvidenceLink(value));
+        }
+        else {
+            claims.push(asClaim(value));
+        }
+    }
+    return {
+        evidence,
+        claims,
+        links,
+    };
+}
+export async function appendEvidence(root, evidence) {
+    asEvidence(evidence);
+    await appendJsonl(projectPaths(root).evidence, evidence);
+}
+export async function appendClaim(root, claim) {
+    await appendJsonl(projectPaths(root).claims, asClaim({ ...claim, recordType: "claim" }));
+}
+export async function appendClaimEvidenceLink(root, link) {
+    await appendJsonl(projectPaths(root).claims, asClaimEvidenceLink({ ...link, recordType: "claim-evidence-link" }));
+}
+export async function readProjectGoal(root) {
+    const project = asProject(JSON.parse(await readFile(projectPaths(root).project, "utf8")));
+    return project.goal;
+}
+export async function readProject(root) {
+    return asProject(JSON.parse(await readFile(projectPaths(root).project, "utf8")));
+}
+//# sourceMappingURL=ledger.js.map

package/dist/src/research/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../../src/research/ledger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AASzF,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,QAAQ,GAAG,CAAC,MAAM,SAAS,CAAU,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9F,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAwB,EAAE,CAAC;IACtC,KAAK,MAAM,KAAK,IAAI,MAAM,SAAS,CAAU,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QAC1F,IAAI,UAAU,IAAI,KAAK,IAAI,SAAS,IAAI,KAAK,IAAI,YAAY,IAAI,KAAK,EAAE,CAAC;YACvE,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC;QACzC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,OAAO;QACL,QAAQ;QACR,MAAM;QACN,KAAK;KACN,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAY,EAAE,QAAkB;IACnE,UAAU,CAAC,QAAQ,CAAC,CAAC;IACrB,MAAM,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,KAAY;IAC1D,MAAM,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,IAAY,EAAE,IAAuB;IACjF,MAAM,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,qBAAqB,EAAE,CAAC,CAAC,CAAC;AACpH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY;IAChD,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1F,OAAO,OAAO,CAAC,IAAI,CAAC;AACtB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY;IAC5C,OAAO,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;AACnF,CAAC"}

package/dist/src/run.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Staged progress output for psyclaw workflows: prints `[stage] label…` lines
+ * the way a research pipeline reads. The stage tag is rendered in the psyclaw
+ * accent color; notes are dimmed. Used by the `psyclaw_workflow` tool (captured
+ * into the tool result) and by TTY sessions. Pure line formatting is exported
+ * for tests.
+ */
+export declare function formatStageLine(tag: string, label: string, color?: boolean): string;
+export declare function formatNoteLine(note: string, color?: boolean): string;
+export interface StageRunnerOptions {
+    /** Override stdout (tests). */
+    write?: (line: string) => void;
+    color?: boolean;
+}
+export interface StageRunner {
+    /** Print `[tag] label…`, run `fn`, then print an optional completion note. */
+    stage<T>(tag: string, label: string, fn: () => Promise<T>, onDone?: (result: T) => string): Promise<T>;
+    note(message: string): void;
+}
+export declare function createStageRunner(options?: StageRunnerOptions): StageRunner;

package/dist/src/run.js

@@ -0,0 +1,34 @@
+/**
+ * Staged progress output for psyclaw workflows: prints `[stage] label…` lines
+ * the way a research pipeline reads. The stage tag is rendered in the psyclaw
+ * accent color; notes are dimmed. Used by the `psyclaw_workflow` tool (captured
+ * into the tool result) and by TTY sessions. Pure line formatting is exported
+ * for tests.
+ */
+const ACCENT = "\x1b[36m"; // teal
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+export function formatStageLine(tag, label, color = true) {
+    const tagPart = color ? `${ACCENT}[${tag}]${RESET}` : `[${tag}]`;
+    return `${tagPart} ${label}`;
+}
+export function formatNoteLine(note, color = true) {
+    return color ? `  ${DIM}${note}${RESET}` : `  ${note}`;
+}
+export function createStageRunner(options = {}) {
+    const write = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const color = options.color ?? process.stdout.isTTY;
+    return {
+        note(message) {
+            write(formatNoteLine(message, color));
+        },
+        async stage(tag, label, fn, onDone) {
+            write(formatStageLine(tag, `${label}…`, color));
+            const result = await fn();
+            if (onDone !== undefined)
+                write(formatNoteLine(onDone(result), color));
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=run.js.map

package/dist/src/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,OAAO;AAClC,MAAM,GAAG,GAAG,SAAS,CAAC;AACtB,MAAM,KAAK,GAAG,SAAS,CAAC;AAExB,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,KAAa,EAAE,KAAK,GAAG,IAAI;IACtE,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC;IACjE,OAAO,GAAG,OAAO,IAAI,KAAK,EAAE,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,KAAK,GAAG,IAAI;IACvD,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;AACzD,CAAC;AAcD,MAAM,UAAU,iBAAiB,CAAC,UAA8B,EAAE;IAChE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC;IAC7E,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;IACpD,OAAO;QACL,IAAI,CAAC,OAAe;YAClB,KAAK,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QACxC,CAAC;QACD,KAAK,CAAC,KAAK,CAAI,GAAW,EAAE,KAAa,EAAE,EAAoB,EAAE,MAA8B;YAC7F,KAAK,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;YAChD,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;YAC1B,IAAI,MAAM,KAAK,SAAS;gBAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;YACvE,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/setup.d.ts

@@ -0,0 +1,54 @@
+export interface ProviderPreset {
+    id: string;
+    name: string;
+    baseUrl: string;
+    api: "openai-completions" | "anthropic-messages";
+    apiKeyEnv: string;
+    models: readonly {
+        id: string;
+        name: string;
+        reasoning?: boolean;
+    }[];
+}
+/**
+ * Generic, provider-neutral presets. None of these embed a literal API key:
+ * the `apiKey` is written as an environment-variable reference (`$ENV`), so
+ * the user supplies the secret in their shell environment, never on disk.
+ */
+export declare const PROVIDER_PRESETS: readonly ProviderPreset[];
+export interface SetupOptions {
+    agentDir?: string;
+    /** Provider ids to write; defaults to all presets (the generic guide). */
+    providers?: readonly string[];
+}
+export interface SetupResult {
+    path: string;
+    providers: string[];
+}
+export interface ProviderConfigInput {
+    id: string;
+    name: string;
+    baseUrl: string;
+    api: "openai-completions" | "anthropic-messages";
+    apiKeyEnv: string;
+    models: readonly {
+        id: string;
+        name?: string;
+        reasoning?: boolean;
+    }[];
+    apiKey?: string;
+}
+/** Persist provider metadata and, when supplied, the key in Pi's auth store. */
+export declare function saveProviderConfig(input: ProviderConfigInput, options?: {
+    agentDir?: string;
+}): Promise<SetupResult>;
+/**
+ * Write Pi's `models.json` with the selected provider presets, merging into
+ * any existing providers rather than clobbering them. No API key literal is
+ * ever written — only `$ENV_VAR` references.
+ */
+export declare function setupProviders(options?: SetupOptions): Promise<SetupResult>;
+/** Whether any provider has been written to `models.json` yet. */
+export declare function hasConfiguredProvider(options?: {
+    agentDir?: string;
+}): Promise<boolean>;

package/dist/src/setup.js

@@ -0,0 +1,221 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { DEFAULT_PRICING, PROVIDER_PRICING } from "./core/pricing.js";
+/**
+ * Generic, provider-neutral presets. None of these embed a literal API key:
+ * the `apiKey` is written as an environment-variable reference (`$ENV`), so
+ * the user supplies the secret in their shell environment, never on disk.
+ */
+export const PROVIDER_PRESETS = [
+    {
+        id: "deepseek",
+        name: "DeepSeek",
+        baseUrl: "https://api.deepseek.com",
+        api: "openai-completions",
+        apiKeyEnv: "DEEPSEEK_API_KEY",
+        models: [
+            { id: "deepseek-v4-flash", name: "DeepSeek V4 Flash" },
+            { id: "deepseek-v4-pro", name: "DeepSeek V4 Pro", reasoning: true },
+        ],
+    },
+    {
+        id: "openai",
+        name: "OpenAI",
+        baseUrl: "https://api.openai.com/v1",
+        api: "openai-completions",
+        apiKeyEnv: "OPENAI_API_KEY",
+        models: [
+            { id: "gpt-5.5", name: "GPT-5.5" },
+            { id: "gpt-5.5-pro", name: "GPT-5.5 Pro", reasoning: true },
+        ],
+    },
+    {
+        id: "anthropic",
+        name: "Anthropic",
+        baseUrl: "https://api.anthropic.com",
+        api: "anthropic-messages",
+        apiKeyEnv: "ANTHROPIC_API_KEY",
+        models: [
+            { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
+            { id: "claude-opus-4-8", name: "Claude Opus 4.8", reasoning: true },
+        ],
+    },
+    {
+        id: "qwen",
+        name: "通义千问",
+        baseUrl: "https://dashscope.aliyuncs.com/compatible-mode",
+        api: "openai-completions",
+        apiKeyEnv: "DASHSCOPE_API_KEY",
+        models: [
+            { id: "qwen3.6-plus", name: "Qwen 3.6 Plus" },
+            { id: "qwen3.7-max", name: "Qwen 3.7 Max", reasoning: true },
+            { id: "qwen3.6-flash", name: "Qwen 3.6 Flash" },
+        ],
+    },
+    {
+        id: "zhipu",
+        name: "智谱 GLM",
+        baseUrl: "https://open.bigmodel.cn/api/paas/v4",
+        api: "openai-completions",
+        apiKeyEnv: "ZHIPU_API_KEY",
+        models: [
+            { id: "glm-5", name: "GLM-5", reasoning: true },
+            { id: "glm-5.1", name: "GLM-5.1", reasoning: true },
+            { id: "glm-5-turbo", name: "GLM-5 Turbo" },
+        ],
+    },
+    {
+        id: "moonshot",
+        name: "月之暗面 Kimi",
+        baseUrl: "https://api.moonshot.cn/v1",
+        api: "openai-completions",
+        apiKeyEnv: "MOONSHOT_API_KEY",
+        models: [
+            { id: "kimi-k2.6", name: "Kimi K2.6", reasoning: true },
+            { id: "kimi-k2.5", name: "Kimi K2.5" },
+        ],
+    },
+    {
+        id: "ollama",
+        name: "Ollama（本地）",
+        baseUrl: "http://localhost:11434/v1",
+        api: "openai-completions",
+        apiKeyEnv: "OLLAMA_API_KEY",
+        models: [
+            { id: "qwen3:8b", name: "Qwen3 8B" },
+            { id: "qwen3:14b", name: "Qwen3 14B" },
+            { id: "deepseek-r1:8b", name: "DeepSeek R1 8B", reasoning: true },
+        ],
+    },
+    {
+        id: "custom",
+        name: "自定义 OpenAI 兼容接口",
+        baseUrl: "",
+        api: "openai-completions",
+        apiKeyEnv: "PSYCLAW_CUSTOM_API_KEY",
+        models: [],
+    },
+];
+function providerToJson(preset) {
+    const pricing = PROVIDER_PRICING[preset.id] ?? DEFAULT_PRICING;
+    return {
+        baseUrl: preset.baseUrl,
+        api: preset.api,
+        apiKey: `$${preset.apiKeyEnv}`,
+        models: preset.models.map((model) => ({
+            id: model.id,
+            name: model.name,
+            ...(model.reasoning === undefined ? {} : { reasoning: model.reasoning }),
+            cost: { ...pricing },
+        })),
+    };
+}
+function providerConfig(input) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(input.id))
+        throw new Error("Invalid provider id");
+    if (!/^[A-Z][A-Z0-9_]{0,127}$/.test(input.apiKeyEnv))
+        throw new Error("Invalid API key environment name");
+    if (input.baseUrl) {
+        const url = new URL(input.baseUrl);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            throw new Error("Provider endpoint must use http or https");
+        if (url.username || url.password || url.hash)
+            throw new Error("Provider endpoint must not contain credentials or fragments");
+    }
+    if (input.models.length === 0)
+        throw new Error("At least one model is required");
+    const pricing = PROVIDER_PRICING[input.id] ?? DEFAULT_PRICING;
+    return {
+        baseUrl: input.baseUrl,
+        api: input.api,
+        apiKey: `$${input.apiKeyEnv}`,
+        models: input.models.map((model) => ({
+            id: model.id,
+            name: model.name ?? model.id,
+            ...(model.reasoning === undefined ? {} : { reasoning: model.reasoning }),
+            cost: { ...pricing },
+        })),
+    };
+}
+/** Persist provider metadata and, when supplied, the key in Pi's auth store. */
+export async function saveProviderConfig(input, options = {}) {
+    const agentDir = options.agentDir ?? getAgentDir();
+    const modelsPath = join(agentDir, "models.json");
+    let existing = {};
+    try {
+        const parsed = JSON.parse(await readFile(modelsPath, "utf8"));
+        if (parsed.providers && typeof parsed.providers === "object" && !Array.isArray(parsed.providers)) {
+            existing.providers = parsed.providers;
+        }
+    }
+    catch { /* start with a new catalog */ }
+    await mkdir(agentDir, { recursive: true });
+    await writeFile(modelsPath, `${JSON.stringify({ providers: { ...existing.providers, [input.id]: providerConfig(input) } }, null, 2)}\n`, "utf8");
+    if (input.apiKey?.trim()) {
+        // AuthStorage is intentionally not part of Pi's public root export. Resolve
+        // the locked runtime's implementation without reading or logging secrets.
+        const entry = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
+        const { AuthStorage } = await import(pathToFileURL(join(dirname(entry), "core", "auth-storage.js")).href);
+        const auth = AuthStorage.create(join(agentDir, "auth.json"));
+        await auth.modify(input.id, async () => ({ type: "api_key", key: input.apiKey.trim() }));
+    }
+    return { path: modelsPath, providers: [input.id] };
+}
+/**
+ * Write Pi's `models.json` with the selected provider presets, merging into
+ * any existing providers rather than clobbering them. No API key literal is
+ * ever written — only `$ENV_VAR` references.
+ */
+export async function setupProviders(options = {}) {
+    const agentDir = options.agentDir ?? getAgentDir();
+    const modelsPath = join(agentDir, "models.json");
+    const selected = options.providers && options.providers.length > 0
+        ? options.providers
+        : PROVIDER_PRESETS.map((preset) => preset.id);
+    const providers = {};
+    for (const id of selected) {
+        const preset = PROVIDER_PRESETS.find((candidate) => candidate.id === id);
+        if (!preset)
+            throw new Error(`Unknown provider: ${id}`);
+        providers[id] = providerToJson(preset);
+    }
+    let existing = {};
+    try {
+        const parsed = JSON.parse(await readFile(modelsPath, "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const candidate = parsed.providers;
+            if (candidate && typeof candidate === "object" && !Array.isArray(candidate)) {
+                existing = { providers: candidate };
+            }
+        }
+    }
+    catch {
+        // Missing or malformed file: start from the presets.
+    }
+    await mkdir(agentDir, { recursive: true });
+    const merged = { ...existing.providers, ...providers };
+    await writeFile(modelsPath, `${JSON.stringify({ providers: merged }, null, 2)}\n`, "utf8");
+    return { path: modelsPath, providers: Object.keys(providers) };
+}
+/** Whether any provider has been written to `models.json` yet. */
+export async function hasConfiguredProvider(options = {}) {
+    const agentDir = options.agentDir ?? getAgentDir();
+    const modelsPath = join(agentDir, "models.json");
+    try {
+        const parsed = JSON.parse(await readFile(modelsPath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return false;
+        const providers = parsed.providers;
+        return providers !== undefined &&
+            typeof providers === "object" &&
+            !Array.isArray(providers) &&
+            Object.keys(providers).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=setup.js.map

package/dist/src/setup.js.map

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

package/dist/src/skills/contracts.d.ts

@@ -0,0 +1,105 @@
+/** The descriptor is the only object needed by a router during discovery. */
+export declare const SKILL_DESCRIPTOR_VERSION: "psyclaw/skill-descriptor/v1";
+export type SkillLicenseStatus = "verified" | "declared" | "missing" | "invalid" | "unknown";
+export type SkillDependencyStatus = "ready" | "declared" | "missing" | "blocked" | "unknown";
+export type SkillTrustStatus = "trusted" | "untrusted" | "blocked" | "unknown";
+export type SkillRiskLevel = "low" | "medium" | "high" | "critical" | "unknown";
+/**
+ * Host-side approval is deliberately separate from descriptor metadata.
+ * A skill may describe itself as `trusted`, but only an approval supplied by
+ * the host can move it out of discover-only mode.
+ */
+export type SkillApprovalStatus = "discover-only" | "approved" | "blocked" | "stale";
+/**
+ * Host-generated supply-chain evidence.  These fields deliberately live
+ * outside SKILL.md frontmatter: a skill cannot certify its own license,
+ * dependency audit, or SBOM.
+ */
+export interface SkillAdmissionEvidence {
+    schemaVersion: "psyclaw/skill-admission/v1";
+    contentSha256: string;
+    licenseSpdx: string;
+    licenseEvidenceRef: string;
+    dependencyEvidenceRef: string;
+    sbomSha256: string;
+}
+export interface SkillApproval {
+    /** `false` is an explicit deny and takes precedence over every other field. */
+    approved: boolean;
+    /** Optional content pin. When present, it must match the discovered SHA. */
+    sha256?: string;
+    /** Optional logical path pin, resolved relative to the process cwd. */
+    sourcePath?: string;
+    /** Optional canonical path pin. Useful for lock/manifest based approvals. */
+    resolvedPath?: string;
+    /** Required host-side manifest/SBOM attestation for execution. */
+    admission?: SkillAdmissionEvidence;
+}
+export type SkillApprovalEntry = boolean | SkillApproval;
+export type SkillApprovalMap = Readonly<Record<string, SkillApprovalEntry>> | ReadonlyMap<string, SkillApprovalEntry>;
+export interface SkillDescriptor {
+    schemaVersion: typeof SKILL_DESCRIPTOR_VERSION;
+    /** Stable id used by routing and explicit load/enable operations. */
+    id: string;
+    name: string;
+    description: string;
+    /** Absolute path as discovered from the caller-provided root. */
+    sourcePath: string;
+    /** Canonical path used for reads; never a symlink. */
+    resolvedPath: string;
+    /** Canonical root under which the skill was discovered. */
+    rootPath: string;
+    /** SHA-256 of the complete SKILL.md file, including frontmatter. */
+    sha256: string;
+    licenseStatus: SkillLicenseStatus;
+    dependencyStatus: SkillDependencyStatus;
+    /** Metadata-derived trust; never sufficient for execution by itself. */
+    trust: SkillTrustStatus;
+    risk: SkillRiskLevel;
+    /** Host approval state. `discover-only` is the secure default. */
+    approvalStatus: SkillApprovalStatus;
+    /** Runtime routing toggle; always false after discovery until explicitly enabled. */
+    enabled: boolean;
+    /** Duplicate ids are retained and marked instead of being overwritten. */
+    conflicted: boolean;
+    /** YAML frontmatter only. It never contains the Markdown body. */
+    metadata: Readonly<Record<string, unknown>>;
+}
+export interface LoadedSkill extends SkillDescriptor {
+    /** Markdown after the YAML frontmatter delimiter. */
+    body: string;
+}
+export type SkillDiagnosticSeverity = "warning" | "error";
+export type SkillDiagnosticCode = "root-not-found" | "root-not-directory" | "root-symlink" | "path-traversal" | "symlink-path" | "invalid-frontmatter" | "invalid-metadata" | "read-error" | "hash-error" | "duplicate-id" | "not-found" | "ambiguous-id" | "blocked-skill" | "suspicious-body";
+export interface SkillDiagnostic {
+    code: SkillDiagnosticCode;
+    severity: SkillDiagnosticSeverity;
+    message: string;
+    path?: string;
+    skillId?: string;
+    relatedPaths?: string[];
+}
+export interface SkillDiscoveryReport {
+    skills: SkillDescriptor[];
+    diagnostics: SkillDiagnostic[];
+}
+export interface SkillRegistryOptions {
+    roots?: string[];
+    /** Explicit id allowlist. This is shorthand for `{ [id]: true }`. */
+    approvedIds?: readonly string[];
+    /** Explicit host approvals, optionally pinned to content and paths. */
+    approvals?: SkillApprovalMap;
+    /** Descriptive alias for `approvals` when loading a trust manifest. */
+    approvalMap?: SkillApprovalMap;
+    /** Backwards-compatible singular alias for `approvals`. */
+    approval?: SkillApprovalMap;
+    /**
+     * Deprecated compatibility option. Frontmatter `enabledByDefault` never
+     * grants host approval and this option is intentionally ignored.
+     */
+    enableByDefault?: boolean;
+}
+export interface SkillSearchOptions {
+    enabledOnly?: boolean;
+    limit?: number;
+}

package/dist/src/skills/contracts.js

@@ -0,0 +1,3 @@
+/** The descriptor is the only object needed by a router during discovery. */
+export const SKILL_DESCRIPTOR_VERSION = "psyclaw/skill-descriptor/v1";
+//# sourceMappingURL=contracts.js.map

package/dist/src/skills/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../../src/skills/contracts.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,CAAC,MAAM,wBAAwB,GAAG,6BAAsC,CAAC"}

package/dist/src/skills/preflight.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Content preflight for skill bodies. This is a heuristic tripwire, not an OS
+ * boundary: a body that instructs the agent to bypass gates or move data out
+ * of the project is marked suspicious and the skill is never executable.
+ */
+export interface PreflightResult {
+    suspicious: boolean;
+    findings: string[];
+}
+export declare function preflightSkillBody(body: string): PreflightResult;