@bivy/bivy 0.6.0 → 0.7.0-staging.95

package/dist/runtime/credential-store.js

@@ -34,6 +34,37 @@ function isStoredCredential(value) {
 function providerId(id) {
     return String(id ?? "").trim().toLowerCase();
 }
+/**
+ * Should an `incoming` credential replace the `local` one during a non-destructive
+ * `importAll` merge? Pure and exported so the convergence rule is unit-testable
+ * without a vault. Rules:
+ *  - No local entry → take the incoming one.
+ *  - Only OAuth-vs-OAuth needs freshness arbitration (an api-key set/replace, or a
+ *    type switch, keeps the existing "incoming wins on a real content change").
+ *  - A snapshot that omits the refresh token must never clobber a usable one —
+ *    rotated refresh tokens are single-use, so an incoming with a blank refresh is
+ *    strictly worse than a local one that still has it.
+ *  - Prefer the token minted LATER by `refreshedAt` (monotonic mint order) when
+ *    both carry it; otherwise fall back to the access-token `expires`. In both
+ *    cases a tie KEEPS the local credential (strictly-greater wins), so an equal
+ *    stamp can't needlessly churn/rotate the vault, and clock skew can't let an
+ *    equal-`expires` stale token win.
+ */
+export function preferIncomingCredential(local, incoming) {
+    if (!local)
+        return true;
+    if (local.type !== "oauth" || incoming.type !== "oauth")
+        return true;
+    const localRefresh = String(local.refresh ?? "").trim();
+    const incomingRefresh = String(incoming.refresh ?? "").trim();
+    if (!incomingRefresh && localRefresh)
+        return false;
+    const lt = Number(local.refreshedAt);
+    const it = Number(incoming.refreshedAt);
+    if (Number.isFinite(lt) && Number.isFinite(it))
+        return it > lt;
+    return (Number(incoming.expires) || 0) > (Number(local.expires) || 0);
+}
 /**
  * Encrypted, cross-process-locked credential vault backed by `<vaultDir>/auth.enc`.
  *
@@ -202,12 +233,10 @@ export class BivyCredentialStore {
                 if (!id || !isStoredCredential(incoming))
                     continue;
                 const local = vault[id];
-                if (incoming.type === "oauth" && local?.type === "oauth") {
-                    const localExpires = Number(local.expires) || 0;
-                    const incomingExpires = Number(incoming.expires) || 0;
-                    if (localExpires > incomingExpires)
-                        continue;
-                }
+                // Freshest-wins, rotation-safe (see preferIncomingCredential): a lagging
+                // or refresh-less snapshot must not overwrite a fresher local login.
+                if (!preferIncomingCredential(local, incoming))
+                    continue;
                 if (!(id in vault))
                     imported += 1;
                 // Only mark dirty on a real content change, so a snapshot that merely

package/dist/runtime/index.js

@@ -40,6 +40,21 @@ import { ensureCodexAuth } from "./codex-auth.js";
 import { parserFactoryFor } from "./cli-parsers.js";
 import { sandboxTier, sandboxArgsFor, codexSandboxPolicy } from "../harness/sandbox.js";
 import { ProtocolRuntime, protocolRuntimeFromEnv, protocolCommandsFromEnv } from "./protocol.js";
+import { codexSlashCommands, opencodeSlashCommands } from "./slash-commands.js";
+/**
+ * On-disk slash commands (custom prompts/commands) for the CLI agents that keep
+ * them as markdown on the node — Codex's `$CODEX_HOME/prompts`, opencode's
+ * global + project `command` dirs. Populates their composer menu and makes an
+ * invoked `/name` actually run (see SlashCommandProvider). Any other agent has no
+ * such directory convention, so it returns undefined (no agent-native commands).
+ */
+function cliSlashCommands(id) {
+    if (id === "codex")
+        return codexSlashCommands();
+    if (id === "opencode")
+        return opencodeSlashCommands();
+    return undefined;
+}
 export * from "./types.js";
 export { NodeCredentialResolver, createCredentialStore } from "./credentials.js";
 const PI_CAPABILITIES = {
@@ -697,6 +712,9 @@ export function cliAgentManifest() {
             label: spec.displayName,
             command: spec.command,
             hidden: Boolean(spec.hidden),
+            supportTier: spec.supportTier ?? "beta",
+            certification: spec.testedVersion ? "release-tested" : (spec.supportTier ?? "beta") === "beta" ? "adapter-tested" : "unverified",
+            ...(spec.testedVersion ? { testedVersion: spec.testedVersion } : {}),
             headlessFlags: [...headless].filter((a) => !a.includes("{")),
             install: spec.install ?? null,
         };
@@ -979,6 +997,11 @@ function codexApprovalsInfo() {
             packages: false,
             fork: false,
             sessionDiscovery: true,
+            // getUsage() returns the shim's real token/cost snapshot, and `codex resume
+            // <id>` reopens the thread in Codex's TUI — advertise both so the catalog
+            // (and the pre-session picker) match what the session actually backs.
+            usageReporting: true,
+            interactiveTui: installed,
             // The governed/resumable Codex variant is the one that owns native
             // discovery+adoption (issue #156) — not the plain exec runtime below —
             // so an adopted session gets per-tool approvals from the moment it's
@@ -1095,7 +1118,12 @@ function codexAppServerRuntime(credsDir, tier) {
                 ],
             },
         ],
-        capabilities: { toolInterception: true, modelSelection: true, resume: true, nativeSessionDiscovery: true, nativeSessionAdoption: true },
+        // usageReporting: ProtocolSession.getUsage() already returns the shim's real
+        // token/cost snapshot — advertise it so the catalog matches what's backed.
+        // interactiveTui: `codex resume <rolloutId>` reopens the exact thread in
+        // Codex's own TUI (the same verified command as native discovery/takeover),
+        // gated on the codex binary being present — mirrors Claude's interactiveTui.
+        capabilities: { toolInterception: true, modelSelection: true, resume: true, usageReporting: true, interactiveTui: commandAvailable("codex"), nativeSessionDiscovery: true, nativeSessionAdoption: true },
         // Resume: the shim reconnects a prior thread via thread/resume by its rollout
         // id, and history preloads from the same on-disk rollout the exec path reads —
         // so takeover/reopen continues a governed session. (Validated on codex-cli
@@ -1112,6 +1140,15 @@ function codexAppServerRuntime(credsDir, tier) {
         // Bivy didn't start, so a pre-existing `codex` session can be adopted here
         // (the governed variant), never the plain exec runtime below.
         discoverNativeSessions: () => discoverNativeCodexSessions(),
+        // Codex custom prompts ($CODEX_HOME/prompts/*.md) → composer slash menu; an
+        // invoked one is expanded and sent as the turn (the app-server doesn't expand
+        // /prompt names itself). resolveCodexHome() matches the prepare'd CODEX_HOME.
+        slashCommands: codexSlashCommands(),
+        // "Continue in terminal": resume this exact thread in Codex's TUI by its
+        // rollout id. `codex resume <id>` is the same command native discovery and
+        // takeover already use (server.ts RESUME/NATIVE_RESUME maps); `env` carries
+        // the minted CODEX_HOME so the TUI reads the same auth.json chat did.
+        interactiveTui: ({ sessionRef, env }) => (sessionRef ? { command: "codex", args: ["resume", sessionRef], env } : null),
     });
 }
 // --- #2: the GENERAL ACP adapter (Agent Client Protocol) --------------------
