@litfamily/litopencode 1.0.0

package/dist/cache-metrics.d.ts

@@ -0,0 +1,54 @@
+import type { Hooks } from "@opencode-ai/plugin";
+/**
+ * The host exposes provider usage only on the assistant message receipt. Keep this
+ * shape deliberately numeric: no prompt, transcript, provider id, or model id is
+ * needed to answer whether the receipt carried cache counters.
+ */
+export type ProviderUsageReceipt = {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly reasoningTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+};
+export type ProviderCacheMeasurement = {
+    readonly receiptEvents: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly reasoningTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+    /** Cache-read tokens divided by the full prompt footprint. */
+    readonly cacheReadShare: number | null;
+};
+export declare const emptyProviderCacheMeasurement: ProviderCacheMeasurement;
+/**
+ * Extract only the stable numeric receipt fields from OpenCode's
+ * `message.updated` assistant event. Step-finish parts carry a second copy of
+ * these counters, so they are intentionally not accepted here.
+ */
+export declare function providerUsageReceiptFromEvent(event: unknown): ProviderUsageReceipt | undefined;
+export declare function recordProviderUsageReceipt(measurement: ProviderCacheMeasurement, receipt: ProviderUsageReceipt): ProviderCacheMeasurement;
+export type ProviderUsageReceiptEventOptions = {
+    readonly onReceipt: (receipt: ProviderUsageReceipt) => void | Promise<void>;
+};
+/** A narrow event adapter that can be composed with other OpenCode event hooks. */
+export declare function createProviderUsageReceiptEventHook(options: ProviderUsageReceiptEventOptions): NonNullable<Hooks["event"]>;
+export type RuleDedupMetric = {
+    readonly selectedRuleCount: number;
+    readonly skippedAlreadyDeliveredCount: number;
+};
+export declare function ruleDedupMetric(selectedRuleCount: number, skippedAlreadyDeliveredCount: number): RuleDedupMetric;
+export type ActivationRegexMetric = {
+    readonly routeMatched: boolean;
+    readonly injectionAccepted: boolean;
+    readonly childSession: boolean;
+};
+export declare function activationRegexMetric(routeMatched: boolean, injectionAccepted: boolean, childSession: boolean): ActivationRegexMetric;
+export type UpdateCacheMetric = {
+    readonly cacheEntryPresent: boolean;
+    readonly latestVersionPresent: boolean;
+    readonly noticeShown: boolean;
+    readonly refreshEligible: boolean;
+};
+export declare function updateCacheMetric(cacheEntryPresent: boolean, latestVersionPresent: boolean, noticeShown: boolean, refreshEligible: boolean): UpdateCacheMetric;

package/dist/cache-metrics.js

@@ -0,0 +1,81 @@
+export const emptyProviderCacheMeasurement = Object.freeze({
+    receiptEvents: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    reasoningTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    cacheReadShare: null
+});
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonNegativeSafeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/**
+ * Extract only the stable numeric receipt fields from OpenCode's
+ * `message.updated` assistant event. Step-finish parts carry a second copy of
+ * these counters, so they are intentionally not accepted here.
+ */
+export function providerUsageReceiptFromEvent(event) {
+    if (!isRecord(event) || event.type !== "message.updated")
+        return undefined;
+    const properties = event.properties;
+    if (!isRecord(properties) || !isRecord(properties.info) || properties.info.role !== "assistant")
+        return undefined;
+    const tokens = properties.info.tokens;
+    if (!isRecord(tokens) || !isRecord(tokens.cache))
+        return undefined;
+    if (!nonNegativeSafeInteger(tokens.input) ||
+        !nonNegativeSafeInteger(tokens.output) ||
+        !nonNegativeSafeInteger(tokens.reasoning) ||
+        !nonNegativeSafeInteger(tokens.cache.read) ||
+        !nonNegativeSafeInteger(tokens.cache.write))
+        return undefined;
+    return Object.freeze({
+        inputTokens: tokens.input,
+        outputTokens: tokens.output,
+        reasoningTokens: tokens.reasoning,
+        cacheReadTokens: tokens.cache.read,
+        cacheWriteTokens: tokens.cache.write
+    });
+}
+export function recordProviderUsageReceipt(measurement, receipt) {
+    const inputTokens = measurement.inputTokens + receipt.inputTokens;
+    const cacheReadTokens = measurement.cacheReadTokens + receipt.cacheReadTokens;
+    const cacheWriteTokens = measurement.cacheWriteTokens + receipt.cacheWriteTokens;
+    const promptTokens = inputTokens + cacheReadTokens + cacheWriteTokens;
+    return Object.freeze({
+        receiptEvents: measurement.receiptEvents + 1,
+        inputTokens,
+        outputTokens: measurement.outputTokens + receipt.outputTokens,
+        reasoningTokens: measurement.reasoningTokens + receipt.reasoningTokens,
+        cacheReadTokens,
+        cacheWriteTokens,
+        cacheReadShare: Number.isSafeInteger(promptTokens) && promptTokens > 0
+            ? cacheReadTokens / promptTokens
+            : null
+    });
+}
+/** A narrow event adapter that can be composed with other OpenCode event hooks. */
+export function createProviderUsageReceiptEventHook(options) {
+    return async ({ event }) => {
+        const receipt = providerUsageReceiptFromEvent(event);
+        if (receipt !== undefined)
+            await options.onReceipt(receipt);
+    };
+}
+export function ruleDedupMetric(selectedRuleCount, skippedAlreadyDeliveredCount) {
+    const count = (value) => Number.isSafeInteger(value) && value >= 0 ? value : 0;
+    return Object.freeze({
+        selectedRuleCount: count(selectedRuleCount),
+        skippedAlreadyDeliveredCount: count(skippedAlreadyDeliveredCount)
+    });
+}
+export function activationRegexMetric(routeMatched, injectionAccepted, childSession) {
+    return Object.freeze({ routeMatched, injectionAccepted, childSession });
+}
+export function updateCacheMetric(cacheEntryPresent, latestVersionPresent, noticeShown, refreshEligible) {
+    return Object.freeze({ cacheEntryPresent, latestVersionPresent, noticeShown, refreshEligible });
+}

