@unblocklabs/unblock-codex-prompt 0.1.0

package/dist/catalog.js

@@ -0,0 +1,185 @@
+import { join, resolve } from "node:path";
+import { parseTOML, getStaticTOMLValue } from "toml-eslint-parser";
+import { readOptional, replaceFile, sha256, withLock } from "./manager.js";
+import { readPromptPointer, setPromptPointer } from "./toml.js";
+export const CATALOG_REFRESH_MS = 24 * 60 * 60 * 1000;
+const KEY = "model_catalog_json";
+function record(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function files(agentDir) {
+    const home = join(resolve(agentDir), "codex-home");
+    return { home, config: join(home, "config.toml"), catalog: join(home, "unblock-codex-models.json"), receipt: join(home, ".unblock-codex-catalog.json") };
+}
+function parseReceipt(source) {
+    if (source === null)
+        return null;
+    const value = JSON.parse(source);
+    if (!record(value) || value.schema !== 1 || typeof value.active !== "boolean" ||
+        (value.previousPointer !== null && typeof value.previousPointer !== "string") ||
+        typeof value.refreshedAt !== "number" || !Number.isFinite(value.refreshedAt) ||
+        typeof value.sha256 !== "string" || typeof value.sourceSha256 !== "string" || typeof value.modelCount !== "number") {
+        throw new Error("Invalid catalog receipt");
+    }
+    return { schema: 1, active: value.active, previousPointer: value.previousPointer, refreshedAt: value.refreshedAt,
+        sha256: value.sha256, sourceSha256: value.sourceSha256, modelCount: value.modelCount };
+}
+export function patchCatalog(value) {
+    if (!record(value) || !Array.isArray(value.models) || value.models.length === 0)
+        throw new Error("Upstream response is not a full Codex model catalog");
+    const seen = new Set();
+    const models = value.models.map((model) => {
+        if (!record(model) || typeof model.slug !== "string" || !model.slug || seen.has(model.slug) ||
+            typeof model.base_instructions !== "string" || !Array.isArray(model.supported_reasoning_levels)) {
+            throw new Error("Invalid or duplicate Codex model metadata");
+        }
+        seen.add(model.slug);
+        const messages = model.model_messages ?? {};
+        if (!record(messages))
+            throw new Error("Invalid model_messages");
+        const multi = messages.multi_agent ?? {};
+        if (!record(multi))
+            throw new Error("Invalid multi_agent metadata");
+        const mode = multi.mode ?? {};
+        if (!record(mode))
+            throw new Error("Invalid multi_agent mode metadata");
+        return { ...model, model_messages: { ...messages, multi_agent: { ...multi, mode: { ...mode, explicit: "" } } } };
+    });
+    return { ...value, models };
+}
+/** Use the configured provider, not the override file or its refreshable cache. */
+export async function fetchUpstreamCatalog(agentDir, configText, request = fetch) {
+    let config;
+    try {
+        config = getStaticTOMLValue(parseTOML(configText));
+    }
+    catch {
+        throw new Error("Invalid Codex TOML");
+    }
+    if (!record(config) || typeof config.model_provider !== "string" || !record(config.model_providers))
+        throw new Error("Catalog refresh requires an explicit Codex provider");
+    const provider = config.model_providers[config.model_provider];
+    if (!record(provider) || typeof provider.base_url !== "string" || typeof provider.env_key !== "string") {
+        throw new Error("Catalog refresh requires a provider base_url and existing env_key credential");
+    }
+    // Never resolve arbitrary auth commands, copy credentials, or fall back to another endpoint.
+    const token = process.env[provider.env_key];
+    if (!token)
+        throw new Error("Configured catalog provider credential is unavailable in the plugin environment");
+    const url = new URL(provider.base_url.replace(/\/$/u, "") + "/models");
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.hash || url.search)
+        throw new Error("Unsupported catalog provider URL");
+    const cached = JSON.parse(await readOptional(join(files(agentDir).home, "models_cache.json")) ?? "null");
+    if (!record(cached) || typeof cached.client_version !== "string" || !/^\d+\.\d+\.\d+$/u.test(cached.client_version))
+        throw new Error("Managed Codex client version missing from its model cache");
+    url.searchParams.set("client_version", cached.client_version);
+    let response;
+    try {
+        response = await request(url, { headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+            redirect: "error", signal: AbortSignal.timeout(15_000) });
+    }
+    catch {
+        throw new Error("Catalog request failed; installed catalog retained");
+    }
+    if (!response.ok || !response.body)
+        throw new Error(`Catalog endpoint returned HTTP ${response.status}`);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 8 * 1024 * 1024)
+                throw new Error("Catalog response exceeds 8 MiB");
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel();
+        reader.releaseLock();
+    }
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)));
+    }
+    catch {
+        throw new Error("Catalog endpoint returned invalid JSON");
+    }
+}
+export async function catalogStatus(agentDir) {
+    const path = files(agentDir);
+    const receipt = parseReceipt(await readOptional(path.receipt));
+    const text = await readOptional(path.catalog);
+    return { enabled: receipt?.active === true, catalogPath: path.catalog, pointerMatches: readPromptPointer(await readOptional(path.config) ?? "", KEY) === path.catalog,
+        contentMatches: receipt !== null && text !== null && sha256(text) === receipt.sha256,
+        refreshedAt: receipt?.refreshedAt ?? null, nextRefreshAt: receipt ? receipt.refreshedAt + CATALOG_REFRESH_MS : null, modelCount: receipt?.modelCount ?? 0 };
+}
+export async function refreshCatalog(agentDir, options = {}) {
+    return withLock({ agentDir, prompt: "" }, async () => {
+        const path = files(agentDir);
+        const config = await readOptional(path.config) ?? "";
+        const previousReceipt = await readOptional(path.receipt);
+        const receipt = parseReceipt(previousReceipt);
+        const enrollment = JSON.parse(await readOptional(join(path.home, ".unblock-codex-prompt.json")) ?? "null");
+        if (!record(enrollment) || enrollment.active !== true || (options.automatic && receipt?.active === false))
+            return { skipped: true, changed: false };
+        const pointer = readPromptPointer(config, KEY);
+        if (pointer !== null && pointer !== path.catalog)
+            throw new Error("A different model_catalog_json is configured; refusing to replace it");
+        const previous = await readOptional(path.catalog);
+        if (!receipt && (previous !== null || pointer === path.catalog))
+            throw new Error("Unowned model catalog exists; recover its receipt first");
+        // Deliberate edits to this generated file are overwritten from upstream; never reuse it as source.
+        const upstream = await (options.fetchCatalog ?? fetchUpstreamCatalog)(agentDir, config);
+        const patched = patchCatalog(upstream);
+        const contents = `${JSON.stringify(patched, null, 2)}\n`;
+        const next = { schema: 1, active: true, previousPointer: receipt?.active ? receipt.previousPointer : pointer,
+            refreshedAt: options.now ?? Date.now(), sha256: sha256(contents), sourceSha256: sha256(JSON.stringify(upstream)), modelCount: patched.models.length };
+        await replaceFile(path.receipt, previousReceipt, `${JSON.stringify(next, null, 2)}\n`);
+        const catalogChanged = await replaceFile(path.catalog, previous, contents);
+        const configChanged = await replaceFile(path.config, config, setPromptPointer(config, path.catalog, KEY));
+        // The pinned managed Codex reloads catalog contents for fresh sessions. A new
+        // config pointer still requires activation; existing conversations are not reset.
+        return { changed: catalogChanged || configChanged, catalogChanged, configChanged, modelCount: next.modelCount, refreshedAt: next.refreshedAt, sha256: next.sha256, restartRequired: configChanged, newSessionRequired: catalogChanged || configChanged };
+    });
+}
+export async function restoreCatalog(agentDir) {
+    return withLock({ agentDir, prompt: "" }, async () => {
+        const path = files(agentDir);
+        const source = await readOptional(path.receipt);
+        const receipt = parseReceipt(source);
+        if (!receipt)
+            return;
+        const config = await readOptional(path.config) ?? "";
+        const pointer = readPromptPointer(config, KEY);
+        if (pointer !== path.catalog && pointer !== receipt.previousPointer)
+            throw new Error("Foreign catalog pointer; refusing restore");
+        await replaceFile(path.receipt, source, `${JSON.stringify({ ...receipt, active: false }, null, 2)}\n`);
+        await replaceFile(path.config, config, setPromptPointer(config, receipt.previousPointer, KEY));
+    });
+}
+/** Start promptly if overdue, persist successful refresh time, retry failures hourly. */
+export function startCatalogRefresh(run, nextAt, onError) {
+    let stopped = false;
+    let timer;
+    let pending;
+    const schedule = (delay) => {
+        timer = setTimeout(() => {
+            pending = (async () => {
+                let next = CATALOG_REFRESH_MS;
+                try {
+                    await run();
+                }
+                catch {
+                    onError();
+                    next = 60 * 60 * 1000;
+                }
+                if (!stopped)
+                    schedule(next);
+            })();
+        }, Math.max(0, delay));
+        timer.unref();
+    };
+    schedule(nextAt - Date.now());
+    return async () => { stopped = true; clearTimeout(timer); await pending; };
+}