@@ -1132,6 +1169,7 @@ function acpShimPath() {
  * ACP promotion path so both wrap agents identically.
  */
 function acpRuntimeOptions(opts) {
+    const slashCommands = cliSlashCommands(opts.id);
     return {
         id: opts.id,
         displayName: opts.displayName,
@@ -1141,6 +1179,9 @@ function acpRuntimeOptions(opts) {
         // the FIRST session (before the shim's hello lands); the hello confirms them.
         capabilities: { toolInterception: true, resume: true },
         resumable: true,
+        // An ACP-promoted opencode still surfaces/expands its on-disk commands (the
+        // ACP handshake doesn't carry them); a bare ACP agent has none.
+        ...(slashCommands ? { slashCommands } : {}),
         ...(opts.credsDir ? { credentials: createCredentialStore(opts.credsDir) } : {}),
     };
 }
@@ -1450,6 +1491,45 @@ const PICKER_RUNTIME_IDS = new Set([
     ...NON_CLI_PICKER_IDS,
     ...CLI_AGENT_IDS.filter((id) => !CLI_AGENT_SPECS[id].hidden),
 ]);
+function runtimeCertification(runtime) {
+    if (runtime.id === "pi")
+        return { certification: "release-tested", testedVersion: "0.83.0" };
+    if (runtime.id === "claude-code-sdk")
+        return { certification: "release-tested", testedVersion: "0.3.220" };
+    if (runtime.testedVersion)
+        return { certification: "release-tested", testedVersion: runtime.testedVersion };
+    return { certification: runtime.supportTier === "beta" ? "adapter-tested" : "unverified" };
+}
+function runtimeProtection(runtime) {
+    // Native SDK/CLI sandboxes receive the requested read-only/workspace/full tier
+    // in their own process boundary. The governed Codex path has both native
+    // sandbox flags and Bivy interception; label the stronger containment source.
+    const nativeSandbox = runtime.id === "claude-code-sdk" || runtime.id === "codex-approvals"
+        || (isCliAgentId(runtime.id) && Boolean(CLI_AGENT_SPECS[runtime.id].composeArgs));
+    if (nativeSandbox)
+        return {
+            protectionLevel: "native-sandbox",
+            protectionLabel: "Native sandbox",
+            protectionDetail: "This agent enforces Bivy's selected access tier in its native sandbox. Bivy tool controls may add approvals, but are not an OS jail of their own.",
+        };
+    if (runtime.capabilities.toolInterception)
+        return {
+            protectionLevel: "tool-controls",
+            protectionLabel: "Bivy tool controls",
+            protectionDetail: "Structured tool calls pass through Bivy policy and approvals. Shell heuristics prevent accidents, not adversarial escape.",
+        };
+    if (runtime.capabilities.mcpToolApprovals)
+        return {
+            protectionLevel: "mcp-controls",
+            protectionLabel: "MCP tools only",
+            protectionDetail: "Bivy governs MCP tool calls, but the agent's built-in shell and file operations still run with your user permissions.",
+        };
+    return {
+        protectionLevel: "user-permissions",
+        protectionLabel: "Runs as your user",
+        protectionDetail: "No Bivy-owned isolation or complete tool interception. Use a container/VM for unattended or untrusted work.",
+    };
+}
 export function listRuntimes(currentId) {
     return RUNTIME_CATALOG
         // Keep the current runtime visible even if hidden, so a session pinned to a
@@ -1472,7 +1552,7 @@ export function listRuntimes(currentId) {
         if (runtime.id === "acp")
             return acpInfo();
         return runtime;
-    }).map((runtime) => ({ ...runtime, current: runtime.id === currentId }));
+    }).map((runtime) => ({ ...runtime, ...runtimeProtection(runtime), ...runtimeCertification(runtime), current: runtime.id === currentId }));
 }
 export function makeRuntime(options) {
     const id = (options.runtime ?? process.env.BIVY_RUNTIME ?? "pi").toLowerCase();
@@ -1616,5 +1696,5 @@ function makeCliRuntime(id, options) {
                     : [a.replace(/\{id\}/g, sessionId).replace(/\{tier\}/g, tier)]),
             }
             : {};
