@ken-jo/agent-connector 0.4.92 → 0.4.94

package/README.md

@@ -47,10 +47,13 @@ if you already run an agent CLI and just want token totals, jump straight to
 
 ## Quick start
 
-agent-connector is an **SDK you depend on**, not a global tool. Add it to the
-package that holds your connector, declare the connector once, then `install` —
-it deploys to every detected agent CLI in that host's own native config. The
-linear path is: **get a server → declare it → install**.
+agent-connector is an **SDK connector developers depend on**. Add it to the
+package that holds your connector, declare the connector once, then ship a
+branded MCP package/bin such as `npx @acme/acme-db-mcp install` — it deploys to
+every detected agent CLI in that host's own native config. Installing
+`@ken-jo/agent-connector` globally is only an optional path for connector-free
+token usage reports. The linear path is:
+**get a server → declare it → install through your branded package**.
 
 **0. You need an MCP server file first.** The config below points at
 `./my-mcp-server.mjs`, so that file must exist before you install. Don't have an
@@ -64,15 +67,27 @@ MCP server yet? Copy
 npm install @ken-jo/agent-connector
 ```
 
+```jsonc
+// 2. package.json — this is the user-facing package identity
+{
+  "name": "@acme/acme-db-mcp",
+  "mcpName": "io.github.acme/acme-db",
+  "bin": { "acme-db": "./bin.mjs" },
+  "dependencies": { "@ken-jo/agent-connector": "^0.4.92" }
+}
+```
+
 ```js
