@ken-jo/agent-connector 0.3.0 → 0.4.0

package/dist/roo-code-GWSNU3OW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/roo-code/index.ts"],"sourcesContent":["/**\n * adapters/roo-code — Roo Code (VS Code extension) platform adapter.\n *\n * Roo Code (rooveterinaryinc.roo-cline) is a Cline-fork VS Code extension and an\n * **mcp-only** host from agent-connector's perspective: it exposes no lifecycle\n * hook system, so MCP server registration is the only thing we install and hooks\n * are reported unavailable. This mirrors the Warp reference adapter exactly.\n *\n * MCP config (vsix 3.54.0):\n *   - user scope    → <vscodeUserDir>/globalStorage/rooveterinaryinc.roo-cline/\n *                     settings/mcp_settings.json   (renamed in 3.54.0 from the\n *                     older `cline_mcp_settings.json`; we PROBE both on detection\n *                     — the extension migrates the old name at startup — and\n *                     WRITE the new `mcp_settings.json`)\n *   - project scope → <projectDir>/.roo/mcp.json\n *   Both are JSON, root key \"mcpServers\".\n *\n * VS Code user-dir resolution (cross-OS):\n *   - macOS   → ~/Library/Application Support/Code/User\n *   - Linux   → ~/.config/Code/User\n *   - Windows → %APPDATA%/Code/User  (falls back to ~/AppData/Roaming/Code/User)\n *   We deliberately target stable VS Code (\"Code\"), the documented home for the\n *   published Roo Code extension's globalStorage. Insiders/forks would live under\n *   a sibling dir but are out of scope for the default path.\n *\n * Env interpolation: Roo Code's settings file documents no native `${env:VAR}`\n * token (the entries are plain command/args/env literals), so we resolve every\n * `${env:VAR}` reference to a literal at install time — the no-native-token path.\n *\n * The hook \"config path\" is the SAME MCP settings file (there is no hook file),\n * so the generic doctor/backup behave sensibly.\n */\n\nimport { existsSync } from \"node:fs\";\nimport { homedir, platform as osPlatform } from \"node:os\";\nimport { join } from \"node:path\";\n\nimport { BaseAdapter } from \"../base.js\";\nimport type { Adapter, InstallContext, MemoryTarget } from \"../spi.js\";\nimport type {\n  ChangeRecord,\n  CommandDef,\n  DetectedPlatform,\n  HealthCheck,\n  HookParadigm,\n  PlatformCapabilities,\n  PlatformId,\n  ServerDef,\n  SkillDef,\n  Transport,\n} from \"../../core/types.js\";\nimport { resolveEnvRefsDeep } from \"../../core/interpolate.js\";\nimport {\n  buildServeWrapperCommand,\n  shouldWrapForTelemetry,\n} from \"../../core/spawn.js\";\n\nconst HOST: PlatformId = \"roo-code\";\nconst MCP_ROOT_KEY = \"mcpServers\";\n\n/** Roo Code extension id → its VS Code globalStorage folder. */\nconst ROO_EXTENSION_ID = \"rooveterinaryinc.roo-cline\";\n/** User-scope MCP settings filename — renamed in vsix 3.54.0. */\nconst MCP_SETTINGS_FILE = \"mcp_settings.json\";\n/** Legacy filename (pre-3.54.0) — probed on detection for older installs. */\nconst LEGACY_MCP_SETTINGS_FILE = \"cline_mcp_settings.json\";\n\n/**\n * Native MCP server entry shapes Roo Code accepts under `mcpServers`.\n * We write the minimal stdio shape { command, args, env, disabled }; Roo Code\n * also accepts optional `alwaysAllow` / `timeout`, which we intentionally omit.\n */\ninterface RooStdioServer {\n  command: string;\n  args?: string[];\n  env?: Record<string, string>;\n  disabled: boolean;\n}\ninterface RooHttpServer {\n  url: string;\n  headers?: Record<string, string>;\n  disabled: boolean;\n}\n\n/**\n * Resolve the cross-OS VS Code per-user data directory (the \"User\" folder that\n * contains `globalStorage`). See module header for the per-platform mapping.\n */\nfunction vscodeUserDir(): string {\n  const home = homedir();\n  switch (osPlatform()) {\n    case \"darwin\":\n      return join(home, \"Library\", \"Application Support\", \"Code\", \"User\");\n    case \"win32\": {\n      const appData =\n        process.env.APPDATA ?? join(home, \"AppData\", \"Roaming\");\n      return join(appData, \"Code\", \"User\");\n    }\n    default:\n      // Linux / other POSIX: XDG-style config dir.\n      return join(home, \".config\", \"Code\", \"User\");\n  }\n}\n\nexport class RooCodeAdapter extends BaseAdapter implements Adapter {\n  readonly id: PlatformId = HOST;\n  readonly name = \"Roo Code\";\n  readonly paradigm: HookParadigm = \"mcp-only\";\n\n  readonly capabilities: PlatformCapabilities = {\n    // Memory surface: AGENTS.md-first managed block (project <projectDir>/AGENTS.md\n    // via the base default — Roo's \"Agent Rules standard\" support is default-on;\n    // user scope → ~/.roo/rules/agent-connector.md below).\n    supportsMemory: true,\n    // Roo Code has no lifecycle hook system — every hook capability is false.\n    preToolUse: false,\n    postToolUse: false,\n    preCompact: false,\n    sessionStart: false,\n    sessionEnd: false,\n    userPromptSubmit: false,\n    stop: false,\n    notification: false,\n    canModifyArgs: false,\n    canModifyOutput: false,\n    canInjectSessionContext: false,\n    // Roo Code registers stdio, SSE, and Streamable HTTP MCP servers.\n    transports: [\"stdio\", \"sse\", \"http\"],\n    // Content surfaces: Roo Code reads custom slash commands and AgentSkills from\n    // its `.roo` config dir (BOTH user ~/.roo and project <projectDir>/.roo).\n    //   command → <configDir>/commands/<name>.md  (md+optional frontmatter)\n    //   skill   → <configDir>/skills/<name>/SKILL.md (+ resources)\n    supportsCommands: true,\n    supportsSkills: true,\n  };\n\n  // ── Detection ────────────────────────────────────────────────────────────\n\n  detectInstalled(projectDir: string): DetectedPlatform {\n    const userSettings = this.userSettingsPath();\n    const userExtDir = join(\n      vscodeUserDir(),\n      \"globalStorage\",\n      ROO_EXTENSION_ID,\n    );\n    // Probe the legacy filename too (3.54.0 migrates it at startup) so an older\n    // install is still recognized; we WRITE the new mcp_settings.json.\n    const userLegacySettings = join(\n      userExtDir,\n      \"settings\",\n      LEGACY_MCP_SETTINGS_FILE,\n    );\n    const projectMcp = join(projectDir, \".roo\", \"mcp.json\");\n\n    const userMatch =\n      existsSync(userSettings) ||\n      existsSync(userLegacySettings) ||\n      existsSync(userExtDir);\n    const projectMatch = existsSync(projectMcp);\n    const installed = userMatch || projectMatch;\n\n    // Prefer the user scope/path when present; otherwise surface the project one.\n    const scope = userMatch || !projectMatch ? \"user\" : \"project\";\n    const configPath = scope === \"user\" ? userSettings : projectMcp;\n    const reason = installed\n      ? userMatch\n        ? `found Roo Code globalStorage under ${userExtDir}`\n        : `found Roo Code project config at ${projectMcp}`\n      : `no Roo Code config at ${userExtDir} or ${projectMcp}`;\n\n    return {\n      id: this.id,\n      name: this.name,\n      installed,\n      paradigm: this.paradigm,\n      capabilities: this.capabilities,\n      configPath,\n      scope,\n      reason,\n      confidence: installed ? \"high\" : \"low\",\n    };\n  }\n\n  // ── Native paths ─────────────────────────────────────────────────────────\n\n  /** Absolute path to the user-scope MCP settings file (VS Code globalStorage). */\n  private userSettingsPath(): string {\n    return join(\n      vscodeUserDir(),\n      \"globalStorage\",\n      ROO_EXTENSION_ID,\n      \"settings\",\n      MCP_SETTINGS_FILE,\n    );\n  }\n\n  // ── Memory surface: global rules dir at user scope ──────────────────────\n  // Project scope stays on the AGENTS.md base default (\"Agent Rules standard\",\n  // default-on). User scope targets a dedicated agent-connector.md in Roo's\n  // documented ~/.roo/rules/ dir (files concatenated; AC-created → cleanly\n  // deletable on uninstall).\n  protected override memoryTargets(ctx: InstallContext): MemoryTarget[] {\n    if (this.memoryOverride(ctx)?.path || ctx.scope !== \"user\") {\n      return super.memoryTargets(ctx);\n    }\n    return [\n      {\n        path: join(homedir(), \".roo\", \"rules\", \"agent-connector.md\"),\n        reason: \"roo-code global rules dir (~/.roo/rules; agent-connector-owned file)\",\n      },\n    ];\n  }\n\n  getConfigDir(ctx: InstallContext): string {\n    return ctx.scope === \"project\"\n      ? join(ctx.projectDir, \".roo\")\n      : join(\n          vscodeUserDir(),\n          \"globalStorage\",\n          ROO_EXTENSION_ID,\n          \"settings\",\n        );\n  }\n\n  getServerConfigPath(ctx: InstallContext): string {\n    return ctx.scope === \"project\"\n      ? join(ctx.projectDir, \".roo\", \"mcp.json\")\n      : this.userSettingsPath();\n  }\n\n  /**\n   * Roo Code has no hook file — hooks are not a thing here. The hook \"config\n   * path\" is the same MCP settings file so the generic doctor/backup behave\n   * sensibly.\n   */\n  getHookConfigPath(ctx: InstallContext): string {\n    return this.getServerConfigPath(ctx);\n  }\n\n  // ── MCP server install / uninstall ───────────────────────────────────────\n\n  installServer(ctx: InstallContext): ChangeRecord[] {\n    const { connector } = ctx;\n    const override = connector.platforms[HOST]?.server;\n    if (!connector.server || override === false) {\n      return [\n        {\n          platform: this.id,\n          action: \"skip\",\n          detail: connector.server\n            ? \"server registration disabled for roo-code\"\n            : \"connector declares no MCP server\",\n        },\n      ];\n    }\n\n    // Shallow-merge any per-platform server override into the base ServerDef.\n    const server: ServerDef =\n      override && typeof override === \"object\"\n        ? { ...connector.server, ...override }\n        : connector.server;\n\n    const serverPath = this.getServerConfigPath(ctx);\n    const entry = this.renderServerEntry(ctx, server);\n\n    return [\n      this.upsertServerInJson(serverPath, MCP_ROOT_KEY, connector.id, entry, ctx.dryRun),\n    ];\n  }\n\n  uninstallServer(ctx: InstallContext): ChangeRecord[] {\n    const serverPath = this.getServerConfigPath(ctx);\n    return [\n      this.removeServerFromJson(serverPath, MCP_ROOT_KEY, ctx.connector.id, ctx.dryRun),\n    ];\n  }\n\n  /** Render a normalized ServerDef into Roo Code's native mcpServers entry. */\n  private renderServerEntry(\n    ctx: InstallContext,\n    server: ServerDef,\n  ): RooStdioServer | RooHttpServer {\n    const transport: Transport = server.transport;\n\n    if (transport === \"stdio\") {\n      let command = server.command ?? \"\";\n      let args = [...(server.args ?? [])];\n\n      // Transparent telemetry wrapping: route the real command through\n      // `<homeBin> serve --connector <id> -- <command> <args...>`.\n      if (shouldWrapForTelemetry(server, ctx.connector.telemetry)) {\n        const wrapped = buildServeWrapperCommand(\n          ctx.homeBinPath,\n          ctx.connector.id,\n          command,\n          args,\n          ctx.scope,\n          this.id,\n        );\n        command = wrapped.command;\n        args = wrapped.args;\n      }\n\n      // Roo Code documents no native interpolation token, so resolve every\n      // ${env:VAR} to a literal at install time.\n      const entry: RooStdioServer = {\n        command: resolveEnvRefsDeep(command),\n        // Honor the per-call server's enabled flag (mirror droid) rather than\n        // hardcoding enabled — a server marked enabled:false installs disabled.\n        disabled: server.enabled === false,\n      };\n      if (args.length > 0) entry.args = resolveEnvRefsDeep(args);\n      const env = this.renderEnv(server.env);\n      if (env) entry.env = env;\n      return entry;\n    }\n\n    // sse / http (and any other remote transport) — Roo Code registers a URL.\n    const entry: RooHttpServer = {\n      url: resolveEnvRefsDeep(server.url ?? \"\"),\n      disabled: server.enabled === false,\n    };\n    const headers = this.renderEnv(server.headers);\n    if (headers) entry.headers = headers;\n    return entry;\n  }\n\n  /**\n   * Render env/header values. Roo Code documents no native interpolation token,\n   * so resolve `${env:VAR}` references to literals at install time.\n   */\n  private renderEnv(\n    env: Record<string, string> | undefined,\n  ): Record<string, string> | undefined {\n    if (!env || Object.keys(env).length === 0) return undefined;\n    return resolveEnvRefsDeep({ ...env });\n  }\n\n  // ── Hooks (unavailable — Roo Code is mcp-only) ───────────────────────────\n\n  installHooks(_ctx: InstallContext): ChangeRecord[] {\n    return [\n      {\n        platform: this.id,\n        action: \"skip\",\n        detail: \"hooks unavailable (Roo Code is mcp-only)\",\n      },\n    ];\n  }\n\n  uninstallHooks(_ctx: InstallContext): ChangeRecord[] {\n    return [\n      {\n        platform: this.id,\n        action: \"skip\",\n        detail: \"hooks unavailable (Roo Code is mcp-only)\",\n      },\n    ];\n  }\n\n  // ── Content surfaces: commands / skills ──────────────────────────────────\n  // CONTENT-ONLY: pure native-file writers. No runtime dispatch, no home-bin\n  // pointer, no telemetry wrap. Each method is idempotent (byte-identical →\n  // skip) via writeContentFile and reversible via removeContentFile. Honors\n  // platforms[\"roo-code\"] per-surface false to skip. BOTH scopes are supported:\n  // user → ~/.roo, project → <projectDir>/.roo.\n  //\n  // Native locations (the `.roo` content root, NOT the globalStorage MCP dir):\n  //   command → <rooDir>/commands/<name>.md   md+optional frontmatter\n  //             (description, argument-hint, + `mode` when cmd.extra carries it)\n  //   skill   → <rooDir>/skills/<name>/SKILL.md (+ resources)\n\n  /**\n   * The `.roo` content root for the active scope: ~/.roo (user) or\n   * <projectDir>/.roo (project). Distinct from getConfigDir's user-scope path\n   * (the VS Code globalStorage `settings` dir, which holds MCP settings only).\n   */\n  private rooDir(ctx: InstallContext): string {\n    return ctx.scope === \"project\"\n      ? join(ctx.projectDir, \".roo\")\n      : join(homedir(), \".roo\");\n  }\n  private commandPath(ctx: InstallContext, name: string): string {\n    return join(this.rooDir(ctx), \"commands\", `${name}.md`);\n  }\n  private skillDir(ctx: InstallContext, name: string): string {\n    return join(this.rooDir(ctx), \"skills\", name);\n  }\n\n  // ── Commands ─────────────────────────────────────────────────────────────\n\n  override installCommands(ctx: InstallContext): ChangeRecord[] {\n    const { connector } = ctx;\n    if (connector.platforms[this.id]?.commands === false) {\n      return [{ platform: this.id, action: \"skip\", detail: \"commands disabled for roo-code\" }];\n    }\n    if (connector.commands.length === 0) {\n      return [{ platform: this.id, action: \"skip\", detail: \"connector declares no commands\" }];\n    }\n    return connector.commands.map((cmd) =>\n      this.writeContentFile(this.commandPath(ctx, cmd.name), this.renderCommand(cmd), ctx.dryRun),\n    );\n  }\n\n  override uninstallCommands(ctx: InstallContext): ChangeRecord[] {\n    const { connector } = ctx;\n    if (connector.commands.length === 0) {\n      return [{ platform: this.id, action: \"skip\", detail: \"connector declares no commands\" }];\n    }\n    return connector.commands.map((cmd) =>\n      this.removeContentFile(this.commandPath(ctx, cmd.name), ctx.dryRun),\n    );\n  }\n\n  /**\n   * Render a command to md+optional frontmatter (description, argument-hint).\n   * Roo Code additionally honors a `mode` frontmatter key; it is passed through\n   * only when cmd.extra carries it (the escape-hatch Object.assign below) — the\n   * standard description/argument-hint shape otherwise.\n   */\n  private renderCommand(cmd: CommandDef): string {\n    const frontmatter: Record<string, unknown> = {};\n    if (cmd.description !== undefined) frontmatter.description = cmd.description;\n    if (cmd.argumentHint !== undefined) frontmatter[\"argument-hint\"] = cmd.argumentHint;\n    if (cmd.extra) Object.assign(frontmatter, cmd.extra);\n    return this.renderFrontmatterMd(frontmatter, cmd.prompt);\n  }\n\n  // ── Skills ───────────────────────────────────────────────────────────────\n\n  override installSkills(ctx: InstallContext): ChangeRecord[] {\n    const { connector } = ctx;\n    if (connector.platforms[this.id]?.skills === false) {\n      return [{ platform: this.id, action: \"skip\", detail: \"skills disabled for roo-code\" }];\n    }\n    if (connector.skills.length === 0) {\n      return [{ platform: this.id, action: \"skip\", detail: \"connector declares no skills\" }];\n    }\n    const changes: ChangeRecord[] = [];\n    for (const skill of connector.skills) {\n      const dir = this.skillDir(ctx, skill.name);\n      changes.push(\n        this.writeContentFile(join(dir, \"SKILL.md\"), this.renderSkill(skill), ctx.dryRun),\n      );\n      // Bundle any resource files beside SKILL.md (relative path → contents).\n      // Defense-in-depth: skip+warn on any key that escapes the skill dir\n      // (config-time validation already rejects these, but never trust input).\n      for (const [rel, contents] of Object.entries(skill.resources ?? {})) {\n        const target = this.resolveWithin(dir, rel);\n        if (target === null) {\n          changes.push({\n            platform: this.id,\n            action: \"warn\",\n            detail: `skill resource \"${rel}\" escapes the skill dir; skipped`,\n          });\n          continue;\n        }\n        changes.push(this.writeContentFile(target, contents, ctx.dryRun));\n      }\n    }\n    return changes;\n  }\n\n  override uninstallSkills(ctx: InstallContext): ChangeRecord[] {\n    const { connector } = ctx;\n    if (connector.skills.length === 0) {\n      return [{ platform: this.id, action: \"skip\", detail: \"connector declares no skills\" }];\n    }\n    const changes: ChangeRecord[] = [];\n    for (const skill of connector.skills) {\n      const dir = this.skillDir(ctx, skill.name);\n      // Remove only the files we wrote (SKILL.md + declared resources), then the\n      // skill dir itself when we own its full contents.\n      changes.push(this.removeContentFile(join(dir, \"SKILL.md\"), ctx.dryRun));\n      for (const rel of Object.keys(skill.resources ?? {})) {\n        const target = this.resolveWithin(dir, rel);\n        if (target === null) continue; // never delete outside the skill dir\n        changes.push(this.removeContentFile(target, ctx.dryRun));\n      }\n      // Only remove the skill dir when WE own its full contents — never rm -rf a\n      // dir that still holds user-added / sibling-tool / shared files.\n      changes.push(this.removeDirIfEmpty(dir, ctx.dryRun));\n    }\n    return changes;\n  }\n\n  /**\n   * Render a skill's SKILL.md: frontmatter (name, description + optional model,\n   * allowed-tools, disable-model-invocation) + body. UNIFORM with every other\n   * skill-supporting platform — only the parent dir differs.\n   */\n  private renderSkill(skill: SkillDef): string {\n    const frontmatter: Record<string, unknown> = {\n      name: skill.name,\n      description: skill.description,\n    };\n    if (skill.model !== undefined) frontmatter.model = skill.model;\n    const allow = skill.tools?.allow;\n    if (allow && allow.length > 0) frontmatter[\"allowed-tools\"] = allow.join(\", \");\n    if (skill.disableModelInvocation !== undefined) {\n      frontmatter[\"disable-model-invocation\"] = skill.disableModelInvocation;\n    }\n    if (skill.extra) Object.assign(frontmatter, skill.extra);\n    return this.renderFrontmatterMd(frontmatter, skill.body);\n  }\n\n  // ── Diagnostics ──────────────────────────────────────────────────────────\n\n  override getHealthChecks(ctx: InstallContext): readonly HealthCheck[] {\n    const mcpPath = this.getServerConfigPath(ctx);\n    const connectorId = ctx.connector.id;\n    return [\n      {\n        name: `${this.name}: MCP settings present`,\n        check: () =>\n          existsSync(mcpPath)\n            ? { status: \"OK\", detail: mcpPath }\n            : { status: \"FAIL\", detail: `not found: ${mcpPath}` },\n      },\n      {\n        name: `${this.name}: server entry registered`,\n        check: () => {\n          // Only assert what the connector declares: a server-less connector —\n          // e.g. a catalog-only bundle of agents/skills/commands — never writes\n          // an mcpServers entry, so its absence is healthy.\n          if (!ctx.connector.server) {\n            return { status: \"OK\", detail: \"no MCP server declared\" };\n          }\n          const cfg = this.readJson<{ [k: string]: Record<string, unknown> }>(mcpPath);\n          const bucket = cfg?.[MCP_ROOT_KEY];\n          if (!cfg || !bucket) {\n            return { status: \"FAIL\", detail: `no ${MCP_ROOT_KEY} in ${mcpPath}` };\n          }\n          return connectorId in bucket\n            ? { status: \"OK\", detail: `${MCP_ROOT_KEY}.${connectorId} present` }\n            : {\n                status: \"FAIL\",\n                detail: `no ${MCP_ROOT_KEY}.${connectorId} in ${mcpPath}`,\n              };\n        },\n      },\n    ];\n  }\n}\n\nexport const adapter = new RooCodeAdapter();\nexport default adapter;\n"],"mappings":"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","names":["entry"]}

