agent-conveyor 0.1.18 → 0.1.20

package/README.md

@@ -154,18 +154,36 @@ The GitHub Pages version lives at
 Use `node scripts/check-landing-page.mjs` for a docs-only desktop/mobile
 screenshot gate; this does not run the full package release smoke.
 
+### Codex Operator Plugin
+
+Agent Conveyor also ships Codex-app-only operator scaffolding for visible
+manager/worker sessions from any project. Install the package, then install
+and inspect the plugin:
+
+```bash
+npm install -g agent-conveyor
+conveyor install-plugin
+conveyor plugin-status
+```
+
+The per-project default ledger for operator sessions is
+`.codex-workers/workerctl.db`. The initial included skills are
+`conveyor-create-pair`, `conveyor-create-worker-set`, and
+`conveyor-check-status`.
+
 After install, the intended Codex app entry point is natural language. Open a
 new Codex app session in the target repo and say:
 
 ```text
-Use the manage-codex-workers skill.
+Use the conveyor-create-pair skill.
 
 Set up a Codex app Ralph loop for issue CTL.
 Require adversarial proof before another worker iteration.
 ```
 
-The installed skill should call the `conveyor` CLI, choose names, create the
-no-tmux binding with `create-disposable-binding`, point the worker at
+For multiple workers, start with `Use the conveyor-create-worker-set skill`.
+The installed plugin skill should call the `conveyor` CLI, choose names, create
+the no-tmux binding with `create-disposable-binding`, point the worker at
 `worker-inbox`, and use `loop-status` plus telemetry receipts before reporting
 that the loop is ready. When the manager is itself running in the Codex app and
 thread tools are available, the skill should first call `create_thread` for a

package/dist/cli/typescript-runtime.d.ts

@@ -25,6 +25,15 @@ interface SpawnedCodexSessionDiscoveryOptions {
 }
 type TypescriptRuntimeOptions = {
     args: readonly string[];
+    campaignReadbackBeforeVerify?: (context: {
+        databasePath: string;
+        readback: {
+            assignment?: string;
+            campaign: string;
+            channel?: string;
+            slot?: string;
+        };
+    }) => void;
     codexCommandResolver?: (name: string) => string | null;
     cwd?: string;
     discoverSpawnedCodexSession?: (options: SpawnedCodexSessionDiscoveryOptions) => SpawnedCodexSessionDiscovery;

package/dist/cli/typescript-runtime.js

@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 import { taskAuditSync } from "../runtime/audit.js";
 import { appAutopilotPlanSync, appLoopStatusSync, appWakeupDispatchPlanSync, appWakeupPlanSync, directInboxPollCommand, visibleSessionProtocolLines, } from "../runtime/app-autonomy.js";
 import { classifyBusyWait, classifyStartupOutput } from "../runtime/classify.js";
-import { addCampaignWorkerSlotSync, campaignDashboardSync, campaignStatusSync, createCampaignAssignmentSync, createCampaignSync, recordCampaignAssetReceiptSync, updateCampaignWorkerSlotLifecycleSync, upsertCampaignChannelBriefSync, } from "../runtime/campaigns.js";
+import { addCampaignWorkerSlotSync, campaignDashboardSync, campaignSetupReadbackProofSync, campaignStatusSync, createCampaignAssignmentSync, createCampaignSync, recordCampaignAssetReceiptSync, updateCampaignWorkerSlotLifecycleSync, upsertCampaignChannelBriefSync, } from "../runtime/campaigns.js";
 import { exportTaskSync } from "../runtime/export.js";
 import { ingestSessionSync } from "../runtime/ingest.js";
 import { acceptanceCriteriaForTaskSync, loopEvidenceCriterion, recordAdversarialLoopEvidenceSync, recordLoopEvidenceSync, recordVisualDiffLoopEvidenceSync, } from "../runtime/loop-evidence.js";
@@ -171,6 +171,15 @@ export function runTypescriptRuntimeCommand(options) {
         if (parsed.command === "install-skills") {
             return runInstallSkillsCommand(parsed, options);
         }
+        if (parsed.command === "plugin-path") {
+            return runPluginPathCommand(parsed, options);
+        }
+        if (parsed.command === "plugin-status") {
+            return runPluginStatusCommand(parsed, options);
+        }
+        if (parsed.command === "install-plugin") {
+            return runInstallPluginCommand(parsed, options);
+        }
         if (parsed.command === "bind") {
             return runBindCommand(parsed, options);
         }
@@ -1086,7 +1095,7 @@ function parseRuntimeArgs(args, env) {
             index += 1;
         }
         else if (arg === "--codex-home") {
-            if (command !== "install-skills") {
+            if (command !== "install-skills" && command !== "install-plugin" && command !== "plugin-status" && command !== "plugin-path") {
                 return { command, enabled, error: "Unsupported TypeScript runtime option: --codex-home", explicit, flags, task };
             }
             const value = valueAfter(queue, index, arg);
@@ -6096,12 +6105,16 @@ function runCampaignCommand(parsed, options) {
                 name: campaign,
                 objective,
             });
+            const readback = campaignSetupReadbackProofFromConfiguredDatabase(parsed, options, {
+                campaign: campaignId,
+            });
             return campaignResult(parsed, {
                 action,
                 campaign,
                 campaign_id: campaignId,
                 created: true,
-            }, [`campaign ${campaign} created ${campaignId}`]);
+                ledger_readback: readback,
+            }, [`campaign ${campaign} created ${campaignId}`, campaignLedgerReadbackText(readback)]);
         }
         if (action === "add-slot") {
             const slotKey = requiredStringFlag(parsed.flags.slotKey, "--slot-key");
@@ -6119,13 +6132,18 @@ function runCampaignCommand(parsed, options) {
                 slotKey,
                 ...(state ? { state } : {}),
             });
