agent-conveyor 0.1.19 → 0.1.21

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`,
+`conveyor-check-status`, and `conveyor-whats-next-nudger`.
+
 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
@@ -186,6 +204,9 @@ print `CONVEYOR POLL`, `CONVEYOR RECEIVED`, `WORK`, `CONVEYOR SEND`, and
 audit proof, not a replacement for the live session story. Idle polls may be a
 single `CONVEYOR IDLE` line.
 
+For bounded follow-up passes after the first worker result, use
+`Use the conveyor-whats-next-nudger skill`.
+
 Dispatch is core infrastructure for supervised worker/manager pairs. The
 `pair` workflow starts a detached Dispatch watch process by default so worker
 completion is routed to the bound manager mechanically. For manually bound

package/dist/cli/typescript-runtime.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);
@@ -6655,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,
@@ -6687,6 +6696,199 @@ 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",
+    "conveyor-whats-next-nudger",
+];
+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) {
@@ -15486,6 +15688,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"