package/dist/runtime/index.d.ts

@@ -1,4 +1,4 @@
-import { c as HookEventName, k as PlatformId } from '../types-CNigfEuR.js';
+import { e as HookEventName, P as PlatformId } from '../types-BEKsAium.js';
 
 /**
  * runtime/hook-entrypoint — the universal json-stdio hook dispatcher.
@@ -188,4 +188,98 @@ interface RunUsageEventResult {
  */
 declare function runUsageEvent(opts: RunUsageEventOptions): Promise<RunUsageEventResult>;
 
-export { type RunHookOptions, type RunHookResult, type RunNativeHookOptions, type RunServeOptions, type RunUsageEventOptions, type RunUsageEventResult, isNativeHookDeclared, runHook, runNativeHook, runServe, runUsageEvent };
+/**
+ * runtime/statusline-entrypoint — the universal statusline (HUD) renderer.
+ *
+ * A statusline-supporting host points its status line config at the single stable
+ * home binary (`<homeBin> statusline <platformId> --connector <id>`, built by
+ * core/spawn.buildHomeBinStatuslineCommand). The CLI reads stdin and calls
+ * {@link runStatusline} with the parsed flags + the raw stdin string. This module:
+ *
+ *   1. Loads the registered connector (live render handler) and the host adapter.
+ *   2. Parses the host's raw status payload into a normalized StatuslineContext.
+ *   3. Calls the connector's render(ctx) and coerces the result to a string.
+ *   4. Formats the line into the host's native status reply (exit code + stdout).
+ *
+ * FAIL-SAFE is the contract (NOT fail-open with carve-outs like hooks): a status
+ * line is decorative — it must NEVER wedge the host or spew an error/stack trace
+ * into the status bar. So ANY error path — bad payload, missing connector,
+ * throwing render, adapter without statusline support — returns exit 0 with NO
+ * stdout (an empty status line), never a non-zero exit and never partial output.
+ *
+ * NOTE (follow-up): no telemetry is recorded for statusline renders in v1 (out of
+ * scope). When added, it MUST stay inside the same fail-safe envelope.
+ */
+/** Flags + stdin the CLI hands to {@link runStatusline}. */
+interface RunStatuslineOptions {
+    /** Host platform id from the command (`statusline <platformId> …`). */
+    platformId: string;
+    /** Connector id from `--connector <id>`. */
+    connectorId: string;
+    /** Raw stdin payload (host-native status JSON). Empty string is tolerated → `{}`. */
+    stdin: string;
+}
+/** Process-level result the CLI translates into exit code + stdout/stderr. */
+interface RunStatuslineResult {
+    exitCode: number;
+    stdout?: string;
+    stderr?: string;
+}
+/**
+ * Render one host status-line invocation. Always resolves (never rejects): every
+ * failure path returns the empty {@link EMPTY} result so the CLI exits cleanly
+ * with an empty status line. See the module header for the fail-safe contract.
+ */
+declare function runStatusline(opts: RunStatuslineOptions): Promise<RunStatuslineResult>;
+
+/**
+ * runtime/action-entrypoint — the universal user-invokable action dispatcher.
+ *
+ * A future host affordance (slash command / keybinding) points at the single
+ * stable home binary (`<homeBin> action <platformId> <actionId> --connector
+ * <id>`, built by core/spawn.buildHomeBinActionCommand). The CLI parses the
+ * flags and calls {@link runAction}. This module:
+ *
+ *   1. Loads the registered connector (live run handler) and the host adapter.
+ *   2. Builds the shared {@link HostCtx} (host + the adapter's capabilities; NO
+ *      stdin — an action takes no host payload, unlike a hook or status line).
+ *   3. Finds the action by id, resolves the per-host run override, runs it, and
+ *      prints the optional result.message.
+ *
+ * USER-TRIGGERED ERROR SEMANTICS (the key difference from hooks/statusline):
+ * actions are invoked DELIBERATELY by a user, so errors are SURFACED, never
+ * failed silently. An unknown action id or a throwing run → exit 1 + a stderr
+ * message. (Hooks fail-open to exit 0; the statusline fail-safes to an empty
+ * line — both are passive surfaces a host fires automatically. An action is not:
+ * swallowing its failure would leave the user staring at nothing, unable to
+ * tell the action ran.)
+ *
+ * NOTE (follow-up): no telemetry is recorded for action runs in v1 (out of
+ * scope), and no adapter EMITS the affordance yet — v1 ships the dispatch
+ * backbone only.
+ */
+/** Flags the CLI hands to {@link runAction} (no stdin — actions take no payload). */
+interface RunActionOptions {
+    /** Host platform id from the command (`action <platformId> <actionId> …`). */
+    platformId: string;
+    /** Connector id from `--connector <id>`. */
+    connectorId: string;
+    /** The action id positional (`action <platformId> <actionId> …`). */
+    actionId: string;
+}
+/** Process-level result the CLI translates into exit code + stdout/stderr. */
+interface RunActionResult {
+    exitCode: number;
+    stdout?: string;
+    stderr?: string;
+}
+/**
+ * Dispatch one user-invokable action. Always resolves (never rejects): every
+ * path returns a concrete {@link RunActionResult} so the CLI can exit cleanly,
+ * but UNLIKE the hook/statusline runtimes an error resolves to exit 1 + a stderr
+ * message (actions are user-triggered — surface the failure). See the module
+ * header for the user-triggered error contract.
+ */
+declare function runAction(opts: RunActionOptions): Promise<RunActionResult>;
+
+export { type RunActionOptions, type RunActionResult, type RunHookOptions, type RunHookResult, type RunNativeHookOptions, type RunServeOptions, type RunStatuslineOptions, type RunStatuslineResult, type RunUsageEventOptions, type RunUsageEventResult, isNativeHookDeclared, runAction, runHook, runNativeHook, runServe, runStatusline, runUsageEvent };