+            const readback = campaignSetupReadbackProofFromConfiguredDatabase(parsed, options, {
+                campaign,
+                slot: slotId,
+            });
             return campaignResult(parsed, {
                 action,
                 campaign,
                 created: true,
+                ledger_readback: readback,
                 slot_id: slotId,
                 slot_key: slotKey,
-            }, [`campaign ${campaign} slot ${slotKey} created ${slotId}`]);
+            }, [`campaign ${campaign} slot ${slotKey} created ${slotId}`, campaignLedgerReadbackText(readback)]);
         }
         if (action === "attach-slot") {
             const slot = requiredStringFlag(parsed.flags.slot, "--slot");
@@ -6194,13 +6212,18 @@ function runCampaignCommand(parsed, options) {
                 campaign,
                 channel,
             });
+            const readback = campaignSetupReadbackProofFromConfiguredDatabase(parsed, options, {
+                campaign,
+                channel,
+            });
             return campaignResult(parsed, {
                 action,
                 brief_id: briefId,
                 campaign,
                 channel,
+                ledger_readback: readback,
                 upserted: true,
-            }, [`campaign ${campaign} brief ${channel} upserted ${briefId}`]);
+            }, [`campaign ${campaign} brief ${channel} upserted ${briefId}`, campaignLedgerReadbackText(readback)]);
         }
         if (action === "assign") {
             const slot = requiredStringFlag(parsed.flags.slot, "--slot");
@@ -6216,13 +6239,19 @@ function runCampaignCommand(parsed, options) {
                 title,
                 ...(status ? { status } : {}),
             });