package/dist/cli/args.d.ts

@@ -0,0 +1,5 @@
+import type { ParsedArgs } from "./types.ts";
+export declare const loopCommands: readonly ["create-goals", "status", "record-evidence", "checkpoint", "steer", "complete-goals", "record-review-blockers", "record-observation", "list-observations"];
+export type LoopCommand = (typeof loopCommands)[number];
+export declare function isLoopCommand(command: string | undefined): command is LoopCommand;
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;

package/dist/cli/args.js

@@ -0,0 +1,415 @@
+import os from "node:os";
+import path from "node:path";
+import { resolveModelRoute } from "./model-catalog.js";
+export const loopCommands = [
+    "create-goals",
+    "status",
+    "record-evidence",
+    "checkpoint",
+    "steer",
+    "complete-goals",
+    "record-review-blockers",
+    "record-observation",
+    "list-observations"
+];
+export function isLoopCommand(command) {
+    return loopCommands.some((candidate) => candidate === command);
+}
+function defaultOpenCodeRoot() {
+    const configHome = process.env.XDG_CONFIG_HOME;
+    if (configHome && configHome.length > 0)
+        return path.join(configHome, "opencode");
+    return path.join(os.homedir(), ".config", "opencode");
+}
+export function parseArgs(argv) {
+    let command = argv[0];
+    let root = defaultOpenCodeRoot();
+    let dryRun = false;
+    let provider;
+    let model;
+    let effort;
+    let subagentModel;
+    let subagentEffort;
+    let yes = false;
+    let modelPrompt = "auto";
+    let permissionMode = "safe";
+    let permissionModeExplicit = false;
+    let permissionPrompt = "auto";
+    let fetchPublicUrl;
+    let fetchPublicJson = false;
+    let fetchPublicAllowPrivateNetwork = false;
+    let fetchPublicTimeoutMs;
+    let fetchPublicMaxBytes;
+    let projectRoot = process.cwd();
+    let loopJson = false;
+    let force = false;
+    let needsUserDecision = false;
+    let sessionId;
+    let objective;
+    let title;
+    const criteria = [];
+    let criterionId;
+    let kind;
+    let ref;
+    let detail;
+    let status;
+    let summary;
+    let directive;
+    let resolve;
+    let signal;
+    let skillId;
+    let observed;
+    let proposal;
+    if (command === "--help" || command === "-h") {
+        command = "help";
+    }
+    const loop = isLoopCommand(command);
+    const requireLoopValue = (arg, value) => {
+        if (!loop)
+            throw new Error(`Unknown argument: ${arg}`);
+        const cleaned = cleanOption(value, arg);
+        if (cleaned === undefined)
+            throw new Error(`${arg} requires a value`);
+        return cleaned;
+    };
+    const firstOptionIndex = command === "fetch-public" ? 2 : 1;
+    if (command === "fetch-public") {
+        fetchPublicUrl = cleanOption(argv[1], "fetch-public URL");
+        if (!fetchPublicUrl)
+            throw new Error("fetch-public requires a URL");
+    }
+    for (let index = firstOptionIndex; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--root" || arg === "--workdir") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error(`${arg} requires a value`);
+            root = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (arg === "--no-auto-update") {
+            continue;
+        }
+        if (arg === "--json") {
+            if (command === "fetch-public")
+                fetchPublicJson = true;
+            else if (loop)
+                loopJson = true;
+            else if (command !== "doctor")
+                throw new Error(`Unknown argument: ${arg}`);
+            continue;
+        }
+        if (arg === "--project") {
+            projectRoot = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--session-id") {
+            sessionId = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--objective") {
+            objective = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--title") {
+            title = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--criterion") {
+            criteria.push(requireLoopValue(arg, argv[index + 1]));
+            index += 1;
+            continue;
+        }
+        if (arg === "--criterion-id") {
+            criterionId = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--kind") {
+            kind = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--ref") {
+            ref = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--detail") {
+            detail = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--status") {
+            status = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--summary") {
+            summary = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--directive") {
+            directive = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--resolve") {
+            resolve = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--signal") {
+            signal = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--skill-id") {
+            skillId = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--observed") {
+            observed = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--proposal") {
+            proposal = requireLoopValue(arg, argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === "--force") {
+            if (!loop)
+                throw new Error(`Unknown argument: ${arg}`);
+            force = true;
+            continue;
+        }
+        if (arg === "--needs-user-decision") {
+            if (!loop)
+                throw new Error(`Unknown argument: ${arg}`);
+            needsUserDecision = true;
+            continue;
+        }
+        if (arg === "--allow-private-network") {
+            if (command !== "fetch-public")
+                throw new Error(`Unknown argument: ${arg}`);
+            fetchPublicAllowPrivateNetwork = true;
+            continue;
+        }
+        if (arg === "--timeout") {
+            if (command !== "fetch-public")
+                throw new Error(`Unknown argument: ${arg}`);
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error("--timeout requires a value");
+            fetchPublicTimeoutMs = parsePositiveInteger(value, "--timeout");
+            index += 1;
+            continue;
+        }
+        if (arg === "--max-bytes") {
+            if (command !== "fetch-public")
+                throw new Error(`Unknown argument: ${arg}`);
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error("--max-bytes requires a value");
+            fetchPublicMaxBytes = parsePositiveInteger(value, "--max-bytes");
+            index += 1;
+            continue;
+        }
+        if (arg === "--provider") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error("--provider requires a value");
+            provider = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--model") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error("--model requires a value");
+            model = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--effort") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error("--effort requires a value");
+            effort = parseModelEffort(value, "--effort");
+            index += 1;
+            continue;
+        }
+        if (arg === "--subagent-model") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error("--subagent-model requires a value");
+            subagentModel = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--subagent-effort") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error("--subagent-effort requires a value");
+            subagentEffort = parseModelEffort(value, "--subagent-effort");
+            index += 1;
+            continue;
+        }
+        if (arg === "--yes") {
+            yes = true;
+            continue;
+        }
+        if (arg === "--model-prompt" || arg === "--select-model") {
+            modelPrompt = "always";
+            continue;
+        }
+        if (arg === "--no-model-prompt") {
+            modelPrompt = "never";
+            continue;
+        }
+        if (arg === "--permission-prompt" || arg === "--select-permissions") {
+            permissionPrompt = "always";
+            continue;
+        }
+        if (arg === "--no-permission-prompt") {
+            permissionPrompt = "never";
+            continue;
+        }
+        if (arg === "--permission-mode") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error("--permission-mode requires a value");
+            permissionMode = parsePermissionMode(value, "--permission-mode");
+            permissionModeExplicit = true;
+            permissionPrompt = "never";
+            index += 1;
+            continue;
+        }
+        if (arg === "--yolo") {
+            permissionMode = "yolo";
+            permissionModeExplicit = true;
+            permissionPrompt = "never";
+            continue;
+        }
+        if (arg === "--help" || arg === "-h") {
+            command = "help";
+            continue;
+        }
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+    return {
+        command,
+        root,
+        fetchPublicUrl,
+        fetchPublicJson,
+        fetchPublicAllowPrivateNetwork,
+        fetchPublicTimeoutMs,
+        fetchPublicMaxBytes,
+        dryRun,
+        permissionMode,
+        permissionModeExplicit,
+        permissionPrompt: yes ? "never" : permissionPrompt,
+        modelSelection: resolveModelSelection(provider, model, effort, subagentModel, subagentEffort),
+        modelPrompt: yes ? "never" : modelPrompt,
+        outputStylePrompt: yes ? "never" : "auto",
+        loop: {
+            projectRoot,
+            json: loopJson,
+            force,
+            needsUserDecision,
+            sessionId,
+            objective,
+            title,
+            criteria: Object.freeze([...criteria]),
+            criterionId,
+            kind,
+            ref,
+            detail,
+            status,
+            summary,
+            directive,
+            resolve,
+            signal,
+            skillId,
+            observed,
+            proposal
+        }
+    };
+}
+function parsePositiveInteger(value, optionName) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0)
+        throw new Error(optionName + " requires a positive integer");
+    return parsed;
+}
+function parsePermissionMode(value, optionName) {
+    const cleaned = cleanOption(value, optionName);
+    if (cleaned === "safe" || cleaned === "balanced" || cleaned === "yolo")
+        return cleaned;
+    throw new Error(optionName + " must be one of safe, balanced, yolo");
+}
+function parseModelEffort(value, optionName) {
+    const cleaned = cleanOption(value, optionName);
+    if (cleaned === "low" || cleaned === "medium" || cleaned === "high" || cleaned === "xhigh" || cleaned === "max")
+        return cleaned;
+    throw new Error(optionName + " must be one of low, medium, high, xhigh, max");
+}
+function cleanOption(value, optionName) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        throw new Error(optionName + " requires a non-empty value");
+    return trimmed;
+}
+function resolveModelSelection(providerValue, modelValue, effort, subagentModelValue, subagentEffort) {
+    const provider = cleanOption(providerValue, "--provider");
+    const model = cleanOption(modelValue, "--model");
+    const subagentModel = cleanOption(subagentModelValue, "--subagent-model");
+    if (provider === undefined && model === undefined) {
+        if (effort !== undefined)
+            throw new Error("--effort requires --model");
+        if (subagentModel !== undefined || subagentEffort !== undefined)
+            throw new Error("--subagent-model requires --model");
+        return undefined;
+    }
+    if (provider !== undefined && model === undefined)
+        throw new Error("--provider requires --model");
+    if (model === undefined)
+        return undefined;
+    const slashIndex = model.indexOf("/");
+    let lead;
+    if (provider === undefined) {
+        if (slashIndex <= 0 || slashIndex === model.length - 1) {
+            throw new Error("--model requires --provider unless the value is provider/model");
+        }
+        lead = resolveModelRoute(model.slice(0, slashIndex), model.slice(slashIndex + 1), effort, "--model");
+    }
+    else {
+        if (slashIndex >= 0)
+            throw new Error("Use --model <model> with --provider, or pass --model provider/model without --provider");
+        lead = resolveModelRoute(provider, model, effort, "--model");
+    }
+    if (subagentModel === undefined) {
+        if (subagentEffort !== undefined)
+            throw new Error("--subagent-effort requires --subagent-model");
+        return lead;
+    }
+    const helperSlash = subagentModel.indexOf("/");
+    const helper = helperSlash > 0 && helperSlash < subagentModel.length - 1
+        ? resolveModelRoute(subagentModel.slice(0, helperSlash), subagentModel.slice(helperSlash + 1), subagentEffort, "--subagent-model")
+        : resolveModelRoute(lead.provider, subagentModel, subagentEffort, "--subagent-model");
+    return { ...lead, helper };
+}