package/dist/runtime/index.js

@@ -1,25 +1,33 @@
 #!/usr/bin/env node
 import {
-  isNativeHookDeclared,
-  runHook,
-  runNativeHook,
+  runAction,
   runServe,
+  runStatusline,
   runUsageEvent
-} from "../chunk-ZAM4M7LI.js";
-import "../chunk-BCHWFTV4.js";
+} from "../chunk-BHUCB6LY.js";
 import "../chunk-OP4KBXUO.js";
-import "../chunk-KVAAFYRR.js";
-import "../chunk-NJU275US.js";
-import "../chunk-3JCRUROU.js";
-import "../chunk-GSGDG2BV.js";
-import "../chunk-MEH7GC7R.js";
+import "../chunk-22Y24V7O.js";
+import "../chunk-J3D5W5T2.js";
+import {
+  isNativeHookDeclared,
+  runHook,
+  runNativeHook
+} from "../chunk-CIRDOY2V.js";
+import "../chunk-BCHWFTV4.js";
+import "../chunk-KHO5WNTP.js";
+import "../chunk-KGJWE6A2.js";
+import "../chunk-ADTHT2FN.js";
+import "../chunk-3PFFTFCU.js";
+import "../chunk-BXGFUENQ.js";
 import "../chunk-N6HH7K6P.js";
 import "../chunk-TRQKHP7D.js";
 export {
   isNativeHookDeclared,
+  runAction,
   runHook,
   runNativeHook,
   runServe,
+  runStatusline,
   runUsageEvent
 };
 //# sourceMappingURL=index.js.map

