@subshell-ai/plugin-oh-my-pi 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,670 @@
+//#region ../../plugin-api/dist/types-CW2dMAMW.d.ts
+/** How the plugin learns about children: harness lifecycle hooks, or a loaded extension. */
+type HarnessSubagentDiscovery = "hooks" | "extension";
+/** Whether the sidebar can move the parent's own view to a child, or the harness keeps that in-app. */
+type HarnessSubagentNavigation = "native" | "unavailable";
+/**
+ * What a plugin declares about its harness's child agents. The host uses
+ * `discovery`/`navigation` to decide what the sidebar may offer; `setup`, when
+ * the harness needs a one-time human act (trusting hooks, installing an
+ * extension), is the copy the preset editor shows for that act.
+ */
+interface HarnessSubagentSupport {
+  /** How subagent lifecycle events reach Subshell */
+  discovery: HarnessSubagentDiscovery;
+  /** Whether subshell may navigate the parent's own view to a child */
+  navigation: HarnessSubagentNavigation;
+  /** One-time user action required for reporting to work, if any */
+  setup?: string;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * 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.
+ *
+ * ONE exception, and it is structural rather than a branch on a label: a
+ * `network` plugin implements {@link NetworkPlugin} instead of
+ * {@link SubshellPlugin}, so the loader picks WHICH members to require by
+ * type. A harness drives a thing in a pane; a network plugin connects this
+ * host to one network. They share the store, the manifest and the capability
+ * vocabulary, and nothing else.
+ */
+type PluginType = "agent-harness" | "terminal" | "network";
+/**
+ * What a plugin can DO. The launch pipeline and the UI read this; neither
+ * branches on {@link PluginType}.
+ *
+ * The union is shared across types and the applicable SUBSET is not, so
+ * {@link capabilityMismatches} takes the type: a harness claiming `publish`
+ * and a network plugin claiming `resume` are both refused at load, for the
+ * same reason a claimed-but-unimplemented capability is.
+ */
+type PluginCapability = "mcp" | "resume" | "attention" | "subagents" | "publish" | "supervise" | "guard" | "settings";
+/** A harness preset as defined by the user (decoded JSON blobs). */
+interface PresetDefinition {
+  /** Human-friendly preset 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 preset's config sources apply (isolation) */
+  configIsolation: boolean;
+  /** If true, new subshells from this preset auto-restart on exit */
+  restartOnExit?: boolean;
+}
+/** Snapshot of a single field-level validation error on a preset. */
+interface PresetValidationIssue {
+  /** Field name (e.g. "name", "env", "settings") */
+  field: string;
+  /** Human-readable problem description */
+  message: string;
+}
+interface PresetValidationResult {
+  valid: boolean;
+  issues: PresetValidationIssue[];
+}
+/** 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 preset being used */
+  preset: PresetDefinition;
+  /** 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.resumePath}
+   * pointed at a file the host found there).
+   */
+  harnessSession?: {
+    id: string;
+    mode: "start" | "resume";
+  };
+  /**
+   * How a harness hook re-enters the subshell binary on the PANE's machine, as
+   * the host resolved it for that machine: `{ command, args }` with the
+   * reporting subcommand already appended, so a plugin adds only its own verb
+   * words. Splice it into whatever hook mechanism the harness has.
+   *
+   * A hook runs where the pane runs, and the only program guaranteed to exist
+   * there is the binary that launched the pane — which is why this arrives
+   * from the host rather than being a command a plugin writes for itself. The
+   * hooks here were once `bun -e '<inlined JS>'`, and every machine without a
+   * bun on its PATH (i.e. most of them) opened its harness on
+   * `bun: command not found`.
+   *
+   * Undefined means the host could not resolve one. OMIT the hooks then: a
+   * command the pane cannot run costs the same signal and adds an error to
+   * every session.
+   */
+  reporter?: ReporterSpec;
+}
+/**
+ * A command prefix that re-enters the subshell binary on a pane's machine,
+ * ready for a plugin's own verb words to be appended.
+ *
+ * Shaped like {@link McpLaunchSpec} and resolved from the same host question
+ * ("am I a compiled binary, or is `bun` running my entry script?"), but kept
+ * separate because they carry different subcommands and the MCP one is
+ * operator-overridable while this one is not.
+ */
+interface ReporterSpec {
+  /** Executable to run (the binary itself, or the interpreter running it). */
+  command: string;
+  /** Everything before the plugin's verb words (any entry script, then the subcommand). */
+  args: string[];
+}
+/**
+ * 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 resumePath} before every
+ * restart to choose between continuing and starting fresh.
+ *
+ * Both members are PURE, and that is the load-bearing property (spec
+ * 2026-09-10 §5): a resume runs on the CONTROL PLANE, for a pane that lives on
+ * a machine the plane cannot see. Computing (rather than checking) is what
+ * lets one plugin implementation serve local and remote restarts identically.
+ */
+interface HarnessResume {
+  /** Allocates the HARNESS conversation id to pin at launch (a uuid for claude). */
+  allocateHarnessSessionId(): string;
+  /**
+   * Where the resumable transcript would be, given the target machine's
+   * environment. PURE: it computes a path and never touches a filesystem, so
+   * the control plane can build it for a machine it cannot see. The HOST
+   * checks existence.
+   */
+  resumePath(harnessSessionId: string, cwd: string, hostEnv: HostEnv): string;
+}
+/** The parts of a target machine's environment a plugin may compute against. */
+interface HostEnv {
+  /** The node's home directory */
+  homeDir: string;
+  /** Values for the variables this plugin's manifest declared it needs */
+  env: Record<string, string>;
+}
+/** 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 {
+  /**
+   * Companion integration modules written next to the config file, under
+   * `<configPath>.d/`. Keys are basenames only, and the host refuses a name
+   * outside `[A-Za-z0-9_-]+\.(mjs|py|json)`, more than eight files, or more
+   * than 64 KiB of content — by throwing at launch, so the registration must
+   * stay inside those rules. Each file ships self-contained: on a pane's
+   * machine nothing of ours is importable (see the package doc).
+   */
+  files?: Record<string, string>;
+  /** 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 layers it AFTER preset env in the pane's
+   * environment: the wiring wins on purpose, so the harness always finds the
+   * config this launch wrote even when a preset sets the same name. Plugins
+   * never read it back.
+   */
+  env?: Record<string, string>;
+}
+/** One copy-paste line shown in the preset 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, secret.
+   *
+   * `secret` is WRITE-ONLY and network-only: the host stores it through
+   * {@link PluginHost.secrets} rather than in the settings object, reads
+   * report only whether one is set, and a plugin never receives the value —
+   * it names the secret and the host hydrates it into a process it spawns
+   * ({@link SupervisedProcessSpec}). The preset editor does not render this
+   * type; a harness declaring one is a bug rather than a second secret store.
+   */
+  type: "string" | "boolean" | "number" | "select" | "secret";
+  /** Choices when type === "select" */
+  choices?: string[];
+  /** True when the field must be set before the plugin can act */
+  required?: boolean;
+  /** Placeholder / example, shown in the editor. Never a real credential. */
+  placeholder?: 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;
+  };
+  /**
+   * Runs a command to completion under the host's bounds and reports it.
+   *
+   * The one way a plugin executes anything. A plugin does not spawn: the host
+   * owns the deadline, the environment allowlist (the process's own
+   * environment holds the auth secret and the database path, and is never
+   * handed over), the PATH a service-run server would otherwise lack, and the
+   * output cap. Two refusals throw rather than returning a result, because
+   * both are bugs in the plugin rather than outcomes: `argv[0]` that is not an
+   * ABSOLUTE path (resolve it with {@link findBinary} — a bare name would
+   * resolve against a PATH the plugin cannot see), and `argv[0]` that is
+   * `sudo`. The server has no terminal to answer a password prompt, so a
+   * privileged command is a copy-paste instruction for the operator and never
+   * something this runs.
+   *
+   * Long-running processes are NOT this: a plugin that needs one describes it
+   * ({@link SupervisedProcessSpec}) and the host supervises it.
+   * @since apiVersion 2
+   */
+  run(argv: string[], opts?: RunOptions): Promise<RunResult>;
+  /**
+   * Write-only credential storage, scoped to this plugin.
+   *
+   * There is deliberately NO `get`. A plugin that could read a credential
+   * could put it in an argv (visible in `ps`), a log line or a hint string;
+   * every legitimate consumer is a process the HOST spawns, so the host
+   * hydrates the value itself from the name the plugin gives it. Values are
+   * stored 0600 under the host's data directory, never in the database and
+   * never in a settings row.
+   * @since apiVersion 2
+   */
+  secrets: PluginSecrets;
+  /** The operating system this host runs on. */
+  readonly platform: PluginPlatform;
+  /** The home directory of the user this host runs as. */
+  readonly homeDir: string;
+}
+/** Where a plugin can be driven at all. Mirrors the manifest's `platforms`. */
+type PluginPlatform = "darwin" | "linux";
+/** Options for {@link PluginHost.run}. */
+interface RunOptions {
+  /** Deadline in milliseconds. Default 30_000; the host caps it at 10 minutes. */
+  timeoutMs?: number;
+  /** Called per output line, ANSI already stripped, from both streams interleaved. */
+  onLine?: (line: string) => void;
+  /**
+   * Ends the run early without failing it.
+   *
+   * What an interactive login needs: `tailscale up` with no key blocks until a
+   * human finishes in a browser, having already printed the URL — so the
+   * plugin reads the URL off {@link onLine} and aborts, leaving the daemon
+   * waiting. An aborted run reports `aborted: true` and whatever was captured.
+   */
+  signal?: AbortSignal;
+  /** Extra environment on top of the host's allowlist. Never overrides PATH. */
+  env?: Record<string, string>;
+  /** Text to write to stdin. Absent means stdin is /dev/null, so a prompt cannot hang forever. */
+  stdin?: string;
+}
+/** What {@link PluginHost.run} reports. Never throws for a non-zero exit. */
+interface RunResult {
+  /** Exit code, or null when the process was signalled or never started. */
+  code: number | null;
+  /** Captured stdout, ANSI stripped, capped. */
+  stdout: string;
+  /** Captured stderr, ANSI stripped, capped. */
+  stderr: string;
+  /** True when the deadline ended it. */
+  timedOut: boolean;
+  /** True when {@link RunOptions.signal} ended it. */
+  aborted: boolean;
+}
+/** Write-only, per-plugin credential storage. See {@link PluginHost.secrets}. */
+interface PluginSecrets {
+  /** Stores (or replaces) a credential under this name. */
+  set(name: string, value: string): Promise<void>;
+  /** Whether a credential is stored under this name. The only read there is. */
+  has(name: string): Promise<boolean>;
+  /** Removes it. Absent is not an error. */
+  delete(name: string): Promise<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 {
+  /** Native child-agent reporting and optional in-place navigation. */
+  subagents?: HarnessSubagentSupport;
+  /** Builds the argv (no shell) used to launch a subshell. */
+  buildCommand(input: BuildCommandInput): string[];
+  /** Validates a preset definition before saving. */
+  validatePreset(preset: PresetDefinition): PresetValidationResult;
+  /** 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. `reporter` is the host-resolved command prefix that
+   * re-enters the subshell binary on a pane's machine (same shape as
+   * {@link BuildCommandInput.reporter}), present only when the host could
+   * resolve one: use it to render hook-configuration steps, and omit those
+   * steps when it is absent rather than guessing a binary name.
+   */
+  mcpSetup?(launch: McpLaunchSpec, reporter?: ReporterSpec): McpSetupInfo;
+  /** Settings rendered in the PRESET editor and stored on the preset. */
+  presetSettings?(): SettingsField[];
+  /** Known extra env var suggestions for the preset editor. */
+  suggestedEnv?(): {
+    key: string;
+    description: string;
+  }[];
+  /** Known CLI flag suggestions for the preset editor. */
+  suggestedFlags?(): {
+    flag: string;
+    description: string;
+  }[];
+}
+/**
+ * A factory that returns a harness, for a plugin that knows which it is.
+ *
+ * {@link PluginFactory} is the LOADER's view — it must accept either shape,
+ * because it decides which to expect from the manifest. A plugin itself has no
+ * such ambiguity, and annotating its own factory with the union would widen
+ * what its tests can call: `createPlugin(host).buildCommand(...)` stops
+ * type-checking on a value that might be a network plugin. So a plugin
+ * declares the half it implements and the loader keeps the union.
+ */
+type HarnessPluginFactory = (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, tried after PATH and before the version managers.
+   *
+   * HOME-relative (`.local/bin/mytool`), or ABSOLUTE when the entry starts
+   * with `/` — which is how a vendor's GUI install is named, since
+   * `/Applications/Tailscale.app/Contents/MacOS/Tailscale` is nobody's HOME.
+   * Each is a candidate to search, so an entry that does not resolve costs
+   * nothing and the ladder carries on.
+   */
+  knownPaths: string[];
+}
+/** Where to send someone whose binary is missing. */
+interface InstallSpec {
+  /**
+   * Copy-pasteable install command for the official installer.
+   *
+   * A command the HOST may run on request, which is why it may not be
+   * privileged: `sudo`, `doas` and `pkexec` are refused by the parser at any
+   * command boundary (the line is run through a shell — see
+   * {@link needsPrivileges}), so an installer that needs root is described
+   * under {@link NetworkManifest.privileged} instead and is only ever shown to
+   * copy. Without that refusal the two would be one field with two meanings,
+   * and the surface offering a button would have to guess.
+   */
+  command: string;
+  /**
+   * URL of the installation documentation.
+   *
+   * Rendered as a link on an admin page, so it must be `http:` or `https:`
+   * and the parser refuses anything else — see {@link isDocsUrl}.
+   */
+  docsUrl: string;
+}
+/** One step an operator must run themselves, because the host may not. */
+interface PrivilegedStep {
+  /** What it does, in a few words: "Install the daemon" */
+  label: string;
+  /** The command to copy. Usually `sudo …`. */
+  command: string;
+  /** Where the vendor documents it; `http:`/`https:` only, as {@link isDocsUrl} requires. */
+  docsUrl?: string;
+  /**
+   * Which ALTERNATIVE this step belongs to, and the heading it renders under.
+   *
+   * Steps sharing a group are one sequence to run in order; different groups
+   * are different ways to arrive at the same place, and a surface renders an
+   * `or` between them rather than continuing the numbering. Steps with no
+   * group are one plain sequence, which is what every step was before this
+   * existed.
+   *
+   * It exists because a platform can genuinely offer two routes: on macOS
+   * Tailscale ships both a GUI app and a command-line daemon, and a page that
+   * numbered those 1..3 told a person to install both. Non-empty when present
+   * — it is a heading, so `""` is refused rather than coerced.
+   */
+  group?: string;
+}
+/**
+ * The `subshell.network` block. Required when `type` is `network`.
+ *
+ * Everything here is DATA a host reads without loading plugin code: which
+ * machines this plugin can run on at all, whether it can produce a login URL,
+ * what publishing it exposes, and which steps only a human with root can
+ * perform. A page can therefore say "not available on this platform" or print
+ * the two sudo commands before any plugin code has been imported — and before
+ * the vendor's CLI is anywhere on the machine.
+ */
+interface NetworkManifest {
+  /**
+   * Operating systems this plugin can be driven on.
+   *
+   * Not a hint: a host refuses every act on a platform absent from this list,
+   * and the UI renders the row as unavailable rather than offering a button
+   * that would 409. Vendors differ here for real reasons — a CLI that talks to
+   * a logged-in desktop session cannot be driven from a launchd service.
+   */
+  platforms: PluginPlatform[];
+  /**
+   * True when `join({})` with no credential can yield a URL a human finishes.
+   *
+   * Data rather than a capability because it describes what a RETURN VALUE may
+   * be, and a capability is checked against members. The UI reads it to decide
+   * whether to offer "sign in" beside "paste a key".
+   */
+  interactiveLogin?: boolean;
+  /**
+   * True when publishing leaves NOTHING the daemon can later be asked about.
+   *
+   * NetBird is the case that forced the field: a join is the whole publish,
+   * so `status()` can only ever see the join, and a plugin that declared
+   * itself `published` would claim a thing its own vendor CLI never told it.
+   * The HOST's publish record is the one witness of the transition, and this
+   * flag is what lets the host (and only the host) upgrade `joined` to
+   * `published` from it. A plugin without the flag is never upgraded: for
+   * Tailscale a serve reset outside this app is a real state, and `joined`
+   * is the honest reading of it.
+   */
+  publishImplicit?: boolean;
+  /**
+   * What publishing on this network exposes the server to.
+   *
+   * `private` is a network only invited machines are on. `public-with-gate`
+   * reaches the open internet with an identity check in front — a different
+   * security posture, stated here so every surface can say so before the act
+   * rather than after it.
+   */
+  exposure: "private" | "public-with-gate";
+  /**
+   * Steps the host can never perform, per platform, in the order to run them.
+   *
+   * Every mesh VPN installs a daemon as root and the server has no terminal to
+   * answer a password prompt, so these are printed to copy and never executed.
+   * Keeping them out of {@link InstallSpec} is what lets a surface offer a
+   * button for one and a copy row for the other without inspecting the string.
+   */
+  privileged?: Partial<Record<PluginPlatform, PrivilegedStep[]>>;
+  /**
+   * What this network calls the two things a person acts on.
+   *
+   * Vendors name the same act differently and a generic word is wrong rather
+   * than merely bland: Tailscale takes an "auth key", NetBird a "setup key",
+   * Cloudflare a "tunnel token", and a field labelled "Auth key" on the
+   * NetBird row asks for something NetBird does not have. Likewise publishing
+   * is "Tailscale Serve" on one network and starting a tunnel on another.
+   *
+   * MANIFEST data rather than something the plugin returns, for the same
+   * reason `platforms` is: a surface renders these before any plugin code has
+   * been loaded, and before the vendor's CLI is anywhere on the machine. Both
+   * are optional and both have a sensible generic default, so a plugin that
+   * says nothing is merely plain rather than broken.
+   */
+  labels?: NetworkLabels;
+}
+/** The vendor's own words for the two acts a person takes. See {@link NetworkManifest.labels}. */
+interface NetworkLabels {
+  /** What to call the pasted credential: "Auth key", "Setup key", "Tunnel token". */
+  credential?: string;
+  /** What to call publishing: "Publish with Tailscale Serve", "Start tunnel". */
+  publish?: string;
+  /**
+   * Where the credential named by `credential` comes from — the vendor page
+   * that mints one.
+   *
+   * The credential box asks for an "Auth key" on a card that otherwise says
+   * nothing about what an auth key is or where to get it, and every vendor
+   * words that differently enough that the SPA cannot write the sentence
+   * itself. So the plugin names its page, and the card renders it as a Docs
+   * link on the label row. http(s) only, refused at parse like every other
+   * URL this contract carries — it lands in an `href` on an admin page.
+   */
+  credentialDocsUrl?: 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;
+  /**
+   * Relative path to this plugin's icon file, e.g. `icon.svg`. Served by
+   * the control plane at `/api/plugins/<id>/icon`; absent means the UI
+   * renders a monogram instead.
+   */
+  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;
+  /**
+   * Environment variables this plugin computes against (spec 2026-09-10 §5).
+   *
+   * The node reports the VALUES of exactly these names at `ready`, so the
+   * reported set grows by declaration rather than a machine shipping its
+   * whole environment to the control plane. Declaring data is deliberate: a
+   * WRONG name is silent, yielding an absent key and the plugin's own
+   * fallback, i.e. a resume that quietly never offers itself (§11).
+   */
+  hostEnv?: string[];
+  /** Network facts. Present exactly when `type` is `network`. */
+  network?: NetworkManifest;
+  /**
+   * False means the launch pickers must not offer this plugin, even though
+   * it drives a pane. Absent means true.
+   *
+   * The declaration belongs to the plugin because only it knows whether a
+   * bare launch means something: a harness whose useful launch needs inputs
+   * no picker carries (SSH needs a destination, which the connect form
+   * supplies through its own door) would otherwise be a row that starts a
+   * dying pane. This hides the entry, not the route: the plugin stays
+   * launchable by id for whatever flow does supply the inputs.
+   */
+  pickable?: boolean;
+}
+//#endregion
+//#region src/manifest.d.ts
+declare const manifest: SubshellManifest;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Oh My Pi uses its own executable and native MCP discovery, independently of
+ * pi. An explicit extension directory contributes mcp.json without redirecting
+ * the user's config or credentials. Verified against omp 18.12.6.
+ */
+declare const createPlugin: HarnessPluginFactory;
+//#endregion
+export { createPlugin as default, manifest };