+            const readback = campaignSetupReadbackProofFromConfiguredDatabase(parsed, options, {
+                assignment: assignmentId,
+                campaign,
+                slot,
+            });
             return campaignResult(parsed, {
                 action,
                 assignment_id: assignmentId,
                 campaign,
                 created: true,
+                ledger_readback: readback,
                 slot_id: slot,
-            }, [`campaign ${campaign} assignment created ${assignmentId}`]);
+            }, [`campaign ${campaign} assignment created ${assignmentId}`, campaignLedgerReadbackText(readback)]);
         }
         if (action === "asset") {
             const slot = requiredStringFlag(parsed.flags.slot, "--slot");
@@ -6276,6 +6305,25 @@ function runCampaignCommand(parsed, options) {
 function campaignActionsUsage() {
     return CAMPAIGN_ACTION_NAMES.join("|");
 }
+function campaignSetupReadbackProofFromConfiguredDatabase(parsed, options, readbackOptions) {
+    const databasePath = runtimeDbPath(parsed, options);
+    options.campaignReadbackBeforeVerify?.({ databasePath, readback: readbackOptions });
+    const database = openDatabaseSync(databasePath);
+    initializeDatabaseSync(database);
+    try {
+        return campaignSetupReadbackProofSync(database, readbackOptions);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`campaign ledger readback failed after setup write: ${message}`, { cause: error });
+    }
+    finally {
+        database.close();
+    }
+}
+function campaignLedgerReadbackText(proof) {
+    return `ledger_readback ok campaign=${proof.campaign_id} checks=${proof.checks.map((check) => check.entity).join(",")}`;
+}
 function unsupportedCampaignActionMessage(action) {
     return `Unsupported campaign action: ${action ?? "<missing>"}; expected one of: ${CAMPAIGN_ACTION_NAMES.join(", ")}. Use \`conveyor campaign dashboard --name <campaign> --json\` to list assets and receipt counts.`;
 }
@@ -6616,7 +6664,7 @@ function runInstallSkillsCommand(parsed, options) {
     if (unsupported) {
         return unsupportedRuntimeResult(parsed, unsupported);
     }
-    const codexHome = resolve(expandUserPath(parsed.flags.codexHome ?? options.env?.CODEX_HOME ?? join(homedir(), ".codex")));
+    const codexHome = resolveCodexHome(parsed, options);
     const skills = installableSkillSources();
     const targets = skills.map((skill) => ({
         name: skill.name,
@@ -6648,6 +6696,194 @@ function runInstallSkillsCommand(parsed, options) {
     const lines = targets.map((target) => `${parsed.flags.dryRun ? "would install" : "installed"} ${target.name} skill in ${target.target}`);
     return { exitCode: 0, handled: true, stdout: `${lines.join("\n")}\n` };
 }
+const AGENT_CONVEYOR_PLUGIN_NAME = "agent-conveyor";
+const AGENT_CONVEYOR_PLUGIN_SKILLS = ["conveyor-create-pair", "conveyor-create-worker-set", "conveyor-check-status"];
+function resolveCodexHome(parsed, options) {
+    return resolve(expandUserPath(parsed.flags.codexHome ?? options.env?.CODEX_HOME ?? join(homedir(), ".codex")));
+}
+function packageVersionFromRoot(packageRoot) {
+    const packageJsonPath = join(packageRoot, "package.json");
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    if (!isPlainRecord(parsed) || typeof parsed.version !== "string" || parsed.version.length === 0) {
+        throw new Error(`Package version not found in ${packageJsonPath}.`);
+    }
+    return parsed.version;
+}
+function pluginPaths(parsed, options) {
+    const codexHome = resolveCodexHome(parsed, options);
+    const packageRoot = packageRootFromRuntimeModule();
+    const packageVersion = packageVersionFromRoot(packageRoot);
+    const pluginCacheRoot = join(codexHome, "plugins", "cache", AGENT_CONVEYOR_PLUGIN_NAME, AGENT_CONVEYOR_PLUGIN_NAME);
+    return {
+        codex_home: codexHome,
+        package_root: packageRoot,
+        plugin_cache_root: pluginCacheRoot,
+        plugin_install_root: join(pluginCacheRoot, packageVersion),
+        plugin_source: join(packageRoot, "plugin", AGENT_CONVEYOR_PLUGIN_NAME),
+        skills_install_root: join(codexHome, "skills"),
+    };
+}
+function readAgentConveyorPluginManifest(source) {
+    const manifestPath = join(source, "plugin.json");
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+    if (!isPlainRecord(parsed)) {
+        throw new Error(`Agent Conveyor plugin manifest must be a JSON object: ${manifestPath}`);
+    }
+    if (parsed.name !== AGENT_CONVEYOR_PLUGIN_NAME) {
+        throw new Error(`Agent Conveyor plugin manifest name must be "${AGENT_CONVEYOR_PLUGIN_NAME}": ${manifestPath}`);
+    }
+    if (typeof parsed.version !== "string") {
+        throw new Error(`Agent Conveyor plugin manifest is missing a string version: ${manifestPath}`);
+    }
+    return {
+        name: parsed.name,
+        version: parsed.version,
+        skills: Array.isArray(parsed.skills) ? parsed.skills.filter((skill) => typeof skill === "string") : undefined,
+    };
+}
+function assertPluginVersionMatchesPackage(manifest, packageVersion) {
+    if (manifest.version !== packageVersion) {
+        throw new Error(`Agent Conveyor plugin version ${manifest.version} does not match package version ${packageVersion}.`);
+    }
+}
+function pluginSkillTargets(paths) {
+    return AGENT_CONVEYOR_PLUGIN_SKILLS.map((name) => {
+        const target = join(paths.skills_install_root, name);
+        return {
+            installed: existsSync(join(target, "SKILL.md")),
+            name,
+            source: join(paths.plugin_source, "skills", name),
+            target,
+        };
+    });
+}
+function installedAgentConveyorPluginManifest(paths) {
+    const manifestPath = join(paths.plugin_install_root, "plugin.json");
+    if (!existsSync(manifestPath)) {
+        return null;
+    }
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+    if (!isPlainRecord(parsed) || parsed.name !== AGENT_CONVEYOR_PLUGIN_NAME || typeof parsed.version !== "string") {
+        return null;
+    }
+    return {
+        name: parsed.name,
+        version: parsed.version,
+        skills: Array.isArray(parsed.skills) ? parsed.skills.filter((skill) => typeof skill === "string") : undefined,
+    };
+}
+function agentConveyorPluginStatus(parsed, options) {
+    const paths = pluginPaths(parsed, options);
+    const packageVersion = packageVersionFromRoot(paths.package_root);
+    const manifest = readAgentConveyorPluginManifest(paths.plugin_source);
+    const installedManifest = installedAgentConveyorPluginManifest(paths);
+    const installedVersion = installedManifest?.version ?? null;
+    const skills = pluginSkillTargets(paths);
+    const installed = installedManifest !== null && skills.every((skill) => skill.installed);
+    return {
+        installed,
+        installed_version: installedVersion,
+        package_version: packageVersion,
+        paths,
+        plugin_version: manifest.version,
+        skills,
+        version_matches: installed && installedVersion === packageVersion && manifest.version === packageVersion,
+    };
+}
+function unsupportedPluginOptions(parsed) {
+    if (parsed.task !== null) {
+        return `Unexpected argument: ${parsed.task}`;
+    }
+    return null;
+}
+function runPluginPathCommand(parsed, options) {
+    const unsupported = unsupportedPluginOptions(parsed);
+    if (unsupported) {
+        return unsupportedRuntimeResult(parsed, unsupported);
+    }
+    const paths = pluginPaths(parsed, options);
+    if (parsed.flags.json) {
+        return jsonResult(paths);
+    }
+    return {
+        exitCode: 0,
+        handled: true,
+        stdout: [
+            `codex_home: ${paths.codex_home}`,
+            `package_root: ${paths.package_root}`,
+            `plugin_cache_root: ${paths.plugin_cache_root}`,
+            `plugin_install_root: ${paths.plugin_install_root}`,
+            `plugin_source: ${paths.plugin_source}`,
+            `skills_install_root: ${paths.skills_install_root}`,
+            "",
+        ].join("\n"),
+    };
+}
+function runPluginStatusCommand(parsed, options) {
+    const unsupported = unsupportedPluginOptions(parsed);
+    if (unsupported) {
+        return unsupportedRuntimeResult(parsed, unsupported);
+    }
+    const status = agentConveyorPluginStatus(parsed, options);
+    if (parsed.flags.json) {
+        return jsonResult(status);
+    }
+    const skillLines = status.skills.map((skill) => `skill ${skill.name}: ${skill.installed ? "installed" : "missing"}`);
+    return {
+        exitCode: 0,
+        handled: true,
+        stdout: [
+            `installed: ${status.installed}`,
+            `installed_version: ${status.installed_version ?? "none"}`,
+            `package_version: ${status.package_version}`,
+            `plugin_version: ${status.plugin_version}`,
+            `version_matches: ${status.version_matches}`,
+            ...skillLines,
+            "",
+        ].join("\n"),
+    };
+}
+function runInstallPluginCommand(parsed, options) {
+    const unsupported = unsupportedPluginOptions(parsed);
+    if (unsupported) {
+        return unsupportedRuntimeResult(parsed, unsupported);
+    }
+    const paths = pluginPaths(parsed, options);
+    const packageVersion = packageVersionFromRoot(paths.package_root);
+    const manifest = readAgentConveyorPluginManifest(paths.plugin_source);
+    assertPluginVersionMatchesPackage(manifest, packageVersion);
+    const skillTargets = pluginSkillTargets(paths);
+    for (const target of skillTargets) {
+        if (!existsSync(join(target.source, "SKILL.md"))) {
+            throw new Error(`Agent Conveyor plugin skill not found: ${target.source}`);
+        }
+    }
+    if (!parsed.flags.dryRun) {
+        rmSync(paths.plugin_install_root, { force: true, recursive: true });
+        mkdirSync(dirname(paths.plugin_install_root), { recursive: true });
+        cpSync(paths.plugin_source, paths.plugin_install_root, { recursive: true });
+        for (const target of skillTargets) {
+            rmSync(target.target, { force: true, recursive: true });
+            mkdirSync(dirname(target.target), { recursive: true });
+            cpSync(target.source, target.target, { recursive: true });
+        }
+    }
+    const status = agentConveyorPluginStatus(parsed, options);
+    const payload = {
+        ...status,
+        dry_run: parsed.flags.dryRun,
+        installed: status.installed,
+        installed_skills: parsed.flags.dryRun ? [] : skillTargets.map((target) => target.name),
+    };
+    if (parsed.flags.json) {
+        return jsonResult(payload);
+    }
+    const lines = [
+        `${parsed.flags.dryRun ? "would install" : "installed"} ${AGENT_CONVEYOR_PLUGIN_NAME} plugin in ${paths.plugin_install_root}`,
+        ...skillTargets.map((target) => `${parsed.flags.dryRun ? "would install" : "installed"} ${target.name} skill in ${target.target}`),
+    ];
+    return { exitCode: 0, handled: true, stdout: `${lines.join("\n")}\n` };
+}
 function dashboardLaunchPayload(parsed) {
     const queryParams = new URLSearchParams();
     if (parsed.flags.taskName) {
@@ -15447,6 +15683,9 @@ function isDefaultRuntimeCommand(command) {
         || command === "start-test"
         || command === "dashboard"
         || command === "install-skills"
+        || command === "install-plugin"
+        || command === "plugin-status"
+        || command === "plugin-path"
         || command === "replay"
         || command === "export-task"
         || command === "tasks"