package/dist/sdk/index.d.ts

@@ -0,0 +1,52 @@
+export { ConnectorConfigError, defineAction, defineCommand, defineConfigPatch, defineConnector, defineHook, defineMemory, defineNativeHook, defineSkill, defineStatusline, defineSubagent } from '../index.js';
+export { S as SURFACE_PREDICATES, a as SurfaceName, c as capabilitiesOf, h as hostsSupporting, s as surfaceSupport } from '../introspect-DuZSPSHB.js';
+import { P as PlatformId } from '../types-BEKsAium.js';
+export { A as ActionDef, a as ActionResult, b as AuthSpec, C as CommandDef, c as ConfigPatchDef, d as ConnectorConfig, E as EventPayloadMap, H as HookDefinition, e as HookEventName, f as HookParadigm, g as HookResponse, h as HooksConfig, i as HostCtx, I as InstallScope, J as JsonValue, M as MemoryDef, N as NativeHookDef, j as NativeHookEvent, k as NotificationEvent, l as PermissionRequestEvent, m as PlatformCapabilities, n as PlatformMemoryOverride, o as PlatformOverride, p as PostToolUseEvent, q as PostToolUseFailureEvent, r as PreCompactEvent, s as PreToolUseEvent, t as PublishConfig, R as ResolvedConnector, S as ServerDef, u as SessionEndEvent, v as SessionStartEvent, w as SkillDef, x as StatuslineContext, y as StatuslineDef, z as StopEvent, B as SubagentDef, D as SubagentStartEvent, F as SubagentStopEvent, G as SurfaceToolPolicy, T as TelemetryAccessor, K as TelemetryConfig, L as TelemetryUsageSummary, O as ToolFilter, Q as Transport, U as UserPromptSubmitEvent } from '../types-BEKsAium.js';
+
+/**
+ * sdk/helpers — host-aware authoring helpers for connector handlers.
+ *
+ * A handler (a hook, a statusline render, an action run) sees the host it is
+ * dispatched for via the {@link HostCtx} (`ctx.host`). These two helpers let a
+ * handler render a host-correct value without hardcoding a per-host branch:
+ *
+ *   • {@link toolName} — resolve a bare MCP tool name to the host's native
+ *     reference form (some hosts namespace MCP tools as `mcp__<id>__<tool>`).
+ *   • {@link style}    — wrap text in an ANSI escape ONLY on hosts that render
+ *     ANSI in a status line / output; plain everywhere else.
+ *
+ * Both are deliberately MODEST, documented best-effort lists — NOT a capability
+ * query. The per-host convention each encodes is not centrally modeled in
+ * {@link PlatformCapabilities} yet; if either set grows it should migrate to a
+ * capability flag (a `mcpToolPrefix` / `rendersAnsi` flag) the adapter declares.
+ */
+
+/**
+ * Resolve a bare MCP tool name to the host's native reference form.
+ *
+ * On a {@link PREFIXED_HOSTS} host the result is `mcp__<connectorId>__<baseName>`
+ * (how those hosts surface a connector's MCP tools); on every other host it is
+ * the bare `baseName`. When the host prefixes but no `connectorId` is supplied
+ * the helper falls back to the bare name rather than emitting a malformed
+ * `mcp__undefined__…` reference — it NEVER throws.
+ */
+declare function toolName(ctx: {
+    host: PlatformId;
+    connectorId?: string;
+}, baseName: string): string;
+/**
+ * Style `text` with an ANSI SGR escape on hosts that render it (a status line /
+ * terminal output), plain everywhere else.
+ *
+ * When `ctx.host` is in {@link ANSI_HOSTS} and `codes.ansi` is provided, returns
+ * `\x1b[<ansi>m<text>\x1b[0m`; otherwise returns `text` unchanged (an
+ * IDE-embedded host, or no `ansi` code given). `codes.ansi` is the SGR
+ * parameter(s), e.g. `"1"` (bold) or `"1;32"` (bold green).
+ */
+declare function style(ctx: {
+    host: PlatformId;
+}, text: string, codes: {
+    ansi?: string;
+}): string;
+
+export { PlatformId, style, toolName };