-// 2. agent-connector.config.mjs — declare your server + hooks once
+// 3. agent-connector.config.mjs — declare your server + hooks once
 import { fileURLToPath } from "node:url";
 import { defineConnector } from "@ken-jo/agent-connector";
 
 const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));
 
 export default defineConnector({
-  id: "acme-db",
+  // package.json / npm metadata is the source of truth. The host alias/runtime
+  // id and connector version are derived from name/mcpName/bin/version unless
+  // you need a multi-instance alias.
   server: {
     transport: "stdio",
     command: "node",
@@ -88,25 +103,27 @@ export default defineConnector({
 > [site quick-start](https://agent-connector.ai) teaches.
 
 ```bash
-# 3. deploy across the agent CLIs detected on this machine
-npx @ken-jo/agent-connector detect           # which platforms are installed here?
-npx @ken-jo/agent-connector install --dry-run # preview every change first
-npx @ken-jo/agent-connector install           # write native config in each host
+# 4. deploy under your branded MCP package/bin
+npx @acme/acme-db-mcp detect            # which platforms are installed here?
+npx @acme/acme-db-mcp install --dry-run # preview every change first
+npx @acme/acme-db-mcp install           # write native config in each host
 ```
 
 > `install` targets only the hosts actually **detected** on this machine (or an
 > explicit `--targets` / `connector.targets` list), intersected with the
 > 42-adapter registry — there is no "install to all 42 unconditionally" path.
-> A global `npm i -g` is **not** required: `npx @ken-jo/agent-connector …` runs
-> straight from your project.
+> `@ken-jo/agent-connector` is the framework dependency underneath; use it
+> directly for development fallback or connector-free token telemetry, not as
+> the foreground install brand for your users.
 
 ## Ship it: direct install or a marketplace plugin
 
 Same one definition, your choice of distribution.
 
-**Direct install** — `agent-connector install` writes each host's native MCP +
-hook + content-surface config in place, with no per-platform marketplace
-submission or review. This is the Quick start path above.
+**Direct install** — your branded command (`acme-db install`,
+`npx @acme/acme-db-mcp install`) writes each host's native MCP + hook +
+content-surface config in place, with no per-platform marketplace submission or
+review. This is the Quick start path above.
 
 **Marketplace plugin** — `agent-connector package` turns the connector into a
 real plugin/extension bundle (manifest + bundled commands, agents, skills,
@@ -147,8 +164,15 @@ agent-connector package --format gemini-extension --out ./ext   # or just one
 > **local install on that same machine/home**. For shared distribution use
 > `npm-plugin` or the MCP standard artifacts, or re-run `package` per machine.
 
-**Let agent-connector drive the host's own install flow** with `install --method
-marketplace`:
+**Let your branded MCP package drive the host's own install flow** with
+`install --method marketplace`:
+
+```bash
+acme-db install --method marketplace
+
+# framework fallback for local framework development/debugging only
+npx @ken-jo/agent-connector install --method marketplace --connector ./agent-connector.config.mjs
+```
 
 - **What it does** — stages the bundle, registers a local marketplace where the
   host has one, then runs the host's plugin-install verb (or, for npm-plugin
@@ -165,24 +189,22 @@ marketplace`:
 ### Ship a branded CLI
 
 A connector developer can ship their **own** bin instead of having users type
-`agent-connector`. `createConnectorCli({ name, connector })` (from the
-`@ken-jo/agent-connector/cli` export) exposes **every** subcommand under your
-brand, fully delegated and **auto-scoped** to your connector — so your users
-never install agent-connector globally or type `--connector`. See
+`agent-connector`. `createConnectorCli({ packageJson, connector })` (from the
+`@ken-jo/agent-connector/cli` export) derives the bin name/version from
+`package.json` and exposes **every** subcommand under your brand, fully
+delegated and **auto-scoped** to your connector — so your users do not need a
+framework global install or `--connector` for branded MCP install/doctor/uninstall. See
 [`examples/branded-cli`](examples/branded-cli) for the full, runnable package.
 
 ```js
 #!/usr/bin/env node
 // bin.mjs — every agent-connector subcommand, branded as `acme-db`
-import { fileURLToPath } from "node:url";
 import { createConnectorCli } from "@ken-jo/agent-connector/cli";
 
 // run() resolves to the exit code and never calls process.exit
 process.exitCode = await createConnectorCli({
-  name: "acme-db",
-  connector: fileURLToPath(
-    new URL("./agent-connector.config.mjs", import.meta.url),
-  ),
+  packageJson: new URL("./package.json", import.meta.url),
+  connector: new URL("./agent-connector.config.mjs", import.meta.url),
 }).run();
 ```
 
@@ -210,7 +232,6 @@ import { defineConnector } from "@ken-jo/agent-connector";
 const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));
 
 export default defineConnector({
-  id: "acme-db",
   server: {
     transport: "stdio",
     command: "node",           // or "npx", "python", etc. — whatever starts your server
@@ -231,7 +252,7 @@ export default defineConnector({
 });
 ```
 
-`agent-connector install` turns that into, e.g.:
+`npx @acme/acme-db-mcp install` turns that into, e.g.:
 
 | Host | What gets written |
 |---|---|
@@ -408,8 +429,6 @@ published package + author):
 
 ```ts
 defineConnector({
-  id: "acme-db",
-  version: "1.2.0",
   server: { transport: "stdio", command: "npx", args: ["-y", "@acme/acme-db-mcp"] },
   publish: {
     registryNamespace: "io.github.acme", // a namespace YOU proved ownership of

package/dist/{action-CVIEPX4U.js → action-VW5SACXY.js}

@@ -1,22 +1,22 @@
 #!/usr/bin/env node
 import {
   fail
-} from "./chunk-5Z36KVU2.js";
+} from "./chunk-TQRLMA2C.js";
 import {
   runAction
-} from "./chunk-447JWFZO.js";
+} from "./chunk-EHP7WISI.js";
 import "./chunk-OP4KBXUO.js";
 import "./chunk-Z2MRSS2I.js";
-import "./chunk-FO5CEXXN.js";
-import "./chunk-FBCBHEGB.js";
+import "./chunk-ZMAJ2XFD.js";
+import "./chunk-I5TO42QC.js";
 import "./chunk-KHO5WNTP.js";
 import "./chunk-IVAWP6HH.js";
-import "./chunk-JVO6NBTT.js";
-import "./chunk-AY3VFNOH.js";
-import "./chunk-KA55FISM.js";
+import "./chunk-KSPMSRVU.js";
+import "./chunk-KJLFGQQM.js";
+import "./chunk-SILKSP2Y.js";
 import "./chunk-NBYKLUF6.js";
 import "./chunk-4NHXLXSD.js";
-import "./chunk-M2H7JURF.js";
+import "./chunk-UMQ6NBQR.js";
 import "./chunk-GZGLCCEE.js";
 
 // src/cli/commands/action.ts
@@ -52,4 +52,4 @@ async function run(argv) {
 export {
   run
 };
-//# sourceMappingURL=action-CVIEPX4U.js.map
+//# sourceMappingURL=action-VW5SACXY.js.map

package/dist/{amazon-q-TIT7FIW3.js → amazon-q-ETMAGY3D.js}

@@ -4,12 +4,12 @@ import {
 } from "./chunk-BEFVJ2OE.js";
 import {
   BaseAdapter
-} from "./chunk-WFEHWTLM.js";
+} from "./chunk-MGTDQLJJ.js";
 import {
   buildWrappedStdio,
   isHomeBinHookCommand
 } from "./chunk-4NHXLXSD.js";
-import "./chunk-M2H7JURF.js";
+import "./chunk-UMQ6NBQR.js";
 import "./chunk-GZGLCCEE.js";
 
 // src/adapters/amazon-q/index.ts
@@ -563,4 +563,4 @@ export {
   adapter,
   amazon_q_default as default
 };
-//# sourceMappingURL=amazon-q-TIT7FIW3.js.map
+//# sourceMappingURL=amazon-q-ETMAGY3D.js.map

package/dist/{amp-NF3OAAUG.js → amp-67BZONGF.js}

@@ -8,11 +8,11 @@ import {
 import {
   BaseAdapter,
   renderSkillMd
-} from "./chunk-WFEHWTLM.js";
+} from "./chunk-MGTDQLJJ.js";
 import {
   buildWrappedStdio
 } from "./chunk-4NHXLXSD.js";
-import "./chunk-M2H7JURF.js";
+import "./chunk-UMQ6NBQR.js";
 import "./chunk-GZGLCCEE.js";
 
 // src/adapters/amp/index.ts
@@ -608,4 +608,4 @@ export {
   adapter,
   amp_default as default
 };
-//# sourceMappingURL=amp-NF3OAAUG.js.map
+//# sourceMappingURL=amp-67BZONGF.js.map

package/dist/{antigravity-7LPK7QOY.js → antigravity-VXLDLTO7.js}

@@ -3,16 +3,16 @@ import {
   AntigravityAdapter,
   adapter,
   antigravity_default
-} from "./chunk-DI5S6TXJ.js";
+} from "./chunk-XC5SJ35F.js";
 import "./chunk-H53QZQJI.js";
 import "./chunk-BEFVJ2OE.js";
-import "./chunk-WFEHWTLM.js";
+import "./chunk-MGTDQLJJ.js";
 import "./chunk-4NHXLXSD.js";
-import "./chunk-M2H7JURF.js";
+import "./chunk-UMQ6NBQR.js";
 import "./chunk-GZGLCCEE.js";
 export {
   AntigravityAdapter,
   adapter,
   antigravity_default as default
 };
-//# sourceMappingURL=antigravity-7LPK7QOY.js.map
+//# sourceMappingURL=antigravity-VXLDLTO7.js.map

package/dist/{antigravity-cli-MDEMPPAH.js → antigravity-cli-OM6SC3PE.js}

@@ -2,7 +2,7 @@
 import {
   AntigravityAdapter,
   adapter
-} from "./chunk-DI5S6TXJ.js";
+} from "./chunk-XC5SJ35F.js";
 import {
   addLedgerOwner,
   createLedgerEntry,
@@ -18,12 +18,12 @@ import {
 } from "./chunk-NBYKLUF6.js";
 import "./chunk-H53QZQJI.js";
 import "./chunk-BEFVJ2OE.js";
-import "./chunk-WFEHWTLM.js";
+import "./chunk-MGTDQLJJ.js";
 import {
   buildHomeBinStatuslineCommand,
   isHomeBinStatuslineCommand
 } from "./chunk-4NHXLXSD.js";
-import "./chunk-M2H7JURF.js";
+import "./chunk-UMQ6NBQR.js";
 import "./chunk-GZGLCCEE.js";
 
 // src/adapters/antigravity-cli/index.ts
@@ -464,4 +464,4 @@ export {
   adapter2 as adapter,
   antigravity_cli_default as default
 };
-//# sourceMappingURL=antigravity-cli-MDEMPPAH.js.map
+//# sourceMappingURL=antigravity-cli-OM6SC3PE.js.map

package/dist/{chunk-7UT6OB52.js → chunk-2RIFORQS.js}

@@ -2,7 +2,7 @@
 import {
   allAdapters,
   loadAdapter
-} from "./chunk-KA55FISM.js";
+} from "./chunk-SILKSP2Y.js";
 
 // src/sdk/introspect.ts
 function hostCanFireEvent(c, event) {
@@ -87,4 +87,4 @@ export {
   hostsSupporting,
   surfaceSupport
 };
-//# sourceMappingURL=chunk-7UT6OB52.js.map
+//# sourceMappingURL=chunk-2RIFORQS.js.map

package/dist/{chunk-JFXL4HYA.js → chunk-6WZODR3Z.js}

@@ -8,7 +8,7 @@ import {
 import {
   BaseAdapter,
   renderSkillMd
-} from "./chunk-WFEHWTLM.js";
+} from "./chunk-MGTDQLJJ.js";
 import {
   buildWrappedStdio,
   isHomeBinHookCommand
@@ -650,4 +650,4 @@ export {
   adapter,
   cursor_default
 };
-//# sourceMappingURL=chunk-JFXL4HYA.js.map
+//# sourceMappingURL=chunk-6WZODR3Z.js.map

package/dist/{chunk-IBLYVAWH.js → chunk-B5W3RHTI.js}

@@ -2,7 +2,7 @@
 import {
   CURSOR_EVENT_MAP,
   CURSOR_HOOKS_VERSION
-} from "./chunk-JFXL4HYA.js";
+} from "./chunk-6WZODR3Z.js";
 import {
   writeTomlString
 } from "./chunk-OPXAP3AC.js";
@@ -14,12 +14,12 @@ import {
   isConcreteSemver,
   isPlaceholderVersion,
   registryTransportType
-} from "./chunk-AY3VFNOH.js";
+} from "./chunk-KJLFGQQM.js";
 import {
   renderCommandMd,
   renderSkillMd,
   renderSubagentMd
-} from "./chunk-WFEHWTLM.js";
+} from "./chunk-MGTDQLJJ.js";
 import {
   buildHomeBinHookCommand,
   buildServeWrapperCommand,
@@ -506,12 +506,27 @@ var emitKimiPlugin = (connector, ctx) => {
 };
 
 // src/core/package-formats/npm.ts
+import { createRequire } from "module";
 import { join as join6 } from "path";
+var AGENT_CONNECTOR_PACKAGE_NAME = "@ken-jo/agent-connector";
 var EVENT_TO_OPENCODE = {
   PreToolUse: "tool.execute.before",
   PostToolUse: "tool.execute.after",
   SessionStart: "experimental.chat.system.transform"
 };
+function resolveFrameworkDependencyRange() {
+  const req = createRequire(import.meta.url);
+  for (const rel of ["../../../package.json", "../../package.json", "../package.json"]) {
+    try {
+      const pkg = req(rel);
+      if (pkg.name === AGENT_CONNECTOR_PACKAGE_NAME && typeof pkg.version === "string" && /^\d+\.\d+\.\d+/.test(pkg.version)) {
+        return `^${pkg.version}`;
+      }
+    } catch {
+    }
+  }
+  return "*";
+}
 function buildPackageJson(connector) {
   const pkgName = connector.id.startsWith("opencode-") ? connector.id : `opencode-${connector.id}`;
   const version = connector.version && connector.version !== "0.0.0" ? connector.version : "0.0.1";
@@ -523,6 +538,7 @@ function buildPackageJson(connector) {
     main: "index.js",
     exports: { ".": "./index.js" },
     keywords: ["opencode", "opencode-plugin", "pi-package", "agent-connector"],
+    dependencies: { [AGENT_CONNECTOR_PACKAGE_NAME]: resolveFrameworkDependencyRange() },
     // pi reads skills/prompts/themes/extensions from the package.json "pi" key.
     pi: { extensions: ["./index.js"], skills: ["./skills"] },
     engines: { node: ">=18.17", opencode: ">=1.0.0" }
@@ -536,7 +552,7 @@ function buildPackageJson(connector) {
   return pkg;
 }
 function buildIndexJs(connector) {
-  const homeBin = JSON.stringify("agent-connector");
+  const frameworkPackageName = JSON.stringify(AGENT_CONNECTOR_PACKAGE_NAME);
   const connectorId = JSON.stringify(connector.id);
   const events = connector.hookEvents.filter(
     (e) => EVENT_TO_OPENCODE[e] !== void 0
@@ -546,27 +562,39 @@ function buildIndexJs(connector) {
  * AUTO-GENERATED by agent-connector \u2014 DO NOT EDIT.
  *
  * Publishable OpenCode/Kilo/Pi plugin for connector ${connector.id}. It imports
- * nothing from agent-connector: every hook invocation shells out to the stable
- * home binary's universal entrypoint and JSON-parses the normalized response.
+ * no public framework APIs: every hook invocation shells out to the bundled
+ * framework runtime's universal entrypoint and JSON-parses the normalized response.
  * Fail-open: any bridge error degrades to "allow".
  */
 import { execFileSync, execSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
 
-const HOME_BIN = ${homeBin};
+const FRAMEWORK_PACKAGE_NAME = ${frameworkPackageName};
 const CONNECTOR_ID = ${connectorId};
+const require = createRequire(import.meta.url);
+
+function resolveBridgeCommand() {
+  try {
+    const pkgJson = require.resolve(FRAMEWORK_PACKAGE_NAME + "/package.json");
+    return { command: process.execPath, prefix: [join(dirname(pkgJson), "dist", "cli.js")] };
+  } catch {
+    return { command: "agent-connector", prefix: [] };
+  }
+}
+
+const BRIDGE_COMMAND = resolveBridgeCommand();
 
 function bridge(event, payload) {
   try {
-    // The published bridge resolves HOME_BIN by bare name via the consumer's
-    // PATH, where on Windows it is agent-connector.cmd. Node cannot execFile a
-    // .cmd, and shell+args is deprecated (DEP0190), so on Windows run one quoted
-    // command line via a shell (cmd.exe applies PATHEXT). POSIX keeps execFile.
-    const args = ["hook", "opencode", event, "--connector", CONNECTOR_ID];
+    // Prefer the runtime bundled as this plugin's dependency. The bare
+    // agent-connector command is only a recovery fallback for hand-built bundles.
+    const args = [...BRIDGE_COMMAND.prefix, "hook", "opencode", event, "--connector", CONNECTOR_ID];
     const opts = { input: JSON.stringify(payload), encoding: "utf8" };
     const stdout =
-      process.platform === "win32"
-        ? execSync([HOME_BIN, ...args].map((a) => '"' + a + '"').join(" "), opts)
-        : execFileSync(HOME_BIN, args, opts);
+      process.platform === "win32" && BRIDGE_COMMAND.command === "agent-connector"
+        ? execSync([BRIDGE_COMMAND.command, ...args].map((a) => '"' + a + '"').join(" "), opts)
+        : execFileSync(BRIDGE_COMMAND.command, args, opts);
     const text = (stdout || "").trim();
     if (text === "") return { decision: "allow" };
     return JSON.parse(text);
@@ -657,9 +685,9 @@ there is no uninstall verb, remove it by editing that array).
 
 ## Prerequisite
 
-Hooks shell out to the \`agent-connector\` CLI resolved from the consumer's PATH \u2014
-the consumer machine needs \`npm i -g @ken-jo/agent-connector\` (hooks silently no-op,
-fail-open, without it).
+The generated package depends on \`@ken-jo/agent-connector\` and hooks resolve that
+local runtime first. A global \`agent-connector\` binary is only a recovery fallback
+for hand-built bundles; hooks silently no-op, fail-open, if neither runtime exists.
 
 ## Before you publish
 
@@ -668,7 +696,7 @@ connector declared \`publish.author\` \u2014 set them to YOUR terms before \`npm
 `
   );
   notes.push(
-    "npm-plugin: hooks require `npm i -g @ken-jo/agent-connector` on the consumer machine (bridge resolves the CLI by name on PATH; silently fail-open without it)"
+    "npm-plugin: hooks resolve the bundled @ken-jo/agent-connector dependency first; a global agent-connector binary is only a recovery fallback, and hooks silently fail-open without either runtime"
   );
   notes.push(
     "npm-plugin: set license/author in the emitted package.json before `npm publish` \u2014 agent-connector does not license your plugin for you"
@@ -1084,4 +1112,4 @@ export {
   packageConnectorAll,
   installInstructions
 };
-//# sourceMappingURL=chunk-IBLYVAWH.js.map
+//# sourceMappingURL=chunk-B5W3RHTI.js.map