-    return new ProcessRuntime({ id, displayName: spec.displayName, command: spec.command, args: runArgs, promptMode: spec.promptMode, credentials: createCredentialStore(options.credsDir), parserFactory: parserFactoryFor(parserId), preflight, prepare, model: cliModelConfig(id), thinking: cliThinkingConfig(id), usageReporting: cliUsageReporting(id), ...resumeOpts });
+    return new ProcessRuntime({ id, displayName: spec.displayName, command: spec.command, args: runArgs, promptMode: spec.promptMode, credentials: createCredentialStore(options.credsDir), parserFactory: parserFactoryFor(parserId), preflight, prepare, model: cliModelConfig(id), thinking: cliThinkingConfig(id), usageReporting: cliUsageReporting(id), slashCommands: cliSlashCommands(id), ...resumeOpts });
 }

package/dist/runtime/oauth/model-oauth.js

@@ -63,14 +63,15 @@ function tokensFrom(provider, payload, prev) {
     const rotated = typeof payload.refresh_token === "string" ? payload.refresh_token : "";
     const refresh = rotated || prev?.refresh || "";
     const expiresIn = Number(payload.expires_in) || 3600;
-    const expires = Date.now() + expiresIn * 1000 - provider.refreshSkewMs;
+    const now = Date.now();
+    const expires = now + expiresIn * 1000 - provider.refreshSkewMs;
     let accountId = prev?.accountId;
     if (provider.accountIdClaim) {
         accountId = jwtClaim(access, provider.accountIdClaim.path, provider.accountIdClaim.field) ?? accountId;
         if (!accountId)
             throw new Error(`Could not extract account id for "${provider.id}" from the OAuth token`);
     }
-    return { access, refresh, expires, ...(accountId ? { accountId } : {}) };
+    return { access, refresh, expires, refreshedAt: now, ...(accountId ? { accountId } : {}) };
 }
 // --- Authorization-code flow (browser + callback server + manual paste) ------
 function buildAuthorizeUrl(provider, opts) {
@@ -282,7 +283,7 @@ export async function loginModelOAuth(credsDir, providerId, interaction) {
     if (!provider)
         throw new Error(`Provider "${providerId}" does not support subscription login`);
     const tokens = provider.flow === "device_code" ? await loginDeviceCode(provider, interaction) : await loginAuthCode(provider, interaction);
-    const credential = { type: "oauth", access: tokens.access, refresh: tokens.refresh, expires: tokens.expires, ...(tokens.accountId ? { accountId: tokens.accountId } : {}) };
+    const credential = { type: "oauth", access: tokens.access, refresh: tokens.refresh, expires: tokens.expires, refreshedAt: tokens.refreshedAt, ...(tokens.accountId ? { accountId: tokens.accountId } : {}) };
     await createCredentialVault(credsDir).modify(providerId, async () => credential);
 }
 /** Exchange the refresh token for a fresh credential (network call; throws on failure). */
@@ -318,7 +319,7 @@ export async function refreshModelOAuth(credsDir, providerId) {
         if (Number(current.expires) > Date.now())
             return current;
         const fresh = await refreshTokens(provider, current);
-        return { type: "oauth", access: fresh.access, refresh: fresh.refresh, expires: fresh.expires, ...(fresh.accountId ? { accountId: fresh.accountId } : {}) };
+        return { type: "oauth", access: fresh.access, refresh: fresh.refresh, expires: fresh.expires, refreshedAt: fresh.refreshedAt, ...(fresh.accountId ? { accountId: fresh.accountId } : {}) };
     });
     return result?.type === "oauth" ? result.access : undefined;
 }