package/dist/sdk/index.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import {
+  SURFACE_PREDICATES,
+  capabilitiesOf,
+  hostsSupporting,
+  surfaceSupport
+} from "../chunk-76FUSVIA.js";
+import {
+  ConnectorConfigError,
+  defineAction,
+  defineCommand,
+  defineConfigPatch,
+  defineConnector,
+  defineHook,
+  defineMemory,
+  defineNativeHook,
+  defineSkill,
+  defineStatusline,
+  defineSubagent
+} from "../chunk-ADTHT2FN.js";
+import "../chunk-3PFFTFCU.js";
+import "../chunk-N6HH7K6P.js";
+import "../chunk-TRQKHP7D.js";
+
+// src/sdk/helpers.ts
+var PREFIXED_HOSTS = /* @__PURE__ */ new Set([
+  "claude-code",
+  "codex",
+  "kimi",
+  "cursor",
+  "copilot-cli",
+  "vscode-copilot",
+  "jetbrains-copilot",
+  "gemini-cli",
+  "qwen-code"
+]);
+function toolName(ctx, baseName) {
+  if (PREFIXED_HOSTS.has(ctx.host) && ctx.connectorId) {
+    return `mcp__${ctx.connectorId}__${baseName}`;
+  }
+  return baseName;
+}
+var ANSI_HOSTS = /* @__PURE__ */ new Set([
+  "claude-code",
+  "codex",
+  "gemini-cli",
+  "qwen-code",
+  "cursor",
+  "copilot-cli",
+  "opencode",
+  "droid",
+  "crush",
+  "goose",
+  "amp"
+]);
+function style(ctx, text, codes) {
+  if (codes.ansi && ANSI_HOSTS.has(ctx.host)) {
+    return `\x1B[${codes.ansi}m${text}\x1B[0m`;
+  }
+  return text;
+}
+export {
+  ConnectorConfigError,
+  SURFACE_PREDICATES,
+  capabilitiesOf,
+  defineAction,
+  defineCommand,
+  defineConfigPatch,
+  defineConnector,
+  defineHook,
+  defineMemory,
+  defineNativeHook,
+  defineSkill,
+  defineStatusline,
+  defineSubagent,
+  hostsSupporting,
+  style,
+  surfaceSupport,
+  toolName
+};
+//# sourceMappingURL=index.js.map