package/dist/cli/auto-update.d.ts

@@ -0,0 +1,117 @@
+export declare const autoUpdatePackageName = "@litfamily/litopencode";
+export declare const autoUpdateTimeoutMs = 30000;
+/** npm install, staged install, and post-install doctor each have this bound. */
+export declare const autoUpdateTransactionBoundMs: number;
+export declare const autoUpdateLockTimeoutMs = 2000;
+/** Keep a live owner protected for the whole bounded transaction plus one command window. */
+export declare const autoUpdateInstallLockStaleMs: number;
+export declare const autoUpdateRecursionEnv = "LITOPENCODE_AUTO_UPDATE_IN_PROGRESS";
+type CommandOutput = {
+    readonly stdout?: string;
+    readonly stderr?: string;
+};
+export type AutoUpdateReason = "plugin" | "management";
+export type InteractiveAutoUpdateGate = {
+    readonly argv: readonly string[];
+    readonly exitCode: number;
+    readonly env: NodeJS.ProcessEnv;
+    readonly stdinIsTTY: boolean | undefined;
+    readonly stdoutIsTTY: boolean | undefined;
+    readonly stderrIsTTY: boolean | undefined;
+    readonly configRoot?: string;
+};
+export type AutoUpdateRunResult = {
+    readonly status: "updated" | "rolled-back" | "skipped" | "failed";
+    readonly reason?: string;
+    readonly currentVersion?: string;
+    readonly targetVersion?: string;
+    readonly spec?: string;
+    readonly receiptPath?: string;
+    readonly backupPath?: string;
+    readonly priorStateVerified?: boolean;
+    readonly stagedStateKnown?: boolean;
+    readonly rollback?: {
+        readonly ok: boolean;
+        readonly error?: string;
+    };
+};
+export type AutoUpdateCommandOptions = {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly timeout: number;
+    readonly maxBuffer: number;
+};
+export type AutoUpdateOptions = {
+    readonly reason: AutoUpdateReason;
+    readonly homeDir?: string;
+    readonly configRoot: string;
+    readonly currentVersion: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly argv?: readonly string[];
+    readonly fetchLatestVersion?: () => Promise<string>;
+    readonly runCommand?: (command: string, args: readonly string[], options: AutoUpdateCommandOptions) => Promise<CommandOutput>;
+};
+type DoctorReceipt = {
+    readonly ok: boolean;
+    readonly exitCode?: number;
+    readonly package?: {
+        readonly name?: string;
+        readonly version?: string;
+    };
+    readonly error?: string;
+};
+type AutoUpdateReceipt = {
+    readonly schemaVersion: 1;
+    readonly status: AutoUpdateRunResult["status"];
+    readonly reason: AutoUpdateReason;
+    readonly currentVersion: string;
+    readonly targetVersion: string;
+    readonly spec: string;
+    readonly configRoot: string;
+    readonly startedAt: number;
+    readonly finishedAt: number;
+    readonly journalPath: string;
+    readonly backupPath: string;
+    readonly backupRetained: boolean;
+    readonly priorStateVerified: boolean;
+    readonly stagedStateKnown: boolean;
+    readonly doctor: DoctorReceipt;
+    readonly rollback: {
+        readonly ok: boolean;
+        readonly error?: string;
+    };
+};
+export declare function autoUpdateInstallLockPath(homeDir?: string): string;
+export declare function autoUpdateJournalPath(homeDir?: string): string;
+export declare function autoUpdateReceiptPath(homeDir?: string): string;
+export declare function isAutoUpdateDisabled(env?: NodeJS.ProcessEnv, argv?: readonly string[]): boolean;
+export declare function shouldRunInteractiveAutoUpdate(input: InteractiveAutoUpdateGate): boolean;
+/**
+ * Keep npm child processes deliberately boring. In particular, npm config files,
+ * tokens, proxy credentials, and arbitrary `npm_config_*` values are not inherited.
+ */
+export declare function sanitizedNpmEnvironment(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function runAutoUpdate(options: AutoUpdateOptions): Promise<AutoUpdateRunResult>;
+/**
+ * A failed transaction is safe to leave in place only when the old managed
+ * state was restored and verified. Unknown child state or an unverified
+ * rollback must stop the host from claiming a successful install.
+ */
+export declare function canContinueAfterAutoUpdate(result: AutoUpdateRunResult): boolean;
+export declare function autoUpdateDiagnostic(result: AutoUpdateRunResult): string;
+export type AutoUpdateReceiptSummary = {
+    readonly status: AutoUpdateReceipt["status"];
+    readonly backupPath: string;
+    readonly backupRetained: boolean;
+    readonly priorStateVerified: boolean;
+    readonly stagedStateKnown: boolean;
+    readonly rollbackOk: boolean;
+    readonly finishedAt: number;
+};
+/** Read only the bounded safety summary used by doctor; never echo command output. */
+export declare function readAutoUpdateReceipt(homeDir?: string): Promise<AutoUpdateReceiptSummary | {
+    readonly status: "unreadable";
+} | undefined>;
+export declare function runPluginAutoUpdate(): Promise<AutoUpdateRunResult>;
+export declare function runInteractiveAutoUpdate(input: InteractiveAutoUpdateGate): Promise<AutoUpdateRunResult>;
+export {};