@subshell-ai/plugin-codex 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,341 @@
+//#region ../../plugin-api/dist/types-90lJTTx6.d.ts
+//#region src/types.d.ts
+/**
+ * The contract a Subshell plugin implements.
+ *
+ * A plugin is loaded from disk by a compiled binary, which means it CANNOT
+ * import anything of ours at runtime. Measured on bun 1.4.2: a bare specifier
+ * from a plugin file fails to resolve, because there is no `node_modules`
+ * beside it. Everything a plugin needs therefore arrives through
+ * {@link PluginHost}, handed to the factory it default-exports.
+ *
+ * This package is types plus PURE helpers only. A plugin bundles it in at
+ * build time, so anything with runtime behaviour would freeze at the version
+ * the plugin was built against; a filesystem probe that did that would keep
+ * searching last year's install locations forever. Those belong on the host.
+ */
+/**
+ * What kind of thing a plugin provides.
+ *
+ * For humans: it groups and labels in the UI and filters the catalog. Code
+ * branches on {@link PluginCapability} instead, so adding a type here touches
+ * labels while adding a capability touches the launch pipeline.
+ */
+type PluginType = "agent-harness" | "terminal";
+/**
+ * What a plugin can DO. The launch pipeline and the UI read this; neither
+ * branches on {@link PluginType}.
+ */
+type PluginCapability = "mcp" | "resume" | "attention" | "settings";
+/** A harness profile as defined by the user (decoded JSON blobs). */
+interface ProfileDefinition {
+  /** Human-friendly profile name */
+  name: string;
+  /** Optional longer description */
+  description?: string | null;
+  /** Extra environment variables to set on the subshell */
+  env: Record<string, string>;
+  /** Extra CLI flags to pass to the harness binary */
+  flags: string[];
+  /** Settings blob passed to the harness (e.g. claude --settings JSON) */
+  settings: Record<string, unknown> | null;
+  /** If true, only this profile's config sources apply (isolation) */
+  configIsolation: boolean;
+  /** If true, new subshells from this profile auto-restart on exit */
+  restartOnExit?: boolean;
+}
+/** Snapshot of a single field-level validation error on a profile. */
+interface ProfileValidationIssue {
+  /** Field name (e.g. "name", "env", "settings") */
+  field: string;
+  /** Human-readable problem description */
+  message: string;
+}
+interface ProfileValidationResult {
+  valid: boolean;
+  issues: ProfileValidationIssue[];
+}
+/** Everything a plugin needs to build a launch command. */
+interface BuildCommandInput {
+  /** Resolved absolute path to the harness binary */
+  binary: string;
+  /** Working directory the harness runs in */
+  cwd: string;
+  /** The validated profile being used */
+  profile: ProfileDefinition;
+  /** Subshell display name ("" = let the harness pick a default) */
+  subshellName: string;
+  /** Any additional CLI flags from route/request context */
+  extraFlags?: string[];
+  /**
+   * The subshell's MCP registration (channels + subshell orchestration), as
+   * produced by this plugin's own `mcpRegistration` and already written to
+   * disk. Plugins consume ONLY `mcp.args`: splice them where the dialect needs
+   * them (claude right after the binary). `mcp.env` is baked into the pane by
+   * the host before the command runs; plugins must not consume it themselves.
+   * Undefined = no registration for this launch.
+   */
+  mcp?: McpRegistration;
+  /**
+   * Conversation identity for restart-resume; set only when this plugin
+   * declares the `resume` capability. `mode: "start"` means the conversation
+   * is NEW and must be created under exactly this id (pin it, because the host
+   * stores it and later resumes by it); `mode: "resume"` names an EXISTING
+   * conversation to continue (the host only asks after {@link HarnessResume.canResume}
+   * confirmed it survives).
+   */
+  harnessSession?: {
+    id: string;
+    mode: "start" | "resume";
+  };
+}
+/**
+ * Restart-resume, implemented only by plugins that can continue a previous
+ * conversation.
+ *
+ * The ids here are HARNESS conversation ids (a claude transcript uuid, say),
+ * never subshell ids: the host pins {@link allocateHarnessSessionId} at launch,
+ * stores it on the subshell row, and consults {@link canResume} before every
+ * restart to choose between continuing and starting fresh.
+ */
+interface HarnessResume {
+  /** Allocates the HARNESS conversation id to pin at launch (a uuid for claude). */
+  allocateHarnessSessionId(): string;
+  /**
+   * Whether the harness conversation `harnessSessionId` (last run in `cwd`)
+   * still exists and can be resumed. False means the host launches a fresh
+   * conversation rather than handing the harness an id it would reject.
+   */
+  canResume(harnessSessionId: string, cwd: string): boolean;
+}
+/** How to spawn the `subshell mcp` stdio server. */
+interface McpLaunchSpec {
+  /** Executable to run (the self command, the interpreter, or the agent binary) */
+  command: string;
+  /** Arguments for the executable (e.g. the mcp entry script path) */
+  args: string[];
+}
+/** Per-subshell MCP registration rendered in the plugin's own config dialect. */
+interface McpRegistration {
+  /** File content the harness reads, written to the subshell's config path */
+  fileContent: string;
+  /** argv the harness needs to load the file (e.g. claude's ["--mcp-config", path]) */
+  args?: string[];
+  /**
+   * Extra pane env the harness needs to discover the file (e.g. OPENCODE_CONFIG).
+   * Consumed by the HOST, which bakes it into the pane env ahead of profile env;
+   * plugins never read it back.
+   */
+  env?: Record<string, string>;
+}
+/** One copy-paste line shown in the profile editor for manual-setup harnesses. */
+interface McpSetupStep {
+  /** What the user should do, and where the text goes */
+  label: string;
+  /** Copyable command or snippet */
+  command: string;
+}
+/**
+ * How a harness obtains the `subshell mcp` tools.
+ *
+ * Discriminated on purpose: auto harnesses explain themselves in one line and
+ * manual harnesses carry steps, and a plugin cannot mix the two.
+ */
+type McpSetupInfo = {
+  mode: "auto";
+  summary: string;
+} | {
+  mode: "manual";
+  steps: McpSetupStep[];
+};
+/** A single option in a plugin's settings editor. */
+interface SettingsField {
+  /** Key into the settings object (e.g. "permissionMode") */
+  key: string;
+  /** Property label */
+  label: string;
+  /** Short description for the editor */
+  description?: string;
+  /** One of: string, boolean, number, select */
+  type: "string" | "boolean" | "number" | "select";
+  /** Choices when type === "select" */
+  choices?: string[];
+  /** Default value when unset */
+  default?: string | boolean | number;
+}
+/**
+ * Why there is no binary.
+ *
+ * `no-binary` is not a failure: a plugin (a `terminal` one, say) can declare
+ * no binary at all, and rendering that as "not on PATH" tells someone their
+ * PATH is wrong about something that never wanted one.
+ */
+type DetectionReason = "not-on-path" | "override-invalid" | "no-binary";
+/** A detection answer: the path, or the reason there is not one. */
+type DetectionResult = {
+  path: string;
+  reason?: undefined;
+} | {
+  path: null;
+  reason: DetectionReason;
+};
+/**
+ * Everything the host lends a plugin, because a plugin can import none of it.
+ *
+ * This is also the version boundary: a host at a higher `apiVersion` keeps
+ * older plugins working by keeping the fields they were compiled against, so
+ * members are ADDED here and never removed or retyped.
+ */
+interface PluginHost {
+  /** The API version this host implements. Always >= the plugin's own. */
+  readonly apiVersion: number;
+  /** Resolve a binary through the host's full lookup ladder. */
+  findBinary(name: string, envOverride: string, knownPaths: string[]): Promise<string | null>;
+  /** The same lookup, reporting why it failed. */
+  detectBinary(name: string, envOverride: string, knownPaths: string[]): Promise<DetectionResult>;
+  /** Run a short command with a deadline; trimmed stdout, or null. */
+  probeVersion(binary: string, args?: string[]): Promise<string | null>;
+  /** POSIX-quote one argument for a shell command line. */
+  shellQuote(value: string): string;
+  /** Structured logging, namespaced to the plugin. */
+  log: {
+    debug(message: string): void;
+    warn(message: string): void;
+  };
+}
+/**
+ * The plugin itself.
+ *
+ * Only the first three members are required. Everything else is a capability
+ * the plugin opts into and declares from {@link capabilities}, so a `terminal`
+ * plugin is a binary and an argv rather than eight stubs.
+ */
+interface SubshellPlugin {
+  /** Builds the argv (no shell) used to launch a subshell. */
+  buildCommand(input: BuildCommandInput): string[];
+  /** Validates a profile definition before saving. */
+  validateProfile(profile: ProfileDefinition): ProfileValidationResult;
+  /** Which optional members below are meaningful on this plugin. */
+  capabilities(): PluginCapability[];
+  /** Maps a harness exit code to a human label (null = unknown). */
+  exitStatus?(code: number): string | null;
+  /**
+   * Interprets the raw stdout of the version probe.
+   *
+   * Probing is the host's job (it owns the deadline); making sense of the
+   * output is the plugin's, because only the plugin knows its harness prints
+   * a banner rather than a bare semver. Omit it and the trimmed output is
+   * used as-is, which is right for every harness that prints just a version.
+   */
+  parseVersion?(raw: string): string | null;
+  /** Overrides manifest-driven detection. Almost no plugin needs this. */
+  detect?(): Promise<DetectionResult>;
+  /** Restart-resume support. Declare the `resume` capability with it. */
+  resume?: HarnessResume;
+  /**
+   * True when `buildCommand` wires this harness's native "needs attention"
+   * reporting into the launch. The host's quiet-output idle watcher skips
+   * these. Declare the `attention` capability with it.
+   */
+  supportsAttentionHooks?: boolean;
+  /**
+   * Renders the per-subshell MCP registration in this harness's config format.
+   * Omit when the harness cannot consume a per-subshell config file; the host
+   * then surfaces one-time manual setup via {@link mcpSetup} instead.
+   */
+  mcpRegistration?(launch: McpLaunchSpec, configPath: string): McpRegistration;
+  /** How users obtain the subshell MCP tools here. Declare the `mcp` capability with it. */
+  mcpSetup?(launch: McpLaunchSpec): McpSetupInfo;
+  /** Settings rendered in the PROFILE editor and stored on the profile. */
+  profileSettings?(): SettingsField[];
+  /** Known extra env var suggestions for the profile editor. */
+  suggestedEnv?(): {
+    key: string;
+    description: string;
+  }[];
+  /** Known CLI flag suggestions for the profile editor. */
+  suggestedFlags?(): {
+    flag: string;
+    description: string;
+  }[];
+}
+/** What a plugin module default-exports. */
+type PluginFactory = (host: PluginHost) => SubshellPlugin;
+//#endregion
+//#region ../../plugin-api/dist/index.d.ts
+/** How a host finds this plugin's binary, as data, so a scan loads no plugin code. */
+interface DetectSpec {
+  /** Executable name to look for, e.g. "claude" */
+  binaryName: string;
+  /** Env var that overrides the lookup outright, e.g. "CLAUDE_PATH" */
+  envOverride: string;
+  /** Well-known locations relative to HOME, tried after PATH */
+  knownPaths: string[];
+}
+/** Where to send someone whose binary is missing. */
+interface InstallSpec {
+  /** Copy-pasteable install command for the official installer */
+  command: string;
+  /** URL of the installation documentation */
+  docsUrl: string;
+}
+/** The parsed `subshell` block. */
+interface SubshellManifest {
+  /** plugin-api version this plugin was built against */
+  apiVersion: number;
+  /** Stable id, also its directory name */
+  id: string;
+  /** What kind of thing this provides */
+  type: PluginType;
+  /** Display name */
+  name: string;
+  /** One-line description shown in the UI */
+  description: string;
+  /** Optional emoji/glyph */
+  icon?: string;
+  /** Module to import, relative to the package directory */
+  entry: string;
+  /** Manifest-driven detection; absent for a plugin that needs no binary */
+  detect?: DetectSpec;
+  /** Install guidance shown when the binary is missing */
+  install?: InstallSpec;
+}
+//#endregion
+//#region src/manifest.d.ts
+declare const manifest: SubshellManifest;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Built-in harness: Codex (OpenAI's `@openai/codex` CLI).
+ *
+ * Launch shape:
+ *   codex [-m <model>] [-s <sandbox>] [-a <approval>] [mcp -c pairs]
+ *         [profile flags] [extra flags]
+ * A bare launch (no subcommand, no prompt) opens the interactive TUI. Codex
+ * has no create-time flag for naming its own session and no way to pin a
+ * conversation id, so neither the subshell name nor a resume capability is
+ * forwarded — restarts start a fresh conversation (the documented default).
+ * The pane's
+ * cwd is already the working directory, so `-C/--cd` is never passed, and
+ * `--dangerously-bypass-approvals-and-sandbox` is NEVER baked into a launch
+ * (a user may put it in their own profile flags — that is their call).
+ *
+ * subshell MCP is wired automatically WITHOUT touching user state: every
+ * launch carries `-c mcp_servers.subshell.command=… -c mcp_servers.subshell.args=…`
+ * config overrides (dotted path, value parsed as TOML — verified against the
+ * real binary), which codex merges over ~/.codex/config.toml for that run
+ * only. No config file the harness must read, no CODEX_HOME redirect (that
+ * dir holds the user's auth.json). The spawned `subshell mcp` child inherits
+ * the subshell's baked SUBSHELL_* pane env for its credential, like every
+ * harness.
+ * (Flags/values verified against @openai/codex 2026-09 help output.)
+ *
+ * Identity, detection and install guidance live in this package's
+ * package.json `subshell` block, NOT here: the host reads them without
+ * importing or executing a line of this file.
+ *
+ * `host` carries what this module cannot import. See `@subshell-ai/plugin-api`.
+ */
+declare const createPlugin: PluginFactory;
+//#endregion
+export { createPlugin as default, manifest };

package/dist/index.js

@@ -0,0 +1,321 @@
+//#region ../../plugin-api/dist/manifest-im30YVIq.js
+/** Every {@link PluginType}, for anything that has to iterate or validate them. */
+const PLUGIN_TYPES = ["agent-harness", "terminal"];
+/**
+* The MCP server name every harness registers the built-in `subshell mcp`
+* server under: the config object key, and the `hermes mcp add|remove`
+* argument alike. The server reports the same name in its MCP handshake, which
+* is what harnesses surface in wire tool ids (`mcp__<name>__<tool>`).
+*/
+const MCP_SERVER_NAME = "subshell";
+/**
+* Ids become directory names under `<dataDir>/plugins/`, so they are path
+* segments and nothing else: no separators, no traversal, no surprises from a
+* case-insensitive filesystem.
+*/
+const ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Reads and validates the `subshell` block of a plugin's package.json.
+*
+* Answers `{ error }` rather than throwing, because every caller is reporting
+* a broken plugin to a person rather than handling an exception: the node
+* marks the plugin broken and renders this message beside it. The strings are
+* therefore specific on purpose.
+* @param pkgJson - the parsed package.json of a plugin directory
+*/
+function parseManifest(pkgJson) {
+	if (!isRecord(pkgJson)) return { error: "package.json is not an object" };
+	const block = pkgJson.subshell;
+	if (!isRecord(block)) return { error: "package.json has no `subshell` block, so it is not a Subshell plugin" };
+	if (typeof block.apiVersion !== "number" || !Number.isInteger(block.apiVersion)) return { error: "`subshell.apiVersion` must be an integer" };
+	if (block.apiVersion < 1) return { error: `this plugin declares plugin-api ${block.apiVersion}, which is not a version; the lowest is 1 and this host implements 1` };
+	if (block.apiVersion > 1) return { error: `this plugin needs plugin-api ${block.apiVersion}, but this host implements 1; upgrade the agent` };
+	if (typeof block.id !== "string" || !ID_RE.test(block.id)) return { error: "`subshell.id` must be lowercase letters, digits and hyphens, starting alphanumeric (it becomes a directory name)" };
+	if (typeof block.type !== "string" || !PLUGIN_TYPES.includes(block.type)) return { error: `\`subshell.type\` must be one of: ${PLUGIN_TYPES.join(", ")}` };
+	if (typeof block.name !== "string" || block.name.trim() === "") return { error: "`subshell.name` must be a non-empty string" };
+	if (typeof block.description !== "string") return { error: "`subshell.description` must be a string" };
+	if (block.icon !== void 0 && typeof block.icon !== "string") return { error: "`subshell.icon` must be a string" };
+	if (typeof block.entry !== "string" || block.entry.trim() === "") return { error: "`subshell.entry` must be a non-empty relative path" };
+	if (block.entry.startsWith("/") || block.entry.split("/").includes("..")) return { error: "`subshell.entry` must stay inside the package (no leading `/` and no `..` segment)" };
+	let detect;
+	if (block.detect !== void 0) {
+		const d = block.detect;
+		if (!isRecord(d) || typeof d.binaryName !== "string" || typeof d.envOverride !== "string" || !Array.isArray(d.knownPaths) || !d.knownPaths.every((k) => typeof k === "string")) return { error: "`subshell.detect` needs binaryName, envOverride and a knownPaths array of strings" };
+		detect = {
+			binaryName: d.binaryName,
+			envOverride: d.envOverride,
+			knownPaths: d.knownPaths
+		};
+	}
+	let install;
+	if (block.install !== void 0) {
+		const i = block.install;
+		if (!isRecord(i) || typeof i.command !== "string" || typeof i.docsUrl !== "string") return { error: "`subshell.install` needs a command and a docsUrl" };
+		install = {
+			command: i.command,
+			docsUrl: i.docsUrl
+		};
+	}
+	return {
+		apiVersion: block.apiVersion,
+		id: block.id,
+		type: block.type,
+		name: block.name,
+		description: block.description,
+		...typeof block.icon === "string" ? { icon: block.icon } : {},
+		entry: block.entry,
+		...detect ? { detect } : {},
+		...install ? { install } : {}
+	};
+}
+//#endregion
+//#region ../../plugin-api/dist/index.js
+/**
+* The profile checks every built-in harness performs unchanged: a non-empty
+* name, string env values, and flags that look like flags. Harnesses with
+* extra rules run their own checks on top of these.
+* @param profile - The decoded profile definition to check
+* @returns Issues per field; `valid` is true when no issues were found
+*/
+function validateGenericProfile(profile) {
+	const issues = [];
+	if (!profile.name || profile.name.trim().length === 0) issues.push({
+		field: "name",
+		message: "Profile name is required."
+	});
+	for (const [key, value] of Object.entries(profile.env)) if (typeof value !== "string") issues.push({
+		field: "env",
+		message: `Env var "${key}" must be a string.`
+	});
+	for (const flag of profile.flags) if (!flag.startsWith("-")) issues.push({
+		field: "flags",
+		message: `Flag "${flag}" must start with "-".`
+	});
+	return {
+		valid: issues.length === 0,
+		issues
+	};
+}
+//#endregion
+//#region src/manifest.ts
+/**
+* This package's own `subshell` block, read from its package.json so the
+* manifest has ONE source of truth.
+*
+* A host that installs this plugin at runtime reads package.json off disk; a
+* host that ships it built in imports this. Both must describe the same
+* plugin, and the only way to guarantee that is for them to be the same bytes.
+*/
+const parsed = parseManifest({
+	name: "@subshell-ai/plugin-codex",
+	description: "Codex harness plugin for Subshell",
+	version: "0.0.1",
+	license: "Apache-2.0",
+	type: "module",
+	main: "dist/index.js",
+	exports: { ".": {
+		"types": "./dist/index.d.ts",
+		"import": "./dist/index.js"
+	} },
+	types: "dist/index.d.ts",
+	scripts: {
+		"build": "tsdown",
+		"build:dev": "hash-runner",
+		"clean": "rm -rf .turbo node_modules dist .hashes.json",
+		"lint": "biome check --write --unsafe src && biome format src --write && biome lint src --fix",
+		"lint:check": "biome check --no-errors-on-unmatched src",
+		"lint:staged": "biome check --no-errors-on-unmatched --write --unsafe --staged src",
+		"test": "bun test",
+		"verify-types": "tsc --project tsconfig.json --noEmit"
+	},
+	devDependencies: {
+		"@internal/tsconfig": "workspace:*",
+		"@subshell-ai/plugin-api": "workspace:*",
+		"@types/bun": "1.3.14",
+		"hash-runner": "4.0.0",
+		"tsdown": "0.22.14",
+		"typescript": "7.0.2"
+	},
+	files: ["dist"],
+	publishConfig: { "access": "public" },
+	subshell: {
+		"apiVersion": 1,
+		"id": "codex",
+		"type": "agent-harness",
+		"name": "Codex",
+		"description": "OpenAI's agentic coding CLI (interactive TUI)",
+		"icon": "📖",
+		"entry": "dist/index.js",
+		"detect": {
+			"binaryName": "codex",
+			"envOverride": "CODEX_PATH",
+			"knownPaths": [
+				".local/bin/codex",
+				".npm-global/bin/codex",
+				".bun/bin/codex"
+			]
+		},
+		"install": {
+			"command": "curl -fsSL https://chatgpt.com/codex/install.sh | sh",
+			"docsUrl": "https://learn.chatgpt.com/docs/codex/cli"
+		}
+	}
+});
+if ("error" in parsed) throw new Error(`@subshell-ai/plugin-codex has an invalid manifest: ${parsed.error}`);
+const manifest = parsed;
+//#endregion
+//#region src/index.ts
+/** Known Codex settings, applied as per-invocation CLI flags. */
+const CODEX_SETTINGS_FIELDS = [
+	{
+		key: "model",
+		label: "Model",
+		description: "Model name passed as -m/--model (e.g. 'gpt-5-codex')",
+		type: "string"
+	},
+	{
+		key: "sandbox",
+		label: "Sandbox",
+		description: "What the agent may touch without asking (-s/--sandbox)",
+		type: "select",
+		choices: [
+			"read-only",
+			"workspace-write",
+			"danger-full-access"
+		]
+	},
+	{
+		key: "askForApproval",
+		label: "Ask for approval",
+		description: "When codex pauses for a human decision (-a/--ask-for-approval)",
+		type: "select",
+		choices: ["on-request", "never"]
+	}
+];
+const SUGGESTED_ENV = [{
+	key: "OPENAI_API_KEY",
+	description: "API key for the api-key login mode (else ChatGPT sign-in)"
+}];
+const SUGGESTED_FLAGS = [
+	{
+		flag: "--search",
+		description: "Enable live web search"
+	},
+	{
+		flag: "-p work",
+		description: "Apply a profile from ~/.codex/config.toml"
+	},
+	{
+		flag: "-c mcp_servers.foo.command=\"/usr/bin/foo\"",
+		description: "One-off config override (dotted path, value parsed as TOML)"
+	}
+];
+/** A TOML basic string from an ASCII-safe JS string. */
+function tomlString(value) {
+	return JSON.stringify(value);
+}
+/** A TOML inline array of basic strings — same JSON-compatibility argument. */
+function tomlStringArray(values) {
+	return `[${values.map(tomlString).join(", ")}]`;
+}
+/**
+* Built-in harness: Codex (OpenAI's `@openai/codex` CLI).
+*
+* Launch shape:
+*   codex [-m <model>] [-s <sandbox>] [-a <approval>] [mcp -c pairs]
+*         [profile flags] [extra flags]
+* A bare launch (no subcommand, no prompt) opens the interactive TUI. Codex
+* has no create-time flag for naming its own session and no way to pin a
+* conversation id, so neither the subshell name nor a resume capability is
+* forwarded — restarts start a fresh conversation (the documented default).
+* The pane's
+* cwd is already the working directory, so `-C/--cd` is never passed, and
+* `--dangerously-bypass-approvals-and-sandbox` is NEVER baked into a launch
+* (a user may put it in their own profile flags — that is their call).
+*
+* subshell MCP is wired automatically WITHOUT touching user state: every
+* launch carries `-c mcp_servers.subshell.command=… -c mcp_servers.subshell.args=…`
+* config overrides (dotted path, value parsed as TOML — verified against the
+* real binary), which codex merges over ~/.codex/config.toml for that run
+* only. No config file the harness must read, no CODEX_HOME redirect (that
+* dir holds the user's auth.json). The spawned `subshell mcp` child inherits
+* the subshell's baked SUBSHELL_* pane env for its credential, like every
+* harness.
+* (Flags/values verified against @openai/codex 2026-09 help output.)
+*
+* Identity, detection and install guidance live in this package's
+* package.json `subshell` block, NOT here: the host reads them without
+* importing or executing a line of this file.
+*
+* `host` carries what this module cannot import. See `@subshell-ai/plugin-api`.
+*/
+const createPlugin = (_host) => ({
+	capabilities: () => ["mcp", "settings"],
+	buildCommand(input) {
+		const { binary, profile, extraFlags, mcp } = input;
+		const args = [binary];
+		const s = profile.settings ?? {};
+		if (typeof s.model === "string" && s.model) args.push("-m", s.model);
+		if (typeof s.sandbox === "string" && s.sandbox) args.push("-s", s.sandbox);
+		if (typeof s.askForApproval === "string" && s.askForApproval) args.push("-a", s.askForApproval);
+		if (mcp?.args) args.push(...mcp.args);
+		for (const flag of profile.flags) args.push(flag);
+		if (extraFlags) args.push(...extraFlags);
+		return args;
+	},
+	/**
+	* Codex config fragment registering subshell as a stdio MCP server — the
+	* exact `[mcp_servers.subshell]` block `~/.codex/config.toml` expects. The
+	* block is NOT what activates the server on subshell launches: `buildCommand`
+	* splices live `-c` overrides instead (see the module doc), so this file is a
+	* manual-setup reference a user may append to their own config.
+	*/
+	mcpRegistration(launch, _configPath) {
+		return {
+			fileContent: [
+				"# Subshell: cross-subshell MCP server, in the shape ~/.codex/config.toml expects.",
+				"#",
+				"# This file is a MANUAL-SETUP REFERENCE ONLY: subshell's own launches pass the",
+				"# live values as `-c mcp_servers.subshell.*=…` per-invocation overrides, so codex",
+				"# never reads this file. To register subshell permanently (e.g. terminal codex),",
+				"# append the block below to ~/.codex/config.toml.",
+				"",
+				`[mcp_servers.${MCP_SERVER_NAME}]`,
+				`command = ${tomlString(launch.command)}`,
+				`args = ${tomlStringArray(launch.args)}`,
+				""
+			].join("\n"),
+			args: [
+				"-c",
+				`mcp_servers.${MCP_SERVER_NAME}.command=${tomlString(launch.command)}`,
+				"-c",
+				`mcp_servers.${MCP_SERVER_NAME}.args=${tomlStringArray(launch.args)}`
+			],
+			env: void 0
+		};
+	},
+	/** Auto: `buildCommand` wires `-c mcp_servers.subshell.*` into every subshell. */
+	mcpSetup(_launch) {
+		return {
+			mode: "auto",
+			summary: "Subshell registers itself with every Codex subshell automatically (per-invocation -c mcp_servers.subshell.* overrides; your ~/.codex config is never modified)."
+		};
+	},
+	validateProfile(profile) {
+		return validateGenericProfile(profile);
+	},
+	profileSettings() {
+		return CODEX_SETTINGS_FIELDS;
+	},
+	suggestedEnv() {
+		return SUGGESTED_ENV;
+	},
+	suggestedFlags() {
+		return SUGGESTED_FLAGS;
+	}
+});
+//#endregion
+export { createPlugin as default, manifest };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@subshell-ai/plugin-codex",
+  "description": "Codex harness plugin for Subshell",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsdown",
+    "build:dev": "hash-runner",
+    "clean": "rm -rf .turbo node_modules dist .hashes.json",
+    "lint": "biome check --write --unsafe src && biome format src --write && biome lint src --fix",
+    "lint:check": "biome check --no-errors-on-unmatched src",
+    "lint:staged": "biome check --no-errors-on-unmatched --write --unsafe --staged src",
+    "test": "bun test",
+    "verify-types": "tsc --project tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@internal/tsconfig": "workspace:*",
+    "@subshell-ai/plugin-api": "workspace:*",
+    "@types/bun": "1.3.14",
+    "hash-runner": "4.0.0",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "subshell": {
+    "apiVersion": 1,
+    "id": "codex",
+    "type": "agent-harness",
+    "name": "Codex",
+    "description": "OpenAI's agentic coding CLI (interactive TUI)",
+    "icon": "\ud83d\udcd6",
+    "entry": "dist/index.js",
+    "detect": {
+      "binaryName": "codex",
+      "envOverride": "CODEX_PATH",
+      "knownPaths": [
+        ".local/bin/codex",
+        ".npm-global/bin/codex",
+        ".bun/bin/codex"
+      ]
+    },
+    "install": {
+      "command": "curl -fsSL https://chatgpt.com/codex/install.sh | sh",
+      "docsUrl": "https://learn.chatgpt.com/docs/codex/cli"
+    }
+  }
+}