package/dist/sdk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sdk/helpers.ts"],"sourcesContent":["/**\n * sdk/helpers — host-aware authoring helpers for connector handlers.\n *\n * A handler (a hook, a statusline render, an action run) sees the host it is\n * dispatched for via the {@link HostCtx} (`ctx.host`). These two helpers let a\n * handler render a host-correct value without hardcoding a per-host branch:\n *\n *   • {@link toolName} — resolve a bare MCP tool name to the host's native\n *     reference form (some hosts namespace MCP tools as `mcp__<id>__<tool>`).\n *   • {@link style}    — wrap text in an ANSI escape ONLY on hosts that render\n *     ANSI in a status line / output; plain everywhere else.\n *\n * Both are deliberately MODEST, documented best-effort lists — NOT a capability\n * query. The per-host convention each encodes is not centrally modeled in\n * {@link PlatformCapabilities} yet; if either set grows it should migrate to a\n * capability flag (a `mcpToolPrefix` / `rendersAnsi` flag) the adapter declares.\n */\n\nimport type { PlatformId } from \"../core/types.js\";\n\n/**\n * Hosts that namespace MCP tools as `mcp__<connectorId>__<tool>` — the\n * `mcp__`-prefix convention Claude Code popularized and most MCP-client agents\n * adopted. CONFIRMED in-repo via the adapters' own `mcp__` PreToolUse matchers\n * for claude-code, codex, and kimi; the remaining members are MCP-client hosts\n * the convention applies to but are not separately verified here (a wrong\n * inclusion only ever yields a name the host doesn't resolve, the same outcome\n * as wrongly EXCLUDING a prefixing host — and an author can always construct the\n * reference themselves). This is a SMALL explicit set, not a capability query;\n * if it grows, migrate it to a per-adapter `mcpToolPrefix` capability flag.\n * (Follow-up: spot-verify gemini-cli / a copilot variant on a live box.)\n */\nconst PREFIXED_HOSTS: ReadonlySet<PlatformId> = new Set<PlatformId>([\n  \"claude-code\",\n  \"codex\",\n  \"kimi\",\n  \"cursor\",\n  \"copilot-cli\",\n  \"vscode-copilot\",\n  \"jetbrains-copilot\",\n  \"gemini-cli\",\n  \"qwen-code\",\n]);\n\n/**\n * Resolve a bare MCP tool name to the host's native reference form.\n *\n * On a {@link PREFIXED_HOSTS} host the result is `mcp__<connectorId>__<baseName>`\n * (how those hosts surface a connector's MCP tools); on every other host it is\n * the bare `baseName`. When the host prefixes but no `connectorId` is supplied\n * the helper falls back to the bare name rather than emitting a malformed\n * `mcp__undefined__…` reference — it NEVER throws.\n */\nexport function toolName(\n  ctx: { host: PlatformId; connectorId?: string },\n  baseName: string,\n): string {\n  if (PREFIXED_HOSTS.has(ctx.host) && ctx.connectorId) {\n    return `mcp__${ctx.connectorId}__${baseName}`;\n  }\n  return baseName;\n}\n\n/**\n * Hosts that render ANSI escape sequences in a status line / terminal output —\n * the CLI/TUI hosts. IDE-embedded hosts (where output lands in a webview /\n * editor panel that shows the raw escape) are deliberately EXCLUDED. Like\n * {@link PREFIXED_HOSTS} this is a documented best-effort list, not a capability\n * query; migrate it to a `rendersAnsi` capability flag if it grows.\n */\nconst ANSI_HOSTS: ReadonlySet<PlatformId> = new Set<PlatformId>([\n  \"claude-code\",\n  \"codex\",\n  \"gemini-cli\",\n  \"qwen-code\",\n  \"cursor\",\n  \"copilot-cli\",\n  \"opencode\",\n  \"droid\",\n  \"crush\",\n  \"goose\",\n  \"amp\",\n]);\n\n/**\n * Style `text` with an ANSI SGR escape on hosts that render it (a status line /\n * terminal output), plain everywhere else.\n *\n * When `ctx.host` is in {@link ANSI_HOSTS} and `codes.ansi` is provided, returns\n * `\\x1b[<ansi>m<text>\\x1b[0m`; otherwise returns `text` unchanged (an\n * IDE-embedded host, or no `ansi` code given). `codes.ansi` is the SGR\n * parameter(s), e.g. `\"1\"` (bold) or `\"1;32\"` (bold green).\n */\nexport function style(\n  ctx: { host: PlatformId },\n  text: string,\n  codes: { ansi?: string },\n): string {\n  if (codes.ansi && ANSI_HOSTS.has(ctx.host)) {\n    return `\\x1b[${codes.ansi}m${text}\\x1b[0m`;\n  }\n  return text;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAM,iBAA0C,oBAAI,IAAgB;AAAA,EAClE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAWM,SAAS,SACd,KACA,UACQ;AACR,MAAI,eAAe,IAAI,IAAI,IAAI,KAAK,IAAI,aAAa;AACnD,WAAO,QAAQ,IAAI,WAAW,KAAK,QAAQ;AAAA,EAC7C;AACA,SAAO;AACT;AASA,IAAM,aAAsC,oBAAI,IAAgB;AAAA,EAC9D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAWM,SAAS,MACd,KACA,MACA,OACQ;AACR,MAAI,MAAM,QAAQ,WAAW,IAAI,IAAI,IAAI,GAAG;AAC1C,WAAO,QAAQ,MAAM,IAAI,IAAI,IAAI;AAAA,EACnC;AACA,SAAO;AACT;","names":[]}

