@webpresso/agent-kit 3.1.28 → 3.2.0

package/dist/esm/cli/commands/run-wait.d.ts

@@ -0,0 +1,2 @@
+export declare const RUN_WAIT_HELP = "wp run wait \u2014 read-only GitHub workflow-run waiter (push/dispatch runs, e.g. production deploys on main)\n\nUsage:\n  wp run wait --run-id <id> [options]\n  wp run wait --sha <head-sha> [--workflow <file-or-name>] [options]\n\nSelector (exactly one required):\n  --run-id <id>           Watch a specific workflow run by database id\n  --sha <sha>             Watch the newest run for a head commit SHA\n  --workflow <file|name>  Filter --sha selection to one workflow\n\nOptions:\n  --until <target>        run-terminal (default) | all-jobs-terminal\n  --poll-interval-ms <n>  Poll interval (default 15000)\n  --timeout-ms <n>        Overall watch deadline (max 300000, default 120000)\n  --max-output-bytes <n>  Per-command output budget\n  --cwd <path>            Project root or descendant\n  --json                  Emit exactly one JSON document (default output)\n  -h, --help              Show this help\n\nRead-only: issues only `gh` GET calls; never mutates run state.";
+export declare function runRunWaitCommand(args: readonly string[]): Promise<number>;

package/dist/esm/cli/commands/run-wait.js