package/dist/compiler.d.ts

@@ -0,0 +1,23 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/plugin-entry";
+export declare const SUPPORTED_OPENCLAW = "2026.9.2";
+export declare function openclawRoot(): Promise<string>;
+export declare function buildSkillsCatalog(config: OpenClawConfig, agentId: string, workspaceDir: string): Promise<{
+    prompt: string;
+    count: number;
+}>;
+export declare function compilePrompt(base: string, policy: string, workspaceDir: string, catalog: {
+    prompt: string;
+    count: number;
+}): Promise<{
+    prompt: string;
+    bundle: {
+        schema: 1;
+        policy: string;
+        sources: {
+            name: string;
+            sha256: string | null;
+        }[];
+        skillCount: number;
+        basePromptLength: number;
+    };
+}>;

package/dist/compiler.js

@@ -0,0 +1,57 @@
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { readOptional, sha256 } from "./manager.js";
+export const SUPPORTED_OPENCLAW = "2026.9.2";
+export async function openclawRoot() {
+    let directory = dirname(fileURLToPath(import.meta.resolve("openclaw/plugin-sdk/agent-runtime")));
+    for (;;) {
+        const source = await readOptional(join(directory, "package.json"));
+        if (source) {
+            const pkg = JSON.parse(source);
+            if (pkg && typeof pkg === "object" && "name" in pkg && pkg.name === "openclaw") {
+                if (!("version" in pkg) || pkg.version !== SUPPORTED_OPENCLAW)
+                    throw new Error(`Frozen bridge supports OpenClaw ${SUPPORTED_OPENCLAW} only; review upgrades before syncing`);
+                return directory;
+            }
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            throw new Error("Cannot locate the running OpenClaw package");
+        directory = parent;
+    }
+}
+// OpenClaw has no public catalog-building SDK. Pin this single internal export,
+// retaining its eligibility, agent allowlist, prompt visibility and size limits.
+export async function buildSkillsCatalog(config, agentId, workspaceDir) {
+    const dist = join(await openclawRoot(), "dist");
+    const names = (await readdir(dist)).filter(name => /^workspace-skill-prompt-[\w-]+\.js$/u.test(name));
+    if (names.length !== 1)
+        throw new Error("Unsupported OpenClaw skills module layout");
+    const path = join(dist, names[0]);
+    const source = await readFile(path, "utf8");
+    if (!source.includes("buildSkillSnapshot as t"))
+        throw new Error("Unsupported OpenClaw skills export");
+    const module = await import(pathToFileURL(path).href);
+    if (typeof module.t !== "function")
+        throw new Error("Missing OpenClaw skill snapshot builder");
+    const result = module.t(workspaceDir, { config, agentId });
+    if (!result || typeof result !== "object" || !("prompt" in result) || typeof result.prompt !== "string" ||
+        !("resolvedSkills" in result) || !Array.isArray(result.resolvedSkills))
+        throw new Error("Unsupported OpenClaw skill snapshot result");
+    return { prompt: result.prompt, count: result.resolvedSkills.length };
+}
+export async function compilePrompt(base, policy, workspaceDir, catalog) {
+    const sources = [];
+    const sections = [base.trim(), "## Frozen agent context\nThis context is a local snapshot, refreshed explicitly by the operator. Native AGENTS.md, native skills, actual tool schemas and current session context remain separate. This snapshot does not grant tools or permissions."];
+    for (const name of ["SOUL.md", "IDENTITY.md", "USER.md"]) {
+        const content = await readOptional(join(workspaceDir, name));
+        sources.push({ name, sha256: content === null ? null : sha256(content) });
+        if (content?.trim())
+            sections.push(`### ${name}\n${content.trim()}`);
+    }
+    sections.push(`## Frozen memory reference\nWhen prior context matters, use the currently available memory tools and follow their schemas. If retrieval is unavailable, say so; do not invent results. The workspace memory reference is ${join(workspaceDir, "MEMORY.md")}. Its contents are not included here. Read it only when the active session's privacy policy permits; do not expose private memory in group or customer conversations.`);
+    sources.push({ name: "OpenClaw skills catalog", sha256: sha256(catalog.prompt) });
+    sections.push(`## Frozen OpenClaw skills catalog\nThis is the approved agent-workspace catalog at sync time, not a promise that credentials or tools remain available. Session-local skill selection and execution-directory skill discovery do not refresh this snapshot. Use the native catalog separately.\n\n${catalog.prompt.trim() || "No eligible model-visible OpenClaw skills at sync time."}`);
+    return { prompt: `${sections.join("\n\n")}\n`, bundle: { schema: 1, policy: policy.trim(), sources, skillCount: catalog.count, basePromptLength: base.trim().length } };
+}

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export declare const PLUGIN_ID = "unblock-codex-prompt";
+export declare function parseConfig(raw: unknown): {
+    agentId: string;
+    agentName: string | undefined;
+    frozenContext: boolean;
+    promptUrl: string | undefined;
+    suppressExplicitDelegationPrompt: boolean;
+};
+export declare function validatePromptUrl(value: string): URL;
+export declare function renderPrompt(template: string, agentName?: string): string;

package/dist/config.js

@@ -0,0 +1,48 @@
+export const PLUGIN_ID = "unblock-codex-prompt";
+export function parseConfig(raw) {
+    const value = raw ?? {};
+    if (typeof value !== "object" || Array.isArray(value))
+        throw new Error("Plugin config must be an object");
+    for (const key of Object.keys(value)) {
+        if (key !== "agentId" && key !== "agentName" && key !== "frozenContext" && key !== "promptUrl" && key !== "suppressExplicitDelegationPrompt")
+            throw new Error(`Unknown plugin option: ${key}`);
+    }
+    const agentId = "agentId" in value ? value.agentId : "main";
+    const agentName = "agentName" in value ? value.agentName : undefined;
+    if (typeof agentId !== "string" || !/^[a-z0-9][a-z0-9_-]*$/u.test(agentId)) {
+        throw new Error("agentId must be a lowercase OpenClaw agent ID");
+    }
+    if (agentName !== undefined && (typeof agentName !== "string" || !agentName.trim() ||
+        agentName.length > 100 || /\p{C}/u.test(agentName))) {
+        throw new Error("agentName must be 1–100 characters without control characters");
+    }
+    const frozenContext = "frozenContext" in value ? value.frozenContext : false;
+    if (typeof frozenContext !== "boolean")
+        throw new Error("frozenContext must be boolean");
+    const promptUrl = "promptUrl" in value ? value.promptUrl : undefined;
+    if (promptUrl !== undefined) {
+        if (typeof promptUrl !== "string")
+            throw new Error("promptUrl must be an HTTPS URL");
+        validatePromptUrl(promptUrl);
+        if (!frozenContext)
+            throw new Error("promptUrl requires frozenContext to replace the OpenClaw policy too");
+    }
+    const suppressExplicitDelegationPrompt = "suppressExplicitDelegationPrompt" in value ? value.suppressExplicitDelegationPrompt : false;
+    if (typeof suppressExplicitDelegationPrompt !== "boolean")
+        throw new Error("suppressExplicitDelegationPrompt must be boolean");
+    if (suppressExplicitDelegationPrompt && !frozenContext)
+        throw new Error("suppressExplicitDelegationPrompt requires frozenContext");
+    return { agentId, agentName: agentName?.trim(), frozenContext, promptUrl, suppressExplicitDelegationPrompt };
+}
+export function validatePromptUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== "https:" || url.username || url.password || url.hash) {
+        throw new Error("promptUrl must use HTTPS without credentials or a fragment");
+    }
+    return url;
+}
+export function renderPrompt(template, agentName) {
+    if (template.split("{{identity}}").length !== 2)
+        throw new Error("Prompt template must contain exactly one identity placeholder");
+    return template.replace("{{identity}}", () => agentName ? `${agentName}, an OpenClaw agent` : "an OpenClaw agent");
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+declare const _default: Omit<{
+    id: string;
+    name: string;
+    description: string;
+    kind?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["kind"];
+    configSchema?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema | (() => import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema);
+    reload?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["reload"];
+    nodeHostCommands?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["nodeHostCommands"];
+    securityAuditCollectors?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["securityAuditCollectors"];
+    register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
+}, "configSchema"> & {
+    configSchema: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,153 @@
+import { readFile } from "node:fs/promises";
+import { listAgentIds, resolveAgentDir, resolveAgentWorkspaceDir } from "openclaw/plugin-sdk/agent-runtime";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { parseConfig, PLUGIN_ID, renderPrompt } from "./config.js";
+import { promptStatus, restorePrompt, syncPrompt, refreshSharedPrompt } from "./manager.js";
+import { adapterStatus, installAdapter, prepareAdapter, restoreAdapter } from "./adapter.js";
+import { buildSkillsCatalog, compilePrompt } from "./compiler.js";
+import { readFrozenPolicy } from "./runtime.js";
+import { fetchPrompt, REMOTE_POLICY } from "./remote.js";
+import { readOptional } from "./manager.js";
+import { join } from "node:path";
+import { CATALOG_REFRESH_MS, catalogStatus, refreshCatalog, restoreCatalog, startCatalogRefresh } from "./catalog.js";
+async function refresh(target, automatic = false) {
+    const failures = [];
+    let catalog;
+    let prompt;
+    // Attempt both independently, sequentially because they share the enrollment lock.
+    if (target.settings.suppressExplicitDelegationPrompt) {
+        try {
+            catalog = await refreshCatalog(target.agentDir, { automatic });
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    if (target.settings.promptUrl) {
+        const url = target.settings.promptUrl;
+        try {
+            prompt = await refreshSharedPrompt(target.agentDir, () => fetchPrompt(url));
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    if (failures.length)
+        throw new AggregateError(failures, "Refresh incomplete; failed components retain their installed data");
+    return { catalog, prompt };
+}
+async function resolveTarget(config) {
+    const settings = parseConfig(config.plugins?.entries?.[PLUGIN_ID]?.config);
+    if (!listAgentIds(config).includes(settings.agentId))
+        throw new Error(`Unknown OpenClaw agent: ${settings.agentId}`);
+    const codexConfig = config.plugins?.entries?.codex?.config;
+    const appServer = codexConfig?.appServer;
+    if (appServer !== undefined) {
+        if (!appServer || typeof appServer !== "object" || Array.isArray(appServer))
+            throw new Error("Invalid Codex appServer config");
+        if (("transport" in appServer && appServer.transport !== "stdio") ||
+            ("homeScope" in appServer && appServer.homeScope !== "agent") ||
+            ("command" in appServer && appServer.command !== undefined)) {
+            throw new Error("Only OpenClaw-managed, agent-scoped local stdio Codex is supported");
+        }
+        if ("args" in appServer && appServer.args !== undefined) {
+            throw new Error("Custom Codex appServer.args may override the prompt; remove them or manage the prompt outside this plugin");
+        }
+    }
+    return { agentDir: resolveAgentDir(config, settings.agentId), settings, workspaceDir: resolveAgentWorkspaceDir(config, settings.agentId) };
+}
+async function bundledPrompt(agentName) {
+    return renderPrompt(await readFile(new URL("../prompts/system.md", import.meta.url), "utf8"), agentName);
+}
+async function status(config) {
+    const target = await resolveTarget(config);
+    const disk = await promptStatus({ ...target, prompt: target.settings.frozenContext ? "" : await bundledPrompt(target.settings.agentName) });
+    if (!target.settings.frozenContext)
+        return disk;
+    const adapter = await adapterStatus(target.agentDir);
+    let ready = false;
+    let error;
+    try {
+        ready = readFrozenPolicy(target.agentDir) !== null;
+    }
+    catch (cause) {
+        error = cause instanceof Error ? cause.message : "Invalid frozen state";
+    }
+    // A frozen snapshot intentionally differs from today's template/documents.
+    const { promptMatches: _matches, expectedSha256: _expected, ...frozenDisk } = disk;
+    const bundle = await readOptional(join(target.agentDir, "codex-home", ".unblock-codex-prompt-bundle.json"));
+    const receipt = bundle ? JSON.parse(bundle) : null;
+    const remotePrompt = receipt && typeof receipt === "object" && "remotePrompt" in receipt ? receipt.remotePrompt : null;
+    return { ...frozenDisk, frozen: true, ready: ready && adapter.installed, adapter, error, configuredPromptUrl: target.settings.promptUrl, remotePrompt };
+}
+export default definePluginEntry({
+    id: PLUGIN_ID,
+    name: "Unblock Codex Prompt",
+    description: "Explicitly compile a frozen Codex prompt with a narrow, version-pinned OpenClaw bridge.",
+    register(api) {
+        let stopCatalogRefresh;
+        // Registration/import stays read-only, including plugin inspection and CLI discovery.
+        api.registerService({
+            id: PLUGIN_ID,
+            reload: { configPrefixes: [`plugins.entries.${PLUGIN_ID}.config`] },
+            async start(ctx) {
+                const result = await status(ctx.config);
+                ctx.logger.info(`${PLUGIN_ID}: ${JSON.stringify(result)}`);
+                const target = await resolveTarget(ctx.config);
+                if ((target.settings.suppressExplicitDelegationPrompt || target.settings.promptUrl) && result.enrolled) {
+                    const catalog = await catalogStatus(target.agentDir);
+                    const remote = "remotePrompt" in result ? result.remotePrompt : null;
+                    const checkedAt = remote && typeof remote === "object" && "checkedAt" in remote && typeof remote.checkedAt === "number" ? remote.checkedAt : 0;
+                    const nextAt = Math.min(target.settings.suppressExplicitDelegationPrompt ? catalog.nextRefreshAt ?? 0 : Infinity, target.settings.promptUrl ? checkedAt ? checkedAt + CATALOG_REFRESH_MS : 0 : Infinity);
+                    stopCatalogRefresh = startCatalogRefresh(async () => {
+                        const refreshed = await refresh(target, true);
+                        ctx.logger.info(`${PLUGIN_ID}: daily refresh ${JSON.stringify(refreshed)}`);
+                    }, nextAt, () => ctx.logger.error(`${PLUGIN_ID}: daily refresh incomplete; failed components retain installed data, retrying in one hour`));
+                    ctx.logger.info(`${PLUGIN_ID}: daily prompt/catalog refresh scheduled`);
+                }
+            },
+            async stop() { await stopCatalogRefresh?.(); stopCatalogRefresh = undefined; },
+        });
+        api.registerCli(({ program, config }) => {
+            const root = program.command("codex-prompt").description("Manage this agent's Codex base prompt (JSON output)");
+            root.command("status").description("Inspect disk state without writing or claiming live adoption")
+                .action(async () => {
+                const target = await resolveTarget(config);
+                console.log(JSON.stringify({ ...await status(config), catalog: await catalogStatus(target.agentDir) }, null, 2));
+            });
+            root.command("refresh-catalog").description("Fetch fresh provider metadata and repair the managed delegation-policy catalog")
+                .action(async () => {
+                const target = await resolveTarget(config);
+                if (!target.settings.suppressExplicitDelegationPrompt)
+                    throw new Error("Enable suppressExplicitDelegationPrompt before refreshing the catalog");
+                console.log(JSON.stringify(await refreshCatalog(target.agentDir), null, 2));
+            });
+            root.command("refresh").description("Refresh remote prompt and enabled catalog without rereading frozen agent context")
+                .action(async () => console.log(JSON.stringify(await refresh(await resolveTarget(config)), null, 2)));
+            const sync = root.command("sync").description("Explicitly refresh the prompt snapshot and install the reviewed adapter")
+                .option("--adopt", "Take ownership of an existing custom prompt pointer")
+                .option("--codex-plugin-dir <path>", "Verified official Codex package directory (required on first frozen sync)");
+            sync.action(async () => {
+                const target = await resolveTarget(config);
+                const options = sync.opts();
+                const plan = target.settings.frozenContext ? await prepareAdapter(target.agentDir, target.settings.agentId, options.codexPluginDir) : null;
+                const remote = target.settings.promptUrl ? await fetchPrompt(target.settings.promptUrl) : null;
+                const prompt = remote?.prompt ?? await bundledPrompt(target.settings.agentName);
+                const compiled = target.settings.frozenContext ? await compilePrompt(prompt, remote ? REMOTE_POLICY : await readFile(new URL("../prompts/developer.md", import.meta.url), "utf8"), target.workspaceDir, await buildSkillsCatalog(config, target.settings.agentId, target.workspaceDir)) : null;
+                if (compiled && remote)
+                    Object.assign(compiled.bundle, { remotePrompt: { ...remote.source, checkedAt: Date.now() } });
+                const result = await syncPrompt({ ...target, prompt, ...compiled }, { adopt: options.adopt === true });
+                const adapter = plan ? await installAdapter(target.agentDir, plan) : undefined;
+                const catalog = target.settings.suppressExplicitDelegationPrompt ? await refreshCatalog(target.agentDir) : undefined;
+                console.log(JSON.stringify({ ...result, adapter, skillCount: compiled?.bundle.skillCount, remotePrompt: remote?.source, catalog }, null, 2));
+            });
+            root.command("restore").description("Restore the original pointer; pause automatic management and retain files")
+                .action(async () => {
+                const target = await resolveTarget(config);
+                await restoreCatalog(target.agentDir);
+                await restoreAdapter(target.agentDir);
+                console.log(JSON.stringify(await restorePrompt({ ...target, prompt: "" }), null, 2));
+            });
+        }, { descriptors: [{ name: "codex-prompt", description: "Manage an agent-scoped Codex base prompt", hasSubcommands: true }] });
+    },
+});

package/dist/manager.d.ts

@@ -0,0 +1,80 @@
+export type FrozenBundle = {
+    schema: 1;
+    policy: string;
+    sources: {
+        name: string;
+        sha256: string | null;
+    }[];
+    skillCount: number;
+    basePromptLength?: number;
+    remotePrompt?: {
+        url: string;
+        revision: string;
+        checkedAt?: number;
+    };
+};
+export declare const FROZEN_CONTEXT_HEADER = "\n\n## Frozen agent context\n";
+export type PromptTarget = {
+    agentDir: string;
+    prompt: string;
+    bundle?: FrozenBundle;
+};
+export declare function readOptional(path: string): Promise<string | null>;
+export declare function sha256(text: string): string;
+/** Disk state only: this cannot attest to instructions retained by a live Codex thread. */
+export declare function promptStatus(target: PromptTarget): Promise<{
+    enrolled: boolean;
+    restored: boolean;
+    configPath: string;
+    promptPath: string;
+    pointerMatches: boolean;
+    promptMatches: boolean;
+    expectedSha256: string;
+    actualSha256: string | null;
+    runtimeVerified: boolean;
+}>;
+export declare function replaceFile(path: string, previous: string | null, contents: string): Promise<boolean>;
+export declare function withLock<T>(target: PromptTarget, operation: () => Promise<T>): Promise<T>;
+export declare function syncPrompt(target: PromptTarget, options?: {
+    adopt?: boolean;
+    automatic?: boolean;
+}): Promise<{
+    changed: boolean;
+    restored: boolean;
+    promptChanged?: never;
+    configChanged?: never;
+    sha256?: never;
+    activation?: never;
+} | {
+    changed: boolean;
+    promptChanged: boolean;
+    configChanged: boolean;
+    sha256: string;
+    activation: string;
+    restored?: never;
+}>;
+export declare function restorePrompt(target: PromptTarget): Promise<{
+    changed: boolean;
+    restored: boolean;
+    retainedPromptPath: string;
+}>;
+/** Replace only the shared prefix; never reread workspace documents or skills. */
+export declare function refreshSharedPrompt(agentDir: string, fetchBase: () => Promise<{
+    prompt: string;
+    source: {
+        url: string;
+        revision: string;
+    };
+}>, now?: number): Promise<{
+    changed: boolean;
+    skipped: boolean;
+    revision?: never;
+    checkedAt?: never;
+    newSessionRequired?: never;
+} | {
+    changed: boolean;
+    revision: string;
+    checkedAt: number;
+    newSessionRequired: boolean;
+    skipped?: never;
+}>;