package/dist/sdk/test.d.ts

@@ -0,0 +1,74 @@
+import { P as PlatformId, e as HookEventName, R as ResolvedConnector } from '../types-BEKsAium.js';
+import { a as SurfaceName } from '../introspect-DuZSPSHB.js';
+
+/**
+ * sdk/test-harness — the SHIPPED, OFFLINE behavioral harness.
+ *
+ * Two read-only tools a connector author runs WITHOUT installing anything or
+ * touching the host's filesystem:
+ *
+ *   • `explain(connector)` — the static per-host × per-DECLARED-surface matrix:
+ *     for every registered host and every surface the connector actually ships,
+ *     is it `native` (the host can honor it), `disabled` (the connector opted
+ *     out for that host via `platforms[host].<surface> === false`), or
+ *     `skip-warn` (the host cannot honor it → install would skip-warn)?
+ *
+ *   • `simulate(connector, opts)` — runs the REAL adapter parse → handler →
+ *     format chain INLINE against a host-shaped raw payload and reports whether
+ *     the host actually HONORS the connector's response (the trustworthy part:
+ *     it surfaces the documented degradations, e.g. Codex silently dropping a
+ *     UserPromptSubmit "context" injection that has no stdout path).
+ *
+ * It deliberately does NOT import the runtime entrypoints (runHook /
+ * runStatusline) — those load the REGISTERED connector from disk and record
+ * telemetry. The harness instead re-implements the tiny parse→handler→format
+ * chain against the in-memory connector + the adapter, mirroring the runtime's
+ * input tolerance (empty/malformed payload → `{}`) and its fail-safe envelope.
+ */
+
+/** One cell of the {@link explain} matrix: a host × a declared surface. */
+interface ExplainRow {
+    host: PlatformId;
+    surface: SurfaceName;
+    /**
+     *  - "native"    — the host's capabilities pass the surface predicate.
+     *  - "disabled"  — the connector opted out for this host
+     *                  (`platforms[host].<surface> === false`).
+     *  - "skip-warn" — the host cannot honor it; install would skip-warn.
+     */
+    support: "native" | "skip-warn" | "disabled";
+    reason: string;
+}
+/**
+ * The static support matrix: every registered host × every surface the
+ * connector declares. Rows are sorted by host then surface for stable output.
+ * Pure read of the adapter capabilities — installs nothing, writes nothing.
+ */
+declare function explain(connector: ResolvedConnector): Promise<ExplainRow[]>;
+/** What to drive through the harness: one host, one surface, one raw payload. */
+interface SimulateOptions {
+    surface: "hooks" | "statusline";
+    host: PlatformId | string;
+    /** REQUIRED when `surface === "hooks"`: which normalized lifecycle event. */
+    event?: HookEventName;
+    /** The host-shaped RAW payload (what the host would pipe in on stdin). */
+    input: unknown;
+}
+/** The harness verdict: did the host actually honor the connector's response? */
+interface SimulateResult {
+    /** True when the host's native reply carries the connector's intent. */
+    honored: boolean;
+    /** The host-native stdout the adapter would emit (when there is one). */
+    hostReply?: string;
+    /** Human-readable why — names the documented degradation when honored:false. */
+    reason: string;
+}
+/**
+ * Run the connector against ONE host-shaped payload through the REAL adapter
+ * path and report whether the host honors the response. Self-contained (does not
+ * touch the registered-connector loader or telemetry) and fail-safe: any throw
+ * in the chain degrades to `honored:false` with the error message, never rejects.
+ */
+declare function simulate(connector: ResolvedConnector, opts: SimulateOptions): Promise<SimulateResult>;
+
+export { type ExplainRow, type SimulateOptions, type SimulateResult, explain, simulate };