@@ -0,0 +1,122 @@
+import { RUN_WAIT_UNTIL_VALUES, runRunWait, } from "#mcp/tools/run-wait.js";
+// `wp run wait` is intercepted in cli.ts before the package-manager `run`
+// facade (which maps `wp run <script>` to `vp run <script>`). This module owns
+// only the `wait` subcommand and keeps arg parsing dependency-free so the
+// interception path stays cheap.
+export const RUN_WAIT_HELP = `wp run wait — read-only GitHub workflow-run waiter (push/dispatch runs, e.g. production deploys on main)
+
+Usage:
+  wp run wait --run-id <id> [options]
+  wp run wait --sha <head-sha> [--workflow <file-or-name>] [options]
+
+Selector (exactly one required):
+  --run-id <id>           Watch a specific workflow run by database id
+  --sha <sha>             Watch the newest run for a head commit SHA
+  --workflow <file|name>  Filter --sha selection to one workflow
+
+Options:
+  --until <target>        run-terminal (default) | all-jobs-terminal
+  --poll-interval-ms <n>  Poll interval (default 15000)
+  --timeout-ms <n>        Overall watch deadline (max 300000, default 120000)
+  --max-output-bytes <n>  Per-command output budget
+  --cwd <path>            Project root or descendant
+  --json                  Emit exactly one JSON document (default output)
+  -h, --help              Show this help
+
+Read-only: issues only \`gh\` GET calls; never mutates run state.`;
+function parsePositiveInteger(value, name) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return parsed;
+}
+function normalizeUntil(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.replaceAll("-", "_");
+    if (!RUN_WAIT_UNTIL_VALUES.includes(normalized)) {
+        throw new Error(`Unknown run wait target: ${value}`);
+    }
+    return normalized;
+}
+const VALUE_FLAGS = new Set([
+    "--run-id",
+    "--sha",
+    "--workflow",
+    "--until",
+    "--poll-interval-ms",
+    "--timeout-ms",
+    "--max-output-bytes",
+    "--cwd",
+]);
+function parseFlags(args) {
+    const values = {};
+    let help = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined)
+            continue;
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+            continue;
+        }
+        if (arg === "--json")
+            continue; // JSON is the only output shape
+        const eq = arg.indexOf("=");
+        if (eq !== -1 && arg.startsWith("--")) {
+            const key = arg.slice(0, eq);
+            if (VALUE_FLAGS.has(key)) {
+                values[key] = arg.slice(eq + 1);
+                continue;
+            }
+        }
+        if (VALUE_FLAGS.has(arg)) {
+            const next = args[index + 1];
+            if (next === undefined)
+                throw new Error(`${arg} requires a value`);
+            values[arg] = next;
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown run wait option: ${arg}`);
+    }
+    return { values, help };
+}
+export async function runRunWaitCommand(args) {
+    const { values, help } = parseFlags(args);
+    if (help) {
+        console.log(RUN_WAIT_HELP);
+        return 0;
+    }
+    const runId = values["--run-id"];
+    const input = {
+        sha: values["--sha"],
+        runId: runId === undefined ? undefined : runId,
+        workflow: values["--workflow"],
+        until: normalizeUntil(values["--until"]),
+        pollIntervalMs: parsePositiveInteger(values["--poll-interval-ms"], "--poll-interval-ms"),
+        timeoutMs: parsePositiveInteger(values["--timeout-ms"], "--timeout-ms"),
+        maxOutputBytes: parsePositiveInteger(values["--max-output-bytes"], "--max-output-bytes"),
+        cwd: values["--cwd"],
+    };
+    let payload;
+    try {
+        payload = await runRunWait(input);
+    }
+    catch (error) {
+        const issues = error.issues;
+        if (Array.isArray(issues)) {
+            const message = issues
+                .map((issue) => (typeof issue.message === "string" ? issue.message : String(issue.message)))
+                .join("; ");
+            console.error(`wp run wait: ${message}`);
+            return 1;
+        }
+        throw error;
+    }
+    console.log(JSON.stringify(payload, null, 2));
+    return payload.status === "success" ? 0 : 1;
+}

package/dist/esm/cli/commands/secrets.d.ts

@@ -2,6 +2,7 @@ import type { CAC } from "cac";
 import { spawnRuntimeCommandSync } from "#runtime/executor.js";
 export interface SecretsCommandOptions {
     readonly cwd?: string;
+    readonly commandCwd?: string;
     readonly profile?: string;
     readonly sink?: string;
     readonly json?: boolean;

package/dist/esm/cli/commands/secrets.js

@@ -14,6 +14,7 @@ export function registerSecretsCommand(cli) {
         .command("secrets <action> [target]", "Secret orchestration commands (doctor, bootstrap github)")
         .option("--profile <name>", "Secret profile name", { default: "preview" })
         .option("--sink <id>", "Secret sink id")
+        .option("--command-cwd <dir>", "Run the scoped command from this directory")
         .option("--json", "Emit machine-readable JSON")
         .option("--lane <lane>", "Lane to bootstrap (repeatable)", { default: [] })
         .option("--apply", "Apply GitHub bootstrap changes instead of dry-run planning")
@@ -22,6 +23,7 @@ export function registerSecretsCommand(cli) {
             cwd: process.cwd(),
             profile: flags.profile,
             sink: flags.sink,
+            commandCwd: flags.commandCwd,
             json: Boolean(flags.json),
             lanes: toArray(flags.lane),
             apply: Boolean(flags.apply),
@@ -109,7 +111,8 @@ export function runSecretsRun(options = {}, deps = {}) {
     const result = (deps.runSecretScopedCommand ?? spawnRuntimeCommandSync)({
         command,
         args,
-        cwd: options.cwd,
+        cwd: options.commandCwd ?? options.cwd,
+        envCwd: options.cwd,
         profile: plan.runtimeProfile,
         secretProfile: plan.profile,
         environment: plan.environment,

package/dist/esm/cli/commands/setup-help.js

@@ -8,7 +8,7 @@ export function getSetupHelpText(version) {
         "Options:",
         "  --with <skills>     Comma-separated opt-in skills and/or presets to install (non-interactive). Presets: example-skill, lore-commits, playwright-mcp, rtk, vision plus the special token `all`. Legacy compatibility presets are intentionally omitted; use wp install oh-my opencode when you want WP-owned refreshes. Opt-in skills are listed by 'wp skill list'. ",
         "  --without <skills>  Comma-separated opt-in skills and/or presets to opt out of for this run. ",
-        "  --host <hosts>      Comma-separated host targets: codex, claude, opencode, all, none ",
+        "  --host <hosts>      Comma-separated host targets: codex, claude, opencode, grok, all, none ",
         "  --dry-run           Show what would change without writing anything ",
         "  --cwd <dir>         Working tree to scaffold into (default: process.cwd()) ",
         "  -h, --help          Display this message ",

package/dist/esm/cli/commands/setup-repair-help.js

@@ -5,7 +5,7 @@
 const PRIMARY_SETUP_OPTIONS = [
     "  --with <skills>     Comma-separated opt-in skills and/or presets to install (non-interactive). Presets: example-skill, lore-commits, playwright-mcp, rtk, vision plus the special token `all`. Legacy compatibility presets are intentionally omitted; use wp install oh-my opencode when you want WP-owned refreshes. Opt-in skills are listed by 'wp skill list'. ",
     "  --without <skills>  Comma-separated opt-in skills and/or presets to opt out of for this run. ",
-    "  --host <hosts>      Comma-separated host targets: codex, claude, opencode, all, none ",
+    "  --host <hosts>      Comma-separated host targets: codex, claude, opencode, grok, all, none ",
     "  --prune             Widen stale agent-kit plugin-cache pruning from the default host set (claude, codex, opencode) to every supported host while retaining recent versions ",
     "  --dry-run           Show what would change without writing anything ",
     "  --cwd <dir>         Working tree to scaffold into (default: process.cwd()) ",

package/dist/esm/cli/commands/worktree/router-dispatch.js

@@ -5,6 +5,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { findGitRoot } from "#cli/commands/init/detect-consumer.js";
+import { removeCodexProjectTrust, removeCodexProjectTrusts, } from "#worktrees/codex-project-trust.js";
 import { shortId } from "#shared-utils/short-id.js";
 import { readConfig } from "#cli/commands/init/config";
 import { getProjectRoot } from "#cli/utils";
@@ -15,7 +16,7 @@ import { hydrateWorktreeDependencies, reconcileWorktreeDependencies, } from "#wo
 import { projectWorktreeAgentSurfaces } from "#worktrees/project-agent-surfaces.js";
 import { assertNotLocalMainBranch } from "#worktrees/main-ownership.js";
 import { buildWorktreeInventory, canonicalizeWorktreePath, classifyMembership, isManagedWorktreePath, resolveRepoIdentity, } from "#worktrees/identity.js";
-import { findRegistryCandidatesByPath, pruneStaleWorktreeRegistryEntries, readWorktreeRegistry, removeWorktreeRegistryEntries, repoScopedPathPredicate, upsertWorktreeRegistryEntry, } from "#worktrees/registry.js";
+import { findRegistryCandidatesByPath, planStaleWorktreeRegistryPrune, readWorktreeRegistry, removeWorktreeRegistryEntries, repoScopedPathPredicate, upsertWorktreeRegistryEntry, } from "#worktrees/registry.js";
 function parseDepsOption(value) {
     if (value === undefined || value === null || value === "")
         return undefined;
@@ -443,7 +444,7 @@ function handleRefresh(opts) {
     }
     console.log(`Refreshed ${updated} managed worktree entr${updated === 1 ? "y" : "ies"} for ${repoRoot}.`);
 }
-function handlePrune(opts) {
+async function handlePrune(opts) {
     if (!opts.all)
         throw new Error("Usage: wp worktree prune --all");
     // Repository-scoped, three-state prune: only THIS repo's entries that are
@@ -451,10 +452,12 @@ function handlePrune(opts) {
     // other-repo, and live-legacy entries are retained.
     const repoRoot = resolveWorktreeRepoRoot(opts.repo ?? opts.cwd ?? process.cwd());
     const inventory = buildWorktreeInventory(repoRoot);
-    const result = pruneStaleWorktreeRegistryEntries({
+    const result = planStaleWorktreeRegistryPrune({
         inventory,
         scope: { authoritativeRepoKey: resolveRepoIdentity(repoRoot) },
     });
+    await removeCodexProjectTrusts(result.removed.map((entry) => entry.path));
+    result.commit();
     console.log(`Pruned ${result.removed.length} stale managed registry entr${result.removed.length === 1 ? "y" : "ies"}.`);
     for (const warning of result.warnings)
         console.log(`warning: ${warning}`);
@@ -527,7 +530,7 @@ function handleRebind(args, opts) {
     console.log(`  worktree_owner_branch: ${binding.branch}`);
     console.log(`  path: ${binding.path}`);
 }
-function handleRemove(nameOrPath, opts) {
+async function handleRemove(nameOrPath, opts) {
     const cwd = opts.cwd ?? process.cwd();
     const callerRoot = resolveWorktreeRepoRoot(cwd);
     const entries = listEntries(callerRoot);
@@ -548,6 +551,7 @@ function handleRemove(nameOrPath, opts) {
     if (result.status !== 0) {
         throw new Error("git worktree remove failed");
     }
+    await removeCodexProjectTrust(resolved);
     removeWorktreeRegistryEntries(repoScopedPathPredicate(resolved, { authoritativeRepoKey: resolveRepoIdentity(repoRoot) }));
 }
 function isDirty(path) {
@@ -563,7 +567,7 @@ function currentBranch(repoRoot) {
     });
     return result.status === 0 ? String(result.stdout ?? "").trim() : "";
 }
-function handleMergeCleanup(nameOrPath, opts) {
+async function handleMergeCleanup(nameOrPath, opts) {
     const cwd = opts.cwd ?? process.cwd();
     const callerRoot = resolveWorktreeRepoRoot(cwd);
     const entries = listEntries(callerRoot);
@@ -628,6 +632,7 @@ function handleMergeCleanup(nameOrPath, opts) {
     if (removeResult.status !== 0) {
         throw new Error("git worktree remove failed");
     }
+    await removeCodexProjectTrust(resolved);
     removeWorktreeRegistryEntries(repoScopedPathPredicate(resolved, { authoritativeRepoKey: resolveRepoIdentity(repoRoot) }));
     const fetchResult = spawnSync("git", [...plan.fetchArgs], { cwd: repoRoot, stdio: "inherit" });
     if (fetchResult.status !== 0) {
@@ -665,7 +670,7 @@ export async function executeWorktreeSubcommand(subcommand, args, opts) {
             handleRefresh(opts);
             return;
         case "prune":
-            handlePrune(opts);
+            await handlePrune(opts);
             return;
         case "migrate":
             handleMigrate(opts);
@@ -682,7 +687,7 @@ export async function executeWorktreeSubcommand(subcommand, args, opts) {
             if (!nameOrPath) {
                 throw new Error("Usage: wp worktree remove <branch-or-path> [--force]");
             }
-            handleRemove(nameOrPath, opts);
+            await handleRemove(nameOrPath, opts);
             return;
         }
         case "merge-cleanup": {
@@ -690,7 +695,7 @@ export async function executeWorktreeSubcommand(subcommand, args, opts) {
             if (!nameOrPath) {
                 throw new Error("Usage: wp worktree merge-cleanup <branch-or-path> [--base <ref>] [--dry-run]");
             }
-            handleMergeCleanup(nameOrPath, opts);
+            await handleMergeCleanup(nameOrPath, opts);
             return;
         }
         default: {

package/dist/esm/cli/direct-provider-launch.js

@@ -11,6 +11,7 @@ import { canonicalizeWorktreePath } from "#worktrees/identity.js";
 import { dashProviderOwnershipName, parseDashPermissionMode, } from "#cli/commands/dash/provider-capabilities.js";
 import { optionalToolCanonicalCommand } from "#cli/optional-tools.js";
 import { commandExists } from "#runtime/command-exists.js";
+import { ensureCodexProjectMcpServers, ensureCodexWebpressoMcp, } from "#cli/commands/init/scaffolders/codex-mcp/index.js";
 export class DirectProviderLaunchPreparationError extends Error {
     action;
     constructor(message, action) {
@@ -78,8 +79,8 @@ function validateDirectProviderLaunch(provider, cwd) {
             ? `Run \`${installCommand}\` and retry.`
             : `Install ${ownershipName} and retry.`);
     }