package/dist/runtime/process.js

@@ -5,7 +5,7 @@ import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { stripAnsi } from "./ansi.js";
 import { buildAgentCredentialEnv } from "./credentials.js";
-import { egressEnv } from "../harness/egress.js";
+import { egressEnv, sessionEgressEnv } from "../harness/egress.js";
 import { depCacheEnv } from "../harness/dep-cache.js";
 import { bivySessionEnv } from "./session-env.js";
 /**
@@ -193,6 +193,17 @@ class ProcessSession {
     setName(name) {
         this.name = name;
     }
+    /** The agent's on-disk slash commands for this workspace (Codex prompts,
+     *  opencode commands). Best-effort and display-only: any read failure yields an
+     *  empty menu, never a throw. */
+    getCommands() {
+        try {
+            return this.runtimeOptions.slashCommands?.list(this.cwd) ?? [];
+        }
+        catch {
+            return [];
+        }
+    }
     async suggestName() {
         // The generic CLI "dumb-pipe" runtime has no model of its own to name a
         // session with. Returning a raw 60-char truncation of the first message here
@@ -216,6 +227,17 @@ class ProcessSession {
         const prompt = text.trim();
         if (!prompt)
             return;
+        // A `/name args` line that matches an on-disk command runs the command by
+        // sending its expanded body to the agent; the transcript still shows what the
+        // user typed. Any non-command line (incl. a leading slash that isn't one)
+        // passes through untouched. Best-effort — a read failure sends the raw line.
+        let promptToSend;
+        try {
+            promptToSend = this.runtimeOptions.slashCommands?.expand(this.cwd, prompt) ?? prompt;
+        }
+        catch {
+            promptToSend = prompt;
+        }
         this.messages.push({ role: "user", content: prompt, timestamp: Date.now() });
         this.streaming = true;
         this.emit({ type: "agent_start" });
@@ -244,7 +266,7 @@ class ProcessSession {
             const idx = Math.min(Math.max(at, 0), argsWithFlags.length);
             argsWithFlags = [...argsWithFlags.slice(0, idx), ...inject, ...argsWithFlags.slice(idx)];
         }
-        const args = this.runtimeOptions.promptMode === "argv" ? [...argsWithFlags, prompt] : argsWithFlags;
+        const args = this.runtimeOptions.promptMode === "argv" ? [...argsWithFlags, promptToSend] : argsWithFlags;
         // Resolve credentials per prompt so freshly-refreshed OAuth tokens (and keys
         // added after this session started) reach the agent. The vault wins over any
         // ambient key so Bivy's shared sign-in is authoritative.
@@ -278,12 +300,14 @@ class ProcessSession {
         // src/harness/sandbox.ts). Bivy no longer wraps the process in an OS jail.
         const child = spawn(this.runtimeOptions.command, args, {
             cwd: this.cwd,
-            // egressEnv() routes this agent's outbound traffic through the harness
-            // network broker when BIVY_EGRESS_PROXY is enabled (else it's {}).
-            // bivySessionEnv() lets the agent's own shell resolve its session for
-            // `bivy attach <path>` (see session-env.ts); spread last so it can never
-            // be shadowed by an operator-configured env var of the same name.
-            env: { ...process.env, ...depCacheEnv(), ...this.runtimeOptions.env, ...credentialEnv, ...prepareEnv, ...egressEnv(), ...bivySessionEnv(this.id) },
+            // Route this agent's outbound traffic through an egress proxy: this
+            // session's OWN proxy if it has one (a per-session sandbox/workflow network
+            // policy — sessionEgressEnv), else the node-global broker when
+            // BIVY_EGRESS_PROXY is enabled (else {}). bivySessionEnv() lets the agent's
+            // own shell resolve its session for `bivy attach <path>` (see
+            // session-env.ts); spread last so it can never be shadowed by an operator-
+            // configured env var of the same name.
+            env: { ...process.env, ...depCacheEnv(), ...this.runtimeOptions.env, ...credentialEnv, ...prepareEnv, ...(sessionEgressEnv(this.id) ?? egressEnv()), ...bivySessionEnv(this.id) },
             stdio: "pipe",
             // Detached so the child becomes the leader of its own process group
             // (POSIX) — see killProcessGroup() / abort() below, which kill that whole
@@ -380,7 +404,7 @@ class ProcessSession {
             this.emit({ type: "agent_end", code, signal });
         });
         if (this.runtimeOptions.promptMode !== "argv") {
-            child.stdin.end(`${prompt}\n`);
+            child.stdin.end(`${promptToSend}\n`);
         }
         else {
             // Prompt is already in argv. Still close stdin so agents that also read it

package/dist/runtime/protocol.js

@@ -5,6 +5,7 @@ import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { buildAgentCredentialEnv } from "./credentials.js";
 import { bivySessionEnv } from "./session-env.js";
+import { mergeAgentCommands } from "./slash-commands.js";
 import { extractTokenUsage } from "./cli-parsers.js";
 /** A protocol `usage` message → UsageSnapshot (reuses the CLI token-key scan). */
 function parseProtocolUsage(raw) {
@@ -247,6 +248,42 @@ class ProtocolSession {
         await this.open();
         await this.command("command.invoke", { sessionId: this.id, runtimeSessionRef: this.runtimeSessionRef, name, args: args ?? "" });
     }
+    /** The session's slash commands: on-disk custom prompts (Codex/opencode) merged
+     *  with whatever the shim advertised in its hello, disk winning a collision.
+     *  Best-effort and display-only — a read failure just drops the on-disk set. */
+    getCommands() {
+        let disk;
+        try {
+            disk = this.runtimeOptions.slashCommands?.list(this.cwd);
+        }
+        catch {
+            disk = undefined;
+        }
+        return mergeAgentCommands(disk, this.capabilitiesRef.commands);
+    }
+    /**
+     * Resume this session in the agent's own interactive TUI (see the runtimeOptions
+     * hook). Resolves the same launch env a turn would — `prepare` (e.g. Codex
+     * mints CODEX_HOME + auth.json) then credentials — so the TUI opens with the
+     * identical auth as chat. Returns null when the runtime has no TUI hook or there
+     * is no session ref to resume yet (the daemon then surfaces "no TUI available").
+     */
+    async interactiveTuiCommand() {
+        const hook = this.runtimeOptions.interactiveTui;
+        if (!hook)
+            return null;
+        const credentialEnv = this.runtimeOptions.credentials
+            ? await buildAgentCredentialEnv(this.runtimeOptions.credentials, undefined, this.currentModelProvider).catch(() => ({}))
+            : {};
+        let prepareEnv = this.prepareEnv;
+        if (this.runtimeOptions.prepare) {
+            prepareEnv =
+                (await Promise.resolve(this.runtimeOptions.prepare({ ...process.env, ...this.runtimeOptions.env, ...credentialEnv })).catch(() => undefined)) ??
+                    prepareEnv;
+        }
+        const env = { ...this.runtimeOptions.env, ...credentialEnv, ...prepareEnv };
+        return hook({ sessionRef: this.runtimeSessionRef ?? this.resumeRef, cwd: this.cwd, env });
+    }
     getName() { return this.name; }
     setName(name) { this.name = name; }
     async suggestName(firstPrompt) {
@@ -556,6 +593,17 @@ class ProtocolSession {
         const images = (options?.images ?? []).map((img) => ({ type: "image", data: img.data, mimeType: img.mimeType }));
         if (!prompt && !images.length)
             return;
+        // A `/name args` line matching an on-disk custom prompt runs the command by
+        // sending its expanded body; the transcript still shows what the user typed.
+        // Non-command lines pass through untouched. Best-effort — a read failure sends
+        // the raw line.
+        let textToSend;
+        try {
+            textToSend = this.runtimeOptions.slashCommands?.expand(this.cwd, prompt) ?? prompt;
+        }
+        catch {
+            textToSend = prompt;
+        }
         this.messages.push({ role: "user", content: prompt, timestamp: Date.now() });
         this.streaming = true;
         this.assistantText = "";
@@ -566,7 +614,7 @@ class ProtocolSession {
         await this.command("chat.send", {
             sessionId: this.id,
             runtimeSessionRef: this.runtimeSessionRef,
-            text: prompt,
+            text: textToSend,
             // Optional multimodal + streaming hints. Present only when the caller
             // supplied them, so a text-only turn keeps the exact payload it always had.
             ...(images.length ? { images } : {}),

package/dist/runtime/slash-commands.js

@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Filesystem-sourced slash commands for agents whose "slash commands" are custom
+// prompt/command markdown files on disk — Codex's `$CODEX_HOME/prompts/*.md` and
+// opencode's `command/*.md` dirs — rather than something learned from a live
+// handshake the way Claude (SDK `init`) and Pi (its extension runner) already do.
+// This is what gives Codex and opencode a real slash menu in the composer instead
+// of the empty state Phase 1 added for them. Two responsibilities:
+//
+//  1. Discovery — enumerate those files as `AgentCommand[]` so `getCommands()` can
+//     advertise them and the composer offers them in autocomplete.
+//  2. Local expansion — when the user actually invokes `/name args`, read the file
+//     and return its expanded body so the command RUNS, instead of the literal
+//     text "/name" being sent to the model. Codex and opencode expand custom
+//     prompts only in their interactive TUI, not on the non-interactive
+//     run/app-server path Bivy drives, so Bivy expands them itself. Substitution
+//     mirrors what those agents document: `$ARGUMENTS` → the whole argument
+//     string, `$1`..`$9` → positional words; unused trailing args are appended
+//     when the body carries no placeholder (matching Codex's own behaviour). We
+//     do NOT emulate opencode's `!shell` / `@file` macros — the expanded body is
+//     sent verbatim for those, a documented, graceful partial.
+//
+// Everything is best-effort and synchronous: an unreadable dir yields no commands
+// and `expand()` returns undefined, so the caller falls back to the exact prior
+// "forward the raw slash line" behaviour. `expand()` returning undefined for any
+// line that isn't a known command means ordinary prompts — and a leading slash
+// that happens not to be a command — pass through untouched.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_LIMIT = 300;
+const DEFAULT_DEPTH = 3;
+/**
+ * Parse a markdown command file into its display description and prompt body.
+ * A leading `---` YAML frontmatter block contributes `description` (the only key
+ * we read); its body is everything after the block. With no frontmatter the body
+ * is the whole file and the description falls back to the first non-empty line
+ * (stripped of leading markdown heading/list markers, truncated for the menu).
+ * Exported for unit tests.
+ */
+export function parseCommandMarkdown(content) {
+    let description;
+    let body = content;
+    const fm = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(content);
+    if (fm) {
+        body = content.slice(fm[0].length);
+        for (const line of fm[1].split(/\r?\n/)) {
+            const m = /^\s*description\s*:\s*(.+?)\s*$/i.exec(line);
+            if (m) {
+                description = stripQuotes(m[1]);
+                break;
+            }
+        }
+    }
+    if (!description) {
+        for (const raw of body.split(/\r?\n/)) {
+            const line = raw.trim();
+            if (!line)
+                continue;
+            description = line.replace(/^[#>*\-\s]+/, "").trim() || undefined;
+            break;
+        }
+    }
+    if (description && description.length > 80)
+        description = `${description.slice(0, 79)}…`;
+    return { description, body: body.trim() };
+}
+function stripQuotes(value) {
+    const v = value.trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        return v.slice(1, -1);
+    }
+    return v;
+}
+/**
+ * Expand a command body against its argument string, mirroring Codex/opencode:
+ * `$ARGUMENTS` → the full argument string, `$1`..`$9` → positional words (missing
+ * ones → empty). When the body references no placeholder and args were supplied,
+ * they're appended (Codex appends unused args rather than dropping them).
+ * Exported for unit tests.
+ */
+export function expandCommandBody(body, argString) {
+    const args = argString.trim();
+    const positional = args ? args.split(/\s+/) : [];
+    let used = false;
+    let out = body.replace(/\$ARGUMENTS\b/g, () => {
+        used = true;
+        return args;
+    });
+    out = out.replace(/\$([1-9])/g, (_m, d) => {
+        used = true;
+        return positional[Number(d) - 1] ?? "";
+    });
+    if (!used && args)
+        out = `${out.replace(/\s+$/, "")}\n\n${args}`;
+    return out.trim();
+}
+/** The command name (without leading slash) a "/name args" line invokes, or null. */
+function parseInvocation(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("/"))
+        return null;
+    const ws = trimmed.search(/\s/);
+    const name = (ws === -1 ? trimmed.slice(1) : trimmed.slice(1, ws)).trim();
+    if (!name)
+        return null;
+    const args = ws === -1 ? "" : trimmed.slice(ws + 1).trim();
+    return { name, args };
+}
+/**
+ * Recursively collect `*.md` under `dir` as `relativePath (no .md)` → absolute
+ * path, where the relative path is POSIX-joined ("/") from the top `dir` so a
+ * subdirectory file namespaces (opencode's `git/commit.md` → `git/commit`).
+ */
+function collectMarkdown(dir, prefix, depth, limit, out) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return; // missing/unreadable dir — no commands from here
+    }
+    for (const entry of entries) {
+        if (out.size >= limit)
+            return;
+        if (entry.name.startsWith("."))
+            continue;
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (depth > 0)
+                collectMarkdown(abs, prefix ? `${prefix}/${entry.name}` : entry.name, depth - 1, limit, out);
+        }
+        else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+            const rel = entry.name.slice(0, -3);
+            out.set(prefix ? `${prefix}/${rel}` : rel, abs);
+        }
+    }
+}
+/**
+ * Build the `/name` → file map for a session: scan each dir (later dirs win a
+ * collision), namespacing subdirectory files with "/" (opencode's convention;
+ * Codex prompts are flat). Best-effort — unreadable dirs contribute nothing.
+ */
+function indexCommands(dirs, depth, limit) {
+    const byName = new Map();
+    for (const dir of dirs) {
+        const found = new Map();
+        collectMarkdown(dir, "", depth, limit, found);
+        for (const [rel, abs] of found) {
+            byName.set(`/${rel}`, abs);
+        }
+    }
+    return byName;
+}
+function readCommandFile(name, abs) {
+    let content;
+    try {
+        content = fs.readFileSync(abs, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const { description, body } = parseCommandMarkdown(content);
+    return { name, description, body };
+}
+/**
+ * A `SlashCommandProvider` backed by markdown files in `opts.dirs(cwd)`. Used to
+ * give Codex (`$CODEX_HOME/prompts`) and opencode (global + project `command`
+ * dirs) their slash menus — see `codexSlashCommands` / `opencodeSlashCommands`.
+ */
+export function markdownSlashCommands(opts) {
+    const depth = opts.depth ?? DEFAULT_DEPTH;
+    const limit = opts.limit ?? DEFAULT_LIMIT;
+    return {
+        list(cwd) {
+            const index = indexCommands(opts.dirs(cwd), depth, limit);
+            const out = [];
+            for (const [name, abs] of index) {
+                const file = readCommandFile(name, abs);
+                if (!file)
+                    continue;
+                const command = { name };
+                if (file.description)
+                    command.description = file.description;
+                out.push(command);
+            }
+            out.sort((a, b) => a.name.localeCompare(b.name));
+            return out;
+        },
+        expand(cwd, line) {
+            const invocation = parseInvocation(line);
+            if (!invocation)
+                return undefined;
+            const index = indexCommands(opts.dirs(cwd), depth, limit);
+            const abs = index.get(`/${invocation.name}`);
+            if (!abs)
+                return undefined;
+            const file = readCommandFile(`/${invocation.name}`, abs);
+            if (!file)
+                return undefined;
+            return expandCommandBody(file.body, invocation.args);
+        },
+    };
+}
+/** Codex's home dir, exactly as the CLI resolves it (`$CODEX_HOME` or `~/.codex`). */
+function codexHome() {
+    return process.env.CODEX_HOME?.trim() || path.join(os.homedir(), ".codex");
+}
+/** The user's global opencode config dir (`$XDG_CONFIG_HOME` or `~/.config`). */
+function opencodeConfigDir() {
+    return process.env.XDG_CONFIG_HOME?.trim() || path.join(os.homedir(), ".config");
+}
+/** Codex custom prompts (`$CODEX_HOME/prompts/*.md`) → `/name` commands. */
+export function codexSlashCommands() {
+    return markdownSlashCommands({ dirs: () => [path.join(codexHome(), "prompts")] });
+}
+/**
+ * opencode custom commands — the global `command` dir plus the project-local
+ * `.opencode/command` (which shadows the global on a name collision). See
+ * opencode.ai/docs/commands.
+ */
+export function opencodeSlashCommands() {
+    return markdownSlashCommands({
+        dirs: (cwd) => [path.join(opencodeConfigDir(), "opencode", "command"), path.join(cwd, ".opencode", "command")],
+    });
+}
+/**
+ * Merge disk-sourced commands with any the runtime already advertised (e.g. a
+ * protocol shim's hello), disk winning a name collision. Used by ProtocolSession
+ * so hello-advertised commands and on-disk prompts coexist. First occurrence of
+ * each name (disk first) wins; input order is otherwise preserved.
+ */
+export function mergeAgentCommands(...groups) {
+    const seen = new Set();
+    const out = [];
+    for (const group of groups) {
+        for (const command of group ?? []) {
+            if (!command?.name || seen.has(command.name))
+                continue;
+            seen.add(command.name);
+            out.push(command);
+        }
+    }
+    return out;
+}