@tea-agent/loop-agent 0.22.0 → 0.24.0

package/dist/worker/console/chat/instruction-skills.js

@@ -0,0 +1,217 @@
+/**
+ * Operator Chat — instruction skills whitelist (design §7.5 / plan D1).
+ *
+ * Hard rules (plan D1):
+ * - skills are READ-ONLY text context injected into the Chat system prompt;
+ * - skills are NEVER registered as executable tools;
+ * - the whitelist is a COMPILE-TIME constant (no runtime dir scan, no env override);
+ * - arbitrary pi extension / package tool / user-level ~/.pi/agent skill is
+ *   never discovered or loaded (V12);
+ * - project `.agents/skills/` (init projection) is NOT injected (prevents
+ *   target-repo injecting write instructions).
+ *
+ * Only the loop-agent repo's own audited skills are eligible. Workflow-specific
+ * skills are conditional on taskKind/workflow and loaded on demand (not in MVP
+ * operator-context default set).
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Operator-context instruction skills (plan D1, "operator-context 允许").
+ * These are read-only methodology skills. Loaded as text context for every
+ * Chat session by default.
+ *
+ * MUST stay a compile-time constant. Adding a skill requires an ADR / plan note.
+ */
+export const OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS = Object.freeze([
+    "grill-me",
+    "systematic-debugging",
+    "code-review-core",
+    "codebase-scout",
+    "verification-before-completion",
+    "requesting-code-review",
+    "analyze-product-requirements",
+    "analyze-product-dependencies",
+    "using-git-worktrees",
+]);
+/**
+ * Meta / governance skills that must NEVER be injected into Chat context
+ * (plan D1 "元 / 治理 skill"). Injecting these would let Chat rewrite its own
+ * governance. Listed explicitly so accidental allowlist edits are caught.
+ */
+export const OPERATOR_CHAT_DENIED_INSTRUCTION_SKILLS = Object.freeze([
+    "loop-agent",
+    "agent-worker",
+    "init-capability-evolution",
+    "ai-engineering-context",
+    "grill-with-docs",
+]);
+/**
+ * Workflow-specific skills (plan D1 "workflow-specific 允许（条件）").
+ * Only injected when the corresponding taskKind / workflow is active.
+ * NOT loaded by default in MVP Chat.
+ */
+export const OPERATOR_CHAT_WORKFLOW_CONDITIONAL_SKILLS = Object.freeze([
+    "frontend-implementation",
+    "frontend-review",
+    "frontend-verification",
+    "frontend-design-review",
+    "test-driven-development",
+    "webapp-testing",
+    "playwright-cli",
+    "playwright-cli-case-generator",
+    "browser-tools",
+]);
+const ALLOWED = new Set(OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS.map((s) => s.toLowerCase()));
+const DENIED = new Set(OPERATOR_CHAT_DENIED_INSTRUCTION_SKILLS.map((s) => s.toLowerCase()));
+const CONDITIONAL = new Set(OPERATOR_CHAT_WORKFLOW_CONDITIONAL_SKILLS.map((s) => s.toLowerCase()));
+export function isOperatorChatInstructionSkillAllowed(name) {
+    return ALLOWED.has(name.trim().toLowerCase());
+}
+export function isOperatorChatInstructionSkillDenied(name) {
+    return DENIED.has(name.trim().toLowerCase());
+}
+export function isOperatorChatInstructionSkillConditional(name) {
+    return CONDITIONAL.has(name.trim().toLowerCase());
+}
+export function classifyInstructionSkill(name, options) {
+    const n = name.trim().toLowerCase();
+    if (DENIED.has(n)) {
+        return { ok: false, reason: "denied-governance", name };
+    }
+    if (ALLOWED.has(n)) {
+        return { ok: true, kind: "operator-context", name };
+    }
+    if (CONDITIONAL.has(n)) {
+        const active = options?.activeWorkflowSkills ?? [];
+        const activeLower = new Set(active.map((s) => s.toLowerCase()));
+        if (activeLower.has(n)) {
+            // Conditional skill is allowed only when explicitly activated by workflow.
+            // For MVP, conditional skills are not auto-injected; callers must opt in.
+            return { ok: false, reason: "conditional-not-active", name };
+        }
+        return { ok: false, reason: "conditional-not-active", name };
+    }
+    return { ok: false, reason: "unknown", name };
+}
+/**
+ * Parse a SKILL.md frontmatter description (first `description:` line) and
+ * return the body text (frontmatter stripped). Tolerant of missing frontmatter.
+ */
+export function parseSkillFrontmatter(raw) {
+    let description = "";
+    let bodyText = raw;
+    const hasFrontmatter = raw.trimStart().startsWith("---");
+    if (hasFrontmatter) {
+        const lines = raw.split(/\r?\n/);
+        // find closing ---
+        let closeIdx = -1;
+        for (let i = 1; i < lines.length; i++) {
+            if (lines[i].trim() === "---") {
+                closeIdx = i;
+                break;
+            }
+        }
+        if (closeIdx > 0) {
+            const fm = lines.slice(1, closeIdx).join("\n");
+            bodyText = lines.slice(closeIdx + 1).join("\n").trim();
+            const descMatch = fm.match(/^description:\s*(.+)$/m);
+            if (descMatch) {
+                description = descMatch[1].trim().replace(/^["']|["']$/g, "");
+            }
+        }
+    }
+    else {
+        bodyText = raw.trim();
+    }
+    return { description, bodyText };
+}
+/**
+ * Load the operator-context instruction skills from the loop-agent repo's own
+ * `skills/` directory and return their text bodies for system-prompt injection.
+ *
+ * Security: only names in OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS are read;
+ * any other path is rejected before filesystem access (safe-side).
+ *
+ * @param skillsDir absolute path to the loop-agent repo `skills/` directory
+ *                  (source repo / npm pack asset, NOT target project `.agents/skills/`).
+ * @param names     override list (tests); defaults to the full allowlist.
+ */
+export async function loadOperatorChatInstructionSkills(skillsDir, names) {
+    const selected = names ?? OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS;
+    const loaded = [];
+    const failures = [];
+    const skipped = [];
+    for (const rawName of selected) {
+        const name = rawName.trim();
+        if (!isOperatorChatInstructionSkillAllowed(name)) {
+            skipped.push(name);
+            continue;
+        }
+        // Defense in depth: reject path traversal / governance skills even if
+        // an attacker managed to mutate the allowlist at runtime.
+        if (isOperatorChatInstructionSkillDenied(name)) {
+            skipped.push(name);
+            continue;
+        }
+        const skillPath = path.join(skillsDir, name, "SKILL.md");
+        const resolved = path.resolve(skillPath);
+        const resolvedSkillsDir = path.resolve(skillsDir);
+        if (!resolved.startsWith(resolvedSkillsDir + path.sep)) {
+            failures.push({
+                name,
+                message: "path escapes skills directory",
+            });
+            continue;
+        }
+        try {
+            const raw = await readFile(resolved, "utf8");
+            const { description, bodyText } = parseSkillFrontmatter(raw);
+            loaded.push({
+                name,
+                description,
+                bodyText,
+                charCount: bodyText.length,
+            });
+        }
+        catch (error) {
+            failures.push({
+                name,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { loaded, failures, skipped };
+}
+/** Hard cap on total injected instruction-skill chars (token budget guard). */
+export const OPERATOR_CHAT_INSTRUCTION_CHAR_BUDGET = 24_000;
+/**
+ * Compose the system-prompt fragment listing loaded instruction skills.
+ * Each skill is rendered as a bounded text block. If total chars exceed the
+ * budget, later skills are truncated (operator-context set is small enough
+ * that truncation should not trigger in practice, but the cap is enforced).
+ */
+export function composeInstructionSkillsPrompt(skills, budget = OPERATOR_CHAT_INSTRUCTION_CHAR_BUDGET) {
+    if (skills.length === 0)
+        return "";
+    const lines = [
+        "## Operator methodology context (read-only instruction skills)",
+        "",
+        "These skills are READ-ONLY context. You may reference their methodology when reasoning, but you CANNOT execute them. All actions must go through the registered operator tools.",
+        "",
+    ];
+    let used = 0;
+    for (const skill of skills) {
+        const header = `\n### ${skill.name}${skill.description ? ` — ${skill.description}` : ""}\n`;
+        const remaining = budget - used - header.length;
+        if (remaining <= 0) {
+            lines.push(`_[${skill.name}: omitted, char budget exhausted]_`);
+            break;
+        }
+        const slice = skill.bodyText.slice(0, Math.max(0, remaining));
+        lines.push(header);
+        lines.push(slice);
+        used += header.length + slice.length;
+    }
+    return lines.join("\n");
+}

package/dist/worker/console/chat/interview-adapter.js

@@ -0,0 +1,136 @@
+import { AssessmentStore, isAssessmentFreshForDraft } from "../interview/assessment.js";
+import { applyGrillMeAnswer, emptyDraft, isDraftStructurallyComplete, listDraftGaps, nextGrillMeQuestion } from "../interview/grill-me.js";
+import { InterviewSessionStore } from "../interview/session.js";
+import { DraftStore } from "../draft-store.js";
+import { normalizeConsoleWorkflowKind } from "../workflow-kinds.js";
+import { scrubSecrets } from "./explore-tools.js";
+function redact(value) {
+    const raw = JSON.stringify(value);
+    return JSON.parse(scrubSecrets(raw).scrubbed);
+}
+/** Browser/model-safe projection: strips app-data paths and scrubs secret-shaped content. */
+export function projectChatInterviewState(state) {
+    return redact({
+        interview: state.interview,
+        draft: { draft: state.draft.draft, draftSha256: state.draft.draftSha256 },
+        ...(state.question ? { question: state.question } : {}),
+        ...(state.taskKindRecommendation ? { taskKindRecommendation: state.taskKindRecommendation } : {}),
+        assessment: state.assessment,
+    });
+}
+export class ChatInterviewAdapter {
+    appData;
+    events;
+    interviews;
+    drafts;
+    assessments;
+    constructor(appData, events) {
+        this.appData = appData;
+        this.events = events;
+        this.interviews = new InterviewSessionStore(appData);
+        this.drafts = new DraftStore(appData);
+        this.assessments = new AssessmentStore(appData);
+    }
+    append(operatorSessionId, turnId, kind, data) {
+        this.events.append(operatorSessionId, turnId, { kind, data: redact(data) });
+    }
+    assessment(draft, assessmentId, fresh = false, reason) {
+        const missingFields = listDraftGaps(draft.draft);
+        return { outcome: missingFields.length === 0 ? "complete" : "questions-required", fresh, missingFields, ...(reason ? { reason } : {}), ...(assessmentId ? { assessmentId } : {}), draftSha256: draft.draftSha256 };
+    }
+    async start(input) {
+        const interview = await this.interviews.create({ taskId: input.taskId, operatorSessionId: input.operatorSessionId });
+        const base = emptyDraft(input.taskId, input.title);
+        const draft = await this.drafts.save({ ...base, ...input.initialDraft, requirement: { ...base.requirement, ...input.initialDraft?.requirement }, constraints: { ...base.constraints, ...input.initialDraft?.constraints }, verification: { ...base.verification, ...input.initialDraft?.verification }, schemaVersion: 1, taskId: input.taskId });
+        const question = nextGrillMeQuestion(draft.draft);
+        const savedInterview = await this.interviews.setCurrentQuestion(interview.sessionId, question ? { id: question.id, text: question.text, affectsFields: question.affectsFields, risk: question.risk } : undefined, question ? "awaiting-user-answer" : "draft-ready");
+        this.append(input.operatorSessionId, interview.sessionId, "interview-turn", { interviewSessionId: interview.sessionId, taskId: input.taskId, state: savedInterview.state, ...(question ? { question } : {}) });
+        this.append(input.operatorSessionId, interview.sessionId, "draft", { taskId: input.taskId, draft: draft.draft, draftSha256: draft.draftSha256 });
+        const assessment = this.assessment(draft);
+        this.append(input.operatorSessionId, interview.sessionId, "assessment", { taskId: input.taskId, ...assessment });
+        return { interview: savedInterview, draft, question, assessment };
+    }
+    async answer(input) {
+        const interview = await this.interviews.get(input.interviewSessionId);
+        if (!interview || interview.operatorSessionId !== input.operatorSessionId)
+            throw new Error("interview session not found for Chat session");
+        if (!interview.currentQuestion || interview.currentQuestion.id !== input.questionId)
+            throw new Error("answer does not match current open question");
+        const current = await this.drafts.get(interview.taskId);
+        if (!current)
+            throw new Error(`draft not found: ${interview.taskId}`);
+        const question = nextGrillMeQuestion(current.draft);
+        if (!question || question.id !== input.questionId)
+            throw new Error("draft gap does not match current question");
+        const applied = applyGrillMeAnswer(current.draft, question, { response: input.response, text: input.text });
+        const isTaskKind = question.gapId === "taskKind";
+        const recommendation = isTaskKind ? applied.taskKind : undefined;
+        if (isTaskKind)
+            delete applied.taskKind;
+        const draft = await this.drafts.save(applied);
+        await this.interviews.recordAnswer(interview.sessionId, { questionId: input.questionId, response: input.response, ...(input.text ? { text: input.text } : {}), at: new Date().toISOString() });
+        const projected = recommendation ? { ...draft.draft, taskKind: recommendation } : draft.draft;
+        const nextQuestion = nextGrillMeQuestion(projected);
+        const savedInterview = await this.interviews.setCurrentQuestion(interview.sessionId, nextQuestion ? { id: nextQuestion.id, text: nextQuestion.text, affectsFields: nextQuestion.affectsFields, risk: nextQuestion.risk } : undefined, nextQuestion ? "awaiting-user-answer" : "awaiting-confirmation");
+        this.append(input.operatorSessionId, interview.sessionId, "interview-turn", { interviewSessionId: interview.sessionId, taskId: interview.taskId, state: savedInterview.state, answer: { questionId: input.questionId, response: input.response, ...(input.text ? { text: input.text } : {}) }, ...(nextQuestion ? { question: nextQuestion } : {}) });
+        this.append(input.operatorSessionId, interview.sessionId, "draft", { taskId: interview.taskId, draft: draft.draft, draftSha256: draft.draftSha256, ...(recommendation ? { taskKindRecommendation: recommendation } : {}) });
+        const assessment = this.assessment({ ...draft, draft: projected });
+        this.append(input.operatorSessionId, interview.sessionId, "assessment", { taskId: interview.taskId, ...assessment });
+        return { interview: savedInterview, draft, question: nextQuestion, taskKindRecommendation: recommendation, assessment };
+    }
+    async confirmTaskKind(input) {
+        const interview = await this.interviews.get(input.interviewSessionId);
+        if (!interview || interview.operatorSessionId !== input.operatorSessionId)
+            throw new Error("interview session not found for Chat session");
+        const current = await this.drafts.get(interview.taskId);
+        if (!current)
+            throw new Error(`draft not found: ${interview.taskId}`);
+        const taskKind = normalizeConsoleWorkflowKind(input.taskKind, "standard");
+        // Save the taskKind change first so we have a stable draftSha256 to bind the
+        // assessment against (isAssessmentFreshForDraft compares draftSha256).
+        const draft = await this.drafts.save({ ...current.draft, taskKind });
+        const outcome = isDraftStructurallyComplete(draft.draft) ? "complete" : "questions-required";
+        const assessmentRef = await this.assessments.create({ draft: draft.draft, instructionVersion: interview.instructionVersion, provider: "deterministic", model: "grill-me", sessionId: interview.sessionId, turnId: interview.sessionId, outcome });
+        // Write the assessmentRef back into the draft so contractApply can resolve a
+        // fresh assessment from the DraftStore (operator-actions contractApply reads
+        // draft.interviewAssessmentRef.assessmentId). computeDraftSha256 excludes
+        // interviewAssessmentRef, so this does not churn the hash that certified it.
+        const draftWithRef = await this.drafts.save({ ...draft.draft, interviewAssessmentRef: { assessmentId: assessmentRef.assessmentId, draftSha256: draft.draftSha256 } });
+        const freshness = isAssessmentFreshForDraft(assessmentRef, draftWithRef.draft);
+        let savedInterview = await this.interviews.markDraftReady(interview.sessionId, draftWithRef.draft, draftWithRef.draftSha256);
+        savedInterview = await this.interviews.markAwaitingConfirmation(interview.sessionId, assessmentRef.assessmentId);
+        const assessment = this.assessment(draftWithRef, assessmentRef.assessmentId, freshness.fresh, freshness.fresh ? undefined : freshness.reason);
+        this.append(input.operatorSessionId, interview.sessionId, "taskKind-confirmed", { taskId: interview.taskId, taskKind, confirmedAt: new Date().toISOString(), confirmedBy: "human" });
+        this.append(input.operatorSessionId, interview.sessionId, "draft", { taskId: interview.taskId, draft: draftWithRef.draft, draftSha256: draftWithRef.draftSha256 });
+        this.append(input.operatorSessionId, interview.sessionId, "assessment", { taskId: interview.taskId, ...assessment });
+        return { interview: savedInterview, draft: draftWithRef, assessment };
+    }
+    async get(interviewSessionId) {
+        const interview = await this.interviews.get(interviewSessionId);
+        if (!interview)
+            return undefined;
+        const draft = await this.drafts.get(interview.taskId);
+        if (!draft)
+            return undefined;
+        const question = nextGrillMeQuestion(draft.draft);
+        let fresh = false;
+        let reason;
+        if (interview.assessmentId) {
+            const ref = await this.assessments.get(interview.assessmentId);
+            if (ref) {
+                const result = isAssessmentFreshForDraft(ref, draft.draft);
+                fresh = result.fresh;
+                if (!result.fresh)
+                    reason = result.reason;
+            }
+        }
+        return { interview, draft, question, assessment: this.assessment(draft, interview.assessmentId, fresh, reason) };
+    }
+    restore(operatorSessionId) {
+        const snapshot = this.events.snapshot(operatorSessionId);
+        if (!snapshot.length)
+            return undefined;
+        const latest = (kind) => [...snapshot].reverse().find((event) => event.kind === kind)?.data;
+        return { interview: latest("interview-turn"), draft: latest("draft")?.draft, assessment: latest("assessment"), taskKind: latest("taskKind-confirmed") };
+    }
+}

package/dist/worker/console/chat/model-resolver.js

@@ -0,0 +1,106 @@
+/**
+ * Operator Chat — default model resolver (no hardcoded model).
+ *
+ * Resolves the Chat default model from the repo harness.json `executors.pi.MED`
+ * tier, then finds a concrete provider by searching the Pi SDK's
+ * `snapshot.available` model list (preferring providers whose model entry is
+ * backed by credentials).
+ *
+ * Rationale: harness.json only stores a modelId per tier (e.g. "gpt-5.5"), not
+ * a provider. The Pi SDK `getModel(provider, modelId)` requires a provider, so
+ * we search `available` for entries whose `id` matches the modelId and pick the
+ * first whose provider resolves to a configured/credentialled source. This
+ * mirrors how the user's wizard-local / configured providers surface models.
+ *
+ * This module is deliberately framework-light: it takes a repoRoot + an
+ * optional model-list snapshot and returns a `{provider, modelId}` descriptor.
+ * The Pi runtime layer turns that into a concrete SDK model via getModel.
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+/** Tier keys in harness executors.pi that may override the default. */
+const EXECUTOR_TIERS = ["LOW", "MED", "HIGH"];
+/**
+ * Read executors.pi.<tier> from the repo harness.json. Returns undefined when
+ * harness.json is absent or the tier is unset / "default" sentinel.
+ *
+ * Default tier = MED (matches DAG executor model matrix convention).
+ */
+export async function readHarnessPiModelTier(repoRoot, tier = "MED") {
+    try {
+        const raw = await readFile(path.join(repoRoot, "harness.json"), "utf-8");
+        const manifest = JSON.parse(raw);
+        const pi = manifest.executors?.pi;
+        if (!pi)
+            return undefined;
+        const tierValue = pi[tier];
+        if (tierValue && tierValue !== "default")
+            return tierValue;
+        const defaultModel = pi.defaultModel;
+        if (defaultModel && defaultModel !== "default")
+            return defaultModel;
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Search the SDK's available-model list for entries matching a modelId.
+ *
+ * Matching rule: an entry matches when its `id` equals the modelId OR equals
+ * `<provider>/<modelId>` (SDK lists both bare and provider-prefixed ids).
+ *
+ * Provider preference (in order):
+ *   1. Bare-id entries (`id === modelId`) — these are the user's own provider
+ *      config (e.g. wizard-local registering `gpt-5.5`), preferred over
+ *      aggregator reseller entries (`openai/gpt-5.5` from openrouter).
+ *   2. Among matches, prefer those flagged hasCredentials=true (provider is
+ *      in the SDK's configuredProviders set).
+ *   3. Stable list order otherwise.
+ */
+export function findProviderForModelId(modelId, available) {
+    const matches = available.filter((m) => {
+        if (m.id === modelId)
+            return true;
+        if (m.id === `${m.provider}/${modelId}`)
+            return true;
+        const slash = m.id.lastIndexOf("/");
+        if (slash >= 0 && m.id.slice(slash + 1) === modelId)
+            return true;
+        return false;
+    });
+    if (matches.length === 0)
+        return undefined;
+    // Score: bare-id (0) beats prefixed (1); then hasCredentials wins; then order.
+    const score = (m) => {
+        let s = 0;
+        if (m.id !== modelId)
+            s += 1; // prefixed id is less preferred
+        if (m.hasCredentials !== true)
+            s += 2; // no credentials is less preferred
+        return s;
+    };
+    return [...matches].sort((a, b) => score(a) - score(b))[0];
+}
+/**
+ * Resolve the Chat default model descriptor. Returns undefined when no model
+ * can be resolved (harness unset + no snapshot match).
+ *
+ * @param repoRoot  repo with harness.json
+ * @param available SDK snapshot.available (already mapped to AvailableModelEntry)
+ * @param options.tier harness tier to read (default MED)
+ */
+export async function resolveDefaultChatModel(repoRoot, available, options) {
+    const modelId = await readHarnessPiModelTier(repoRoot, options?.tier ?? "MED");
+    if (!modelId)
+        return undefined;
+    const entry = findProviderForModelId(modelId, available);
+    if (!entry)
+        return undefined;
+    return {
+        provider: entry.provider,
+        modelId,
+        label: entry.name,
+    };
+}

package/dist/worker/console/chat/operation-card.js

@@ -0,0 +1,23 @@
+export function mergeOperationCardState(current, incoming) {
+    const index = current.findIndex((operation) => operation.operationId === incoming.operationId);
+    if (index < 0)
+        return [...current, incoming];
+    return current.map((operation, candidateIndex) => candidateIndex === index ? { ...operation, ...incoming } : operation);
+}
+export function operationFromEventPayload(payload) {
+    const operation = payload.operation;
+    if (!operation || typeof operation !== "object")
+        return undefined;
+    const candidate = operation;
+    if (candidate.schemaVersion !== 1 ||
+        typeof candidate.operationId !== "string" ||
+        typeof candidate.action !== "string" ||
+        typeof candidate.state !== "string" ||
+        typeof candidate.inspectHref !== "string" ||
+        typeof candidate.createdAt !== "string" ||
+        typeof candidate.updatedAt !== "string" ||
+        typeof candidate.previewHash !== "string") {
+        return undefined;
+    }
+    return candidate;
+}

package/dist/worker/console/chat/pi-console-config.js

@@ -0,0 +1,158 @@
+import { createHash, randomBytes } from "node:crypto";
+import { open, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { readJsonIfExists, writeSecureJson } from "../app-data.js";
+import { OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS } from "./instruction-skills.js";
+const revision = (raw) => createHash("sha256").update(raw).digest("hex");
+export async function readModelsConfig(agentDir) {
+    let raw = "{}";
+    try {
+        raw = await readFile(path.join(agentDir, "models.json"), "utf8");
+    }
+    catch {
+        /* empty config */
+    }
+    const parsed = JSON.parse(raw);
+    return {
+        revision: revision(raw),
+        providers: Object.entries(parsed.providers ?? {}).map(([name, provider]) => ({
+            name,
+            api: typeof provider.api === "string" ? provider.api : undefined,
+            baseUrl: typeof provider.baseUrl === "string" ? provider.baseUrl : undefined,
+            credential: {
+                configured: typeof provider.apiKey === "string" && provider.apiKey.length > 0,
+            },
+            models: Array.isArray(provider.models)
+                ? provider.models
+                    .map((model) => {
+                    const item = model && typeof model === "object"
+                        ? model
+                        : {};
+                    return {
+                        id: String(item.id ?? ""),
+                        name: typeof item.name === "string" ? item.name : undefined,
+                    };
+                })
+                    .filter((model) => model.id)
+                : [],
+        })),
+    };
+}
+export async function patchModelsConfig(agentDir, input) {
+    if (!["upsert-model", "remove-model", "remove-provider"].includes(input.action))
+        throw Object.assign(new Error("invalid models config action"), {
+            code: "INVALID_INPUT",
+            status: 400,
+        });
+    const file = path.join(agentDir, "models.json");
+    let raw = "{}";
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch {
+        /* create below */
+    }
+    if (revision(raw) !== input.expectedRevision)
+        throw Object.assign(new Error("models config changed"), {
+            code: "CONFIG_CONFLICT",
+            status: 409,
+        });
+    if (!/^[A-Za-z0-9._-]+$/.test(input.provider))
+        throw Object.assign(new Error("invalid provider"), {
+            code: "INVALID_INPUT",
+            status: 400,
+        });
+    const parsed = JSON.parse(raw);
+    parsed.providers ??= {};
+    const provider = parsed.providers[input.provider];
+    if (input.action === "remove-provider")
+        delete parsed.providers[input.provider];
+    else {
+        if (!provider)
+            throw Object.assign(new Error("provider not found; configure credentials with Pi CLI"), { code: "NOT_FOUND", status: 404 });
+        const models = Array.isArray(provider.models)
+            ? provider.models.filter((model) => model && typeof model === "object")
+            : [];
+        if (!input.model?.id || input.model.id.length > 160)
+            throw Object.assign(new Error("model id is required"), {
+                code: "INVALID_INPUT",
+                status: 400,
+            });
+        if (input.model.name && input.model.name.length > 160)
+            throw Object.assign(new Error("model name is too long"), {
+                code: "INVALID_INPUT",
+                status: 400,
+            });
+        provider.models =
+            input.action === "remove-model"
+                ? models.filter((model) => model.id !== input.model.id)
+                : [
+                    ...models.filter((model) => model.id !== input.model.id),
+                    {
+                        ...(models.find((model) => model.id === input.model.id) ?? {}),
+                        id: input.model.id,
+                        ...(input.model.name !== undefined
+                            ? { name: input.model.name }
+                            : {}),
+                    },
+                ];
+    }
+    const body = `${JSON.stringify(parsed, null, 2)}\n`;
+    const tmp = path.join(agentDir, `.models.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
+    await writeFile(tmp, body, { encoding: "utf8", mode: 0o600 });
+    const handle = await open(tmp, "r+");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await rename(tmp, file);
+    return readModelsConfig(agentDir);
+}
+const preferencesFile = (appData) => path.join(appData.chats, ".instruction-skill-preferences.json");
+export async function readSkillPreferences(appData) {
+    const value = await readJsonIfExists(preferencesFile(appData));
+    return (value?.disabledNames ?? []).filter((name) => OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS.includes(name));
+}
+export async function writeSkillPreferences(appData, disabledNames) {
+    const allowed = new Set(OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS);
+    if (disabledNames.some((name) => !allowed.has(name)))
+        throw Object.assign(new Error("preferences contain a non-allowed skill"), {
+            code: "INVALID_INPUT",
+            status: 400,
+        });
+    const normalized = [...new Set(disabledNames)].sort();
+    await writeSecureJson(preferencesFile(appData), {
+        schemaVersion: 1,
+        disabledNames: normalized,
+    });
+    return normalized;
+}
+export async function readPackageInventory(agentDir, repoRoot) {
+    const read = async (file) => {
+        try {
+            const parsed = JSON.parse(await readFile(file, "utf8"));
+            return (parsed.packages ?? []).filter((item) => typeof item === "string");
+        }
+        catch {
+            return [];
+        }
+    };
+    const global = await read(path.join(agentDir, "settings.json"));
+    const project = await read(path.join(repoRoot, ".pi", "settings.json"));
+    return [
+        ...global.map((spec) => ({
+            spec,
+            scope: "global",
+            enabled: true,
+            resourceCount: 0,
+        })),
+        ...project.map((spec) => ({
+            spec,
+            scope: "project",
+            enabled: true,
+            resourceCount: 0,
+        })),
+    ];
+}