-    // External PATH hosts (Grok) do not run optional-tool freshness — skip vp.
-    const vpCommand = resolveGlobalCapableVpCommand();
+    // External PATH hosts (Grok) do not run optional-tool freshness.
+    const vpCommand = adapter ? resolveGlobalCapableVpCommand() : null;
     if (adapter && !vpCommand) {
         throw new DirectProviderLaunchPreparationError("No global-capable Vite+ runner found.", "Reinstall @webpresso/agent-kit and retry.");
     }
@@ -90,6 +91,29 @@ function validateDirectProviderLaunch(provider, cwd) {
         vpCommand,
     };
 }
+function ensureCodexSessionTooling(repoRoot) {
+    const options = { dryRun: false, overwrite: false };
+    const webpresso = ensureCodexWebpressoMcp({ options });
+    if (webpresso.kind === "codex-webpresso-mcp-not-installed") {
+        throw new DirectProviderLaunchPreparationError(`Codex webpresso MCP is not configured because no usable agent-kit install root was found. Checked: ${webpresso.checked.join(", ") || "(none)"}`, "Run `wp setup --yes-global` from this repo, then retry `wp codex`.");
+    }
+    const project = ensureCodexProjectMcpServers({ repoRoot, options });
+    if (project.kind === "codex-project-mcp-invalid") {
+        throw new DirectProviderLaunchPreparationError(`Codex project MCP config is invalid: ${project.reason}`, "Fix .mcp.json or run `wp setup --yes-global` for detailed setup diagnostics.");
+    }
+    if (project.kind === "codex-project-mcp-unavailable") {
+        throw new DirectProviderLaunchPreparationError(`Codex project MCP server ${project.server} is unavailable: ${project.reason}`, "Run `wp setup --yes-global` from this repo to provision project MCP servers, then retry.");
+    }
+}
+const PROVIDER_SESSION_PREFLIGHTS = {
+    claude: () => undefined,
+    codex: ensureCodexSessionTooling,
+    grok: () => undefined,
+    opencode: () => undefined,
+};
+function ensureProviderSessionTooling(provider, cwd) {
+    PROVIDER_SESSION_PREFLIGHTS[provider](cwd);
+}
 export function isBareInteractiveProviderLaunch(args) {
     return parseDashPermissionMode(args).args.length === 0;
 }
@@ -136,14 +160,17 @@ export async function prepareDirectProviderLaunch(provider, args, cwd) {
         return { cwd, warnings: [] };
     }
     const { managedCwd, warnings } = await prepareLaunchEnvironment(provider, cwd);
-    if (managedCwd)
+    if (managedCwd) {
+        ensureProviderSessionTooling(provider, managedCwd);
         return { cwd: managedCwd, warnings };
+    }
     const created = await createManagedWorktree({
         cwd,
         prefix: provider,
         base: "origin/main",
         dependencyHydration: dependencyHydrationForProvider(provider),
     });
+    ensureProviderSessionTooling(provider, created.path);
     return { cwd: created.path, warnings };
 }
 /**
@@ -163,5 +190,6 @@ export function dependencyHydrationForProvider(provider) {
  */
 export async function prepareDirectProviderLaunchAt(provider, cwd) {
     const { warnings } = await prepareLaunchEnvironment(provider, cwd);
+    ensureProviderSessionTooling(provider, cwd);
     return { cwd, warnings };
 }

package/dist/esm/cli/optional-tool-freshness.d.ts

@@ -15,6 +15,16 @@ export interface OptionalToolFreshnessCache {
     readonly version: 1;
     readonly tools: Partial<Record<ManagedToolName, OptionalToolFreshnessRecord>>;
 }
+export interface OptionalToolRefreshLeaseRecord {
+    readonly pid: number | null;
+    readonly startedAt: number;
+    readonly heartbeatAt: number;
+    readonly expiresAt: number;
+}
+export interface OptionalToolRefreshLeaseCache {
+    readonly version: 1;
+    readonly tools: Partial<Record<ManagedToolName, OptionalToolRefreshLeaseRecord>>;
+}
 export type OptionalToolFreshnessMode = "force" | "if-needed";
 export type OptionalToolFreshnessResult = {
     readonly kind: "missing";
@@ -66,9 +76,22 @@ export interface OptionalToolFreshnessDeps {
     }) => SpawnSyncReturns<string>;
     readonly readCache?: () => OptionalToolFreshnessCache;
     readonly writeCache?: (cache: OptionalToolFreshnessCache) => void;
+    readonly readLeaseCache?: () => OptionalToolRefreshLeaseCache;
+    readonly writeLeaseCache?: (cache: OptionalToolRefreshLeaseCache) => void;
+    readonly clearLease?: (tool: ManagedToolName) => void;
+    readonly spawnDetached?: (command: string, args: readonly string[], options: {
+        readonly cwd: string;
+    }) => {
+        readonly pid?: number | undefined;
+        readonly unref?: () => void;
+    };
 }
 export declare function readOptionalToolFreshnessCache(path?: string): OptionalToolFreshnessCache;
 export declare function writeOptionalToolFreshnessCache(cache: OptionalToolFreshnessCache, path?: string): void;
+export declare function readOptionalToolRefreshLeaseCache(path?: string): OptionalToolRefreshLeaseCache;
+export declare function writeOptionalToolRefreshLeaseCache(cache: OptionalToolRefreshLeaseCache, path?: string): void;
+export declare function clearOptionalToolRefreshLease(tool: ManagedToolName, path?: string): void;
+export declare function optionalToolRefreshLeaseRecord(pid: number | null, now: number): OptionalToolRefreshLeaseRecord;
 export declare function supportsOptionalToolFreshness(adapter: OptionalToolAdapter): boolean;
 /**
  * Resolve a WP-managed optional-tool adapter for a dash provider.
@@ -78,4 +101,8 @@ export declare function tryResolveProviderToolAdapter(provider: DashProvider): O
 export declare function resolveProviderToolAdapter(provider: DashProvider): OptionalToolAdapter;
 export declare function refreshOptionalToolSync(input: OptionalToolFreshnessInput, deps?: OptionalToolFreshnessDeps): OptionalToolFreshnessResult;
 export declare function ensureOptionalToolFreshnessForLaunch(input: Omit<OptionalToolFreshnessInput, "mode">, deps?: OptionalToolFreshnessDeps): Promise<OptionalToolFreshnessResult>;
+export declare function runOptionalToolRefreshWorker(args: readonly string[], deps?: OptionalToolFreshnessDeps & {
+    readonly readOwnershipState?: () => ToolingOwnershipState;
+    readonly resolveVpCommand?: () => GlobalCapableVpCommandInput | null;
+}): number;
 export {};