@spark-strategic/helix-core 0.1.1 → 0.1.3

package/README.md

@@ -1,75 +1,26 @@
 # @spark-strategic/helix-core
 
-The local companion you run to connect a **personal agent** to Helix — and the
-home for future local Helix tooling (e.g. an MCP server). Thin by design: it owns
-a WebSocket to `agents-api` and the chat-turn protocol, and delegates the actual
-answering to a pluggable **adapter**.
+Connect a personal agent to [Helix](https://helix.spark-strategic.ai).
 
-> This package is intended to be installed from public npm and run wherever your
-> agent lives. It never needs to run inside the Helix cloud.
+Create a personal agent in Helix, then run the command shown on its page:
 
-## Quick start
-
-```bash
-npm i -g @spark-strategic/helix-core
-
-export HELIX_CONNECTOR_SLUG=my-agent      # PersonalAgent.slug
-export HELIX_CONNECTOR_KEY=…              # connector shared secret
-helix-core connect
 ```
-
-Config resolves from (low → high precedence): built-in defaults, a `connector`
-block in `~/.helix/config.json`, environment variables, then CLI flags.
-
-| Setting | Env | Flag |
-|---|---|---|
-| agents-api base URL | `HELIX_AGENTS_API_URL` | `--url` |
-| PersonalAgent slug | `HELIX_CONNECTOR_SLUG` | `--slug` |
-| Connector key | `HELIX_CONNECTOR_KEY` | `--key` |
-
-## Bring your own agent
-
-The built-in `echo` adapter just streams your message back. To connect a real
-agent, embed the library and pass your own `AgentAdapter`:
-
-```ts
-import { Connector, resolveConfig, packageInfo, type AgentAdapter } from '@spark-strategic/helix-core';
-
-const myAdapter: AgentAdapter = {
-  name: 'my-agent',
-  version: '1.0.0',
-  async runTurn(ctx, emit) {
-    emit.status('thinking');
-    for await (const chunk of myModel(ctx.message, { signal: ctx.signal })) {
-      emit.delta(chunk);
-    }
-    return { costUsd: 0 };            // optional attribution for the Helix ledger
-  },
-};
-
-new Connector({ config: resolveConfig(), adapter: myAdapter, client: packageInfo() }).start();
+npm i -g @spark-strategic/helix-core
+helix-core init openclaw --token <personal agent token>
 ```
 
-- Resolve `runTurn` = the turn succeeded (a `chat_done` is emitted for you).
-- Throw = it failed (a `chat_error` is emitted with the message).
-- Honor `ctx.signal` — it aborts when the user hits stop or the socket drops.
-
-## Compatibility
-
-The client and the Helix server version independently, so the wire protocol is
-deliberately conservative:
+That's the whole setup. `init` enrolls the agent from your token, prepares the
+local OpenClaw gateway, and stays connected so the agent is live in Helix. Nothing
+else to configure.
 
-- **`PROTOCOL_VERSION`** is bumped only on a *breaking* wire change. Additive
-  features are announced via `capabilities` on the connect handshake instead —
-  so an old connector and a new server (or vice-versa) still interoperate.
-- **Unknown inbound frames are ignored**, never fatal. Helix can add new frames
-  without breaking older connectors.
-- On connect the client sends a `connector_hello` with its package version, which
-  Helix records so it can nudge you when a newer release is available. You are
-  never *forced* to update unless a minimum version is enforced server-side.
+## Notes
 
-## Extending
+- Your **personal agent token** comes from the agent's page in Helix — copy the
+  command straight from there.
+- Re-running `init` is safe.
+- The agent stays online while the command runs. To run it under a process
+  manager instead, add `--no-connect` and start it separately with
+  `helix-core connect --adapter openclaw`.
+- `helix-core help` lists every option.
 
-Additional package tools are added as **new CLI subcommands** (beside `connect`),
-not by overloading the adapter interface. The adapter is only the personal-agent
-chat seam.
+MIT © Spark Strategic

package/dist/cli.js

@@ -11,6 +11,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const config_1 = require("./config");
 const connector_1 = require("./connector");
 const adapter_1 = require("./adapter");
+const openclaw_adapter_1 = require("./openclaw-adapter");
+const init_1 = require("./init");
 const version_1 = require("./version");
 /** Minimal flag parser: `--key value`, `--key=value`, and boolean `--flag`. */
 function parseArgs(argv) {
@@ -18,6 +20,11 @@ function parseArgs(argv) {
     const flags = {};
     for (let i = 0; i < rest.length; i += 1) {
         const arg = rest[i];
+        // Single-dash boolean short flags (e.g. `-y`).
+        if (/^-[a-zA-Z]$/.test(arg)) {
+            flags[arg.slice(1)] = true;
+            continue;
+        }
         if (!arg.startsWith('--'))
             continue;
         const body = arg.slice(2);
@@ -45,20 +52,27 @@ function overridesFromFlags(flags) {
         o.key = flags.key;
     return o;
 }
-/** Resolve the adapter named by `--adapter`. Only the reference echo adapter ships
- *  in-box; real adapters are expected to embed the library, not go through the CLI.
- *  Kept as a lookup so additional built-ins can be registered later. */
-function selectAdapter(name) {
+/** Resolve the adapter named by `--adapter`. The `echo` reference and the
+ *  `openclaw` gateway bridge ship in-box; other custom agents are expected to
+ *  embed the library and pass their own AgentAdapter rather than go through the
+ *  CLI. Kept as a lookup so additional built-ins can be registered later. */
+function selectAdapter(name, flags) {
     switch ((name ?? 'echo').toLowerCase()) {
         case 'echo':
             return new adapter_1.EchoAdapter();
+        case 'openclaw':
+            return new openclaw_adapter_1.OpenClawAdapter({
+                baseUrl: typeof flags['openclaw-url'] === 'string' ? flags['openclaw-url'] : undefined,
+                token: typeof flags['openclaw-token'] === 'string' ? flags['openclaw-token'] : undefined,
+                agentId: typeof flags['openclaw-agent'] === 'string' ? flags['openclaw-agent'] : undefined,
+            });
         default:
-            throw new Error(`Unknown adapter "${name}". Built-in: echo. For a custom agent, embed the library and pass your own AgentAdapter.`);
+            throw new Error(`Unknown adapter "${name}". Built-in: echo, openclaw. For a custom agent, embed the library and pass your own AgentAdapter.`);
     }
 }
 function runConnect(flags) {
     const config = (0, config_1.resolveConfig)(overridesFromFlags(flags));
-    const adapter = selectAdapter(typeof flags.adapter === 'string' ? flags.adapter : undefined);
+    const adapter = selectAdapter(typeof flags.adapter === 'string' ? flags.adapter : undefined, flags);
     const client = (0, version_1.packageInfo)();
     const connector = new connector_1.Connector({ config, adapter, client });
     connector.start();
@@ -70,21 +84,23 @@ function runConnect(flags) {
     process.on('SIGINT', () => shutdown('SIGINT'));
     process.on('SIGTERM', () => shutdown('SIGTERM'));
 }
-const HELP = `helix-core — connect a personal agent (and future tools) to Helix
+const HELP = `helix-core — connect a personal agent to Helix
+
+Setup (one command, from your agent's page in Helix):
+  helix-core init openclaw --token <personal agent token>
 
-Usage:
-  helix-core connect [options]     Attach as a PersonalAgent and service chat turns
-  helix-core version               Print package + protocol version
-  helix-core help                  Show this help
+That enrolls the agent, prepares the local OpenClaw gateway, and stays connected.
 
-Options (connect):
-  --url <url>        agents-api base URL (default: https://agents-api.spark-strategic.ai)
-  --slug <slug>      PersonalAgent slug to attach as
-  --key <key>        Connector shared secret
-  --adapter <name>   Built-in adapter to run (default: echo)
+Other commands:
+  helix-core version    Print package + protocol version
+  helix-core help       Show this help
 
-Config also resolves from ~/.helix/config.json (a "connector" block) and env:
-  HELIX_AGENTS_API_URL, HELIX_CONNECTOR_SLUG, HELIX_CONNECTOR_KEY
+Options (init openclaw):
+  --token <token>   Personal agent token from Helix (required for first setup)
+  --yes, -y         Skip the pre-restart confirmation prompt
+  --no-restart      Configure only; don't restart the gateway
+  --no-connect      Configure only; don't stay attached after setup
+  --agent <id>      OpenClaw agent id to route turns to (default: main)
 `;
 function main() {
     const { command, flags } = parseArgs(process.argv.slice(2));
@@ -107,6 +123,27 @@ function main() {
                 process.exit(1);
             }
             break;
+        case 'init': {
+            // `init <target>` — target is the first positional after the command.
+            const target = process.argv.slice(3).find((a) => !a.startsWith('-'));
+            if (target !== 'openclaw') {
+                console.error(`[helix-core] unknown init target "${target ?? ''}" — supported: openclaw\n`);
+                console.log(HELP);
+                process.exit(1);
+            }
+            (0, init_1.runInitOpenClaw)({
+                token: typeof flags.token === 'string' ? flags.token : undefined,
+                yes: flags.yes === true || flags.y === true,
+                noRestart: flags['no-restart'] === true,
+                noConnect: flags['no-connect'] === true,
+                agent: typeof flags.agent === 'string' ? flags.agent : undefined,
+                url: typeof flags.url === 'string' ? flags.url : undefined,
+            }).catch((err) => {
+                console.error(`[helix-core] ${err instanceof Error ? err.message : String(err)}`);
+                process.exit(1);
+            });
+            break;
+        }
         default:
             console.error(`[helix-core] unknown command "${command}"\n`);
             console.log(HELP);

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -14,6 +14,11 @@ export interface ConnectorConfig {
     /** Shared secret presented on the socket. Matches PersonalAgent.connectorKey. */
     key: string;
 }
+export declare const DEFAULT_AGENTS_API_URL = "https://agents-api.spark-strategic.ai";
+/** Resolve the agents-api base URL from (low → high): default, ~/.helix
+ *  config, env, explicit override. Used by enrollment before a full connector
+ *  config exists (there's no slug/key yet at that point). */
+export declare function resolveAgentsApiUrl(override?: string): string;
 export type ConfigOverrides = Partial<ConnectorConfig>;
 /**
  * Resolve the effective connector config. Throws a clear error if a required

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;CACb;AAID,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;AAkBvD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,GAAE,eAAoB,GAAG,eAAe,CAiC9E;AAED,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAG9D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;CACb;AAED,eAAO,MAAM,sBAAsB,0CAA0C,CAAC;AAE9E;;6DAE6D;AAC7D,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAY7D;AAED,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;AAkBvD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,GAAE,eAAoB,GAAG,eAAe,CAiC9E;AAED,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAG9D"}

package/dist/config.js

@@ -41,12 +41,28 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_AGENTS_API_URL = void 0;
+exports.resolveAgentsApiUrl = resolveAgentsApiUrl;
 exports.resolveConfig = resolveConfig;
 exports.connectorWsUrl = connectorWsUrl;
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
-const DEFAULT_AGENTS_API_URL = 'https://agents-api.spark-strategic.ai';
+exports.DEFAULT_AGENTS_API_URL = 'https://agents-api.spark-strategic.ai';
+/** Resolve the agents-api base URL from (low → high): default, ~/.helix
+ *  config, env, explicit override. Used by enrollment before a full connector
+ *  config exists (there's no slug/key yet at that point). */
+function resolveAgentsApiUrl(override) {
+    const file = readConfigFile();
+    const fileConnector = (file.connector && typeof file.connector === 'object'
+        ? file.connector
+        : {});
+    return (str(override) ??
+        str(process.env.HELIX_AGENTS_API_URL) ??
+        str(fileConnector.agentsApiUrl) ??
+        str(file.agentsApiUrl) ??
+        exports.DEFAULT_AGENTS_API_URL);
+}
 function readConfigFile() {
     const configPath = path.join(os.homedir(), '.helix', 'config.json');
     if (!fs.existsSync(configPath))
@@ -78,7 +94,7 @@ function resolveConfig(overrides = {}) {
         str(process.env.HELIX_AGENTS_API_URL) ??
         str(fileConnector.agentsApiUrl) ??
         str(file.agentsApiUrl) ??
-        DEFAULT_AGENTS_API_URL;
+        exports.DEFAULT_AGENTS_API_URL;
     const slug = overrides.slug ??
         str(process.env.HELIX_CONNECTOR_SLUG) ??
         str(fileConnector.slug);

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoBH,kDAYC;AAwBD,sCAiCC;AAGD,wCAGC;AA7FD,uCAAyB;AACzB,uCAAyB;AACzB,2CAA6B;AAWhB,QAAA,sBAAsB,GAAG,uCAAuC,CAAC;AAE9E;;6DAE6D;AAC7D,SAAgB,mBAAmB,CAAC,QAAiB;IACnD,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,MAAM,aAAa,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ;QACzE,CAAC,CAAE,IAAI,CAAC,SAAqC;QAC7C,CAAC,CAAC,EAAE,CAAC,CAAC;IACR,OAAO,CACL,GAAG,CAAC,QAAQ,CAAC;QACb,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;QACrC,GAAG,CAAC,aAAa,CAAC,YAAY,CAAC;QAC/B,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC;QACtB,8BAAsB,CACvB,CAAC;AACJ,CAAC;AAID,SAAS,cAAc;IACrB,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;IACpE,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;QAChE,OAAO,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAkC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CAAC,mDAAmD,EAAE,GAAG,CAAC,CAAC;QACvE,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,GAAG,CAAC,CAAU;IACrB,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,YAA6B,EAAE;IAC3D,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,+EAA+E;IAC/E,yDAAyD;IACzD,MAAM,aAAa,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ;QACzE,CAAC,CAAE,IAAI,CAAC,SAAqC;QAC7C,CAAC,CAAC,EAAE,CAAC,CAAC;IAER,MAAM,YAAY,GAChB,SAAS,CAAC,YAAY;QACtB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;QACrC,GAAG,CAAC,aAAa,CAAC,YAAY,CAAC;QAC/B,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC;QACtB,8BAAsB,CAAC;IAEzB,MAAM,IAAI,GACR,SAAS,CAAC,IAAI;QACd,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;QACrC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAE1B,MAAM,GAAG,GACP,SAAS,CAAC,GAAG;QACb,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;QACpC,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAEzB,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;IACjE,IAAI,CAAC,GAAG;QAAE,OAAO,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;IAC7D,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,wCAAwC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,IAAK,EAAE,GAAG,EAAE,GAAI,EAAE,CAAC;AAClD,CAAC;AAED,8DAA8D;AAC9D,SAAgB,cAAc,CAAC,MAAuB;IACpD,MAAM,IAAI,GAAG,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC5E,OAAO,GAAG,IAAI,iBAAiB,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,kBAAkB,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;AACzG,CAAC"}

package/dist/index.d.ts

@@ -7,6 +7,7 @@
  */
 export * from './protocol';
 export * from './adapter';
+export * from './openclaw-adapter';
 export * from './config';
 export * from './connector';
 export { packageInfo, PROTOCOL_VERSION } from './version';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -24,6 +24,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROTOCOL_VERSION = exports.packageInfo = void 0;
 __exportStar(require("./protocol"), exports);
 __exportStar(require("./adapter"), exports);
+__exportStar(require("./openclaw-adapter"), exports);
 __exportStar(require("./config"), exports);
 __exportStar(require("./connector"), exports);
 var version_1 = require("./version");

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;;AAEH,6CAA2B;AAC3B,4CAA0B;AAC1B,2CAAyB;AACzB,8CAA4B;AAC5B,qCAA0D;AAAjD,sGAAA,WAAW,OAAA;AAAE,2GAAA,gBAAgB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;;AAEH,6CAA2B;AAC3B,4CAA0B;AAC1B,qDAAmC;AACnC,2CAAyB;AACzB,8CAA4B;AAC5B,qCAA0D;AAAjD,sGAAA,WAAW,OAAA;AAAE,2GAAA,gBAAgB,OAAA"}

package/dist/init.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `helix-core init openclaw` — one-shot setup that makes a local OpenClaw
+ * gateway reachable by the OpenClaw adapter.
+ *
+ * The adapter (openclaw-adapter.ts) talks to the gateway's OpenAI-compatible
+ * `/v1/chat/completions` endpoint, which ships **disabled by default**. Rather
+ * than making the operator hand-edit config and remember to restart, this
+ * command:
+ *
+ *   1. seeds the `openclaw` block in ~/.helix/config.json (gateway url + token +
+ *      agent id) so `helix-core connect --adapter openclaw` needs no flags,
+ *   2. flips `gateway.http.endpoints.chatCompletions.enabled = true` — but
+ *      PROMPTS first, because OpenClaw watches its config file and this write
+ *      auto-restarts the gateway (kind:"restart", default reload mode "hybrid"),
+ *      briefly taking it offline. The prompt therefore gates the WRITE, not a
+ *      later restart; on "hot"/"off" reload modes we restart explicitly instead.
+ *
+ * On enabling the flag we PREFER the first-class `openclaw config set`, but fall
+ * back to a direct JSON merge of the OpenClaw config file when the CLI rejects it
+ * (older CLIs whose schema predates the endpoint, or whose `config` subcommand
+ * resolves a different store than the file). Reads always come from the file,
+ * because `openclaw config get` proved unreliable across versions.
+ *
+ * Idempotent: re-running is safe (already-enabled is detected and reported).
+ */
+export interface InitFlags {
+    /** Personal agent token from the Helix UI — the one credential the operator
+     *  supplies. Enrolled to discover the agent slug; no slug/URL needed. */
+    token?: string;
+    /** Skip the pre-restart confirmation prompt (non-interactive installs). */
+    yes?: boolean;
+    /** Configure only; do not restart the gateway. */
+    noRestart?: boolean;
+    /** Configure only; don't stay attached after setup. */
+    noConnect?: boolean;
+    /** OpenClaw agent id turns should route to (default: main). */
+    agent?: string;
+    /** Advanced: override the agents-api base URL (defaults to the Helix cloud). */
+    url?: string;
+}
+/** Locate OpenClaw's config file. Mirrors OpenClaw's own resolution order:
+ *  OPENCLAW_CONFIG (explicit file) → OPENCLAW_HOME/openclaw.json → ~/.openclaw/openclaw.json. */
+export declare function openclawConfigPath(): string;
+/** `helix-core init openclaw` handler. */
+export declare function runInitOpenClaw(flags: InitFlags): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAgBH,MAAM,WAAW,SAAS;IACxB;6EACyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,kDAAkD;IAClD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,uDAAuD;IACvD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AA4DD;iGACiG;AACjG,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAsFD,0CAA0C;AAC1C,wBAAsB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CA0HrE"}

package/dist/init.js

@@ -0,0 +1,338 @@
+"use strict";
+/**
+ * `helix-core init openclaw` — one-shot setup that makes a local OpenClaw
+ * gateway reachable by the OpenClaw adapter.
+ *
+ * The adapter (openclaw-adapter.ts) talks to the gateway's OpenAI-compatible
+ * `/v1/chat/completions` endpoint, which ships **disabled by default**. Rather
+ * than making the operator hand-edit config and remember to restart, this
+ * command:
+ *
+ *   1. seeds the `openclaw` block in ~/.helix/config.json (gateway url + token +
+ *      agent id) so `helix-core connect --adapter openclaw` needs no flags,
+ *   2. flips `gateway.http.endpoints.chatCompletions.enabled = true` — but
+ *      PROMPTS first, because OpenClaw watches its config file and this write
+ *      auto-restarts the gateway (kind:"restart", default reload mode "hybrid"),
+ *      briefly taking it offline. The prompt therefore gates the WRITE, not a
+ *      later restart; on "hot"/"off" reload modes we restart explicitly instead.
+ *
+ * On enabling the flag we PREFER the first-class `openclaw config set`, but fall
+ * back to a direct JSON merge of the OpenClaw config file when the CLI rejects it
+ * (older CLIs whose schema predates the endpoint, or whose `config` subcommand
+ * resolves a different store than the file). Reads always come from the file,
+ * because `openclaw config get` proved unreliable across versions.
+ *
+ * Idempotent: re-running is safe (already-enabled is detected and reported).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openclawConfigPath = openclawConfigPath;
+exports.runInitOpenClaw = runInitOpenClaw;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
+const config_1 = require("./config");
+const connector_1 = require("./connector");
+const openclaw_adapter_1 = require("./openclaw-adapter");
+const version_1 = require("./version");
+const ENDPOINT_PATH = 'gateway.http.endpoints.chatCompletions.enabled';
+const DEFAULT_AGENT_ID = 'main';
+const DEFAULT_PORT = 18789;
+/** Exchange a personal agent token for its routable slug via the agents-api
+ *  enrollment endpoint. The token is the only identity the operator has; this is
+ *  how the connector discovers everything else. Throws a clear error on a bad
+ *  token or an unreachable API. */
+async function enrollConnector(token, agentsApiUrl) {
+    const base = agentsApiUrl.replace(/\/+$/, '');
+    let res;
+    try {
+        res = await fetch(`${base}/api/connector/enroll`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ token }),
+        });
+    }
+    catch (err) {
+        throw new Error(`could not reach Helix at ${base} to enroll (${err instanceof Error ? err.message : String(err)}). Check your connection and try again.`);
+    }
+    if (res.status === 401) {
+        throw new Error('that personal agent token was not recognized. Copy the exact command from the Helix agent page and try again.');
+    }
+    if (!res.ok) {
+        let detail = '';
+        try {
+            detail = (await res.json()).message ?? '';
+        }
+        catch { /* ignore */ }
+        throw new Error(`enrollment failed (${res.status})${detail ? `: ${detail}` : ''}.`);
+    }
+    const body = (await res.json());
+    if (!body.slug)
+        throw new Error('enrollment succeeded but returned no agent slug — please report this.');
+    return { slug: body.slug, name: body.name ?? body.slug };
+}
+/** Merge the resolved connector identity (slug + key + api url) into the
+ *  `connector` block of ~/.helix/config.json so `connect` needs no flags/env. */
+function seedHelixConnectorBlock(block) {
+    const configPath = path.join(os.homedir(), '.helix', 'config.json');
+    const existing = readJsonFile(configPath, true);
+    const prev = (existing.connector && typeof existing.connector === 'object'
+        ? existing.connector
+        : {});
+    existing.connector = { ...prev, ...block };
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, `${JSON.stringify(existing, null, 2)}\n`, 'utf-8');
+    return configPath;
+}
+/** Run an `openclaw` subcommand and capture output. Uses `shell:true` with a
+ *  single trusted command string (all callers pass fixed constants — no user
+ *  input) so Windows resolves `openclaw.cmd` without the args-splitting
+ *  deprecation. Returns ok:false (never throws) if the CLI is missing/fails. */
+function openclaw(args) {
+    const res = (0, child_process_1.spawnSync)(`openclaw ${args}`, { encoding: 'utf-8', shell: true });
+    if (res.error)
+        return { ok: false, stdout: '', stderr: String(res.error.message ?? res.error) };
+    return { ok: res.status === 0, stdout: (res.stdout ?? '').trim(), stderr: (res.stderr ?? '').trim() };
+}
+/** Locate OpenClaw's config file. Mirrors OpenClaw's own resolution order:
+ *  OPENCLAW_CONFIG (explicit file) → OPENCLAW_HOME/openclaw.json → ~/.openclaw/openclaw.json. */
+function openclawConfigPath() {
+    const explicit = process.env.OPENCLAW_CONFIG?.trim();
+    if (explicit)
+        return explicit;
+    const home = process.env.OPENCLAW_HOME?.trim();
+    if (home)
+        return path.join(home, 'openclaw.json');
+    return path.join(os.homedir(), '.openclaw', 'openclaw.json');
+}
+/** Read + parse a JSON config file. Strips a leading UTF-8 BOM (OpenClaw writes
+ *  one on Windows and `JSON.parse` rejects it). `strict` throws on a present but
+ *  unparseable file so write paths never clobber real config; non-strict returns
+ *  {} (used for best-effort reads). Missing file → {} in both modes. */
+function readJsonFile(file, strict = false) {
+    if (!fs.existsSync(file))
+        return {};
+    let raw = fs.readFileSync(file, 'utf-8');
+    if (raw.charCodeAt(0) === 0xFEFF)
+        raw = raw.slice(1); // strip UTF-8 BOM (OpenClaw writes one on Windows)
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch (err) {
+        if (strict) {
+            throw new Error(`refusing to edit ${file} — it exists but isn't valid JSON (${err instanceof Error ? err.message : String(err)}). Fix it and re-run.`);
+        }
+        return {};
+    }
+}
+/** Read a nested value by dot-path from an already-parsed object. */
+function getPath(obj, dotPath) {
+    let cur = obj;
+    for (const key of dotPath.split('.')) {
+        if (!cur || typeof cur !== 'object')
+            return undefined;
+        cur = cur[key];
+    }
+    return cur;
+}
+/** Deep-set a nested value by dot-path, creating intermediate objects. */
+function setPath(obj, dotPath, value) {
+    const keys = dotPath.split('.');
+    let cur = obj;
+    for (let i = 0; i < keys.length - 1; i += 1) {
+        const k = keys[i];
+        if (!cur[k] || typeof cur[k] !== 'object')
+            cur[k] = {};
+        cur = cur[k];
+    }
+    cur[keys[keys.length - 1]] = value;
+}
+/** Ask a yes/no question on the TTY. Resolves true only on an explicit yes.
+ *  No TTY (piped/CI) → false; callers should pass --yes in that case. */
+function confirm(question) {
+    if (!process.stdin.isTTY)
+        return Promise.resolve(false);
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`${question} [y/N] `, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+/** Merge a partial `openclaw` block into ~/.helix/config.json, preserving the
+ *  rest of the file (the SAME file helix-os / the connector read). */
+function seedHelixOpenClawBlock(block) {
+    const configPath = path.join(os.homedir(), '.helix', 'config.json');
+    const existing = readJsonFile(configPath, true);
+    const prev = (existing.openclaw && typeof existing.openclaw === 'object'
+        ? existing.openclaw
+        : {});
+    existing.openclaw = { ...prev, ...block };
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, `${JSON.stringify(existing, null, 2)}\n`, 'utf-8');
+    return configPath;
+}
+/** Enable the endpoint. Prefer the first-class `openclaw config set`, but the
+ *  ONLY source of truth is the config file the gateway actually reads — some
+ *  CLI builds report success without persisting there. So we always re-read the
+ *  file to verify, and fall back to a direct JSON merge if it didn't land.
+ *  Returns how it was ultimately applied so the caller can report honestly. */
+function enableEndpoint(cfgPath) {
+    openclaw(`config set ${ENDPOINT_PATH} true --strict-json`); // best effort
+    if (getPath(readJsonFile(cfgPath), ENDPOINT_PATH) === true)
+        return 'cli';
+    const cfg = readJsonFile(cfgPath, true);
+    setPath(cfg, ENDPOINT_PATH, true);
+    fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
+    fs.writeFileSync(cfgPath, `${JSON.stringify(cfg, null, 2)}\n`, 'utf-8');
+    return 'file';
+}
+/** `helix-core init openclaw` handler. */
+async function runInitOpenClaw(flags) {
+    const log = (m) => console.log(`[helix-core] ${m}`);
+    // 0a. Enroll the personal agent token, if given. This is the primary path: one
+    //     token in, everything (slug + saved connector identity) out. The plaintext
+    //     token doubles as the socket key, so it's stored alongside the slug.
+    if (flags.token) {
+        const agentsApiUrl = (0, config_1.resolveAgentsApiUrl)(flags.url);
+        log('enrolling personal agent…');
+        const agent = await enrollConnector(flags.token, agentsApiUrl);
+        seedHelixConnectorBlock({ slug: agent.slug, key: flags.token, agentsApiUrl });
+        log(`enrolled as "${agent.name}" (${agent.slug}).`);
+    }
+    // 0b. Confirm the OpenClaw CLI is present (we need it to restart the gateway).
+    if (!openclaw('--version').ok) {
+        throw new Error('openclaw CLI not found on PATH — install/enable OpenClaw first, then re-run `helix-core init openclaw`.');
+    }
+    const cfgPath = openclawConfigPath();
+    const cfg = readJsonFile(cfgPath);
+    log(`using OpenClaw config: ${cfgPath}`);
+    // 1. Seed ~/.helix/config.json `openclaw` block so `connect` needs no flags.
+    //    This is non-disruptive (a different file the gateway doesn't watch), so we
+    //    do all the harmless prep BEFORE the one action that bounces the gateway.
+    const portRaw = getPath(cfg, 'gateway.port');
+    const port = typeof portRaw === 'number' ? portRaw : DEFAULT_PORT;
+    const authMode = getPath(cfg, 'gateway.auth.mode');
+    const tokenRaw = getPath(cfg, 'gateway.auth.token');
+    const token = authMode === 'token' && typeof tokenRaw === 'string' ? tokenRaw : undefined;
+    const agentId = flags.agent?.trim() || DEFAULT_AGENT_ID;
+    const block = { url: `http://127.0.0.1:${port}`, agentId };
+    if (token)
+        block.token = token;
+    const written = seedHelixOpenClawBlock(block);
+    log(`seeded openclaw block in ${written} (url + agentId${token ? ' + token' : ''}).`);
+    if (authMode === 'token' && !token) {
+        log('note: gateway auth is "token" but no token was found — set OPENCLAW_GATEWAY_TOKEN or gateway.auth.token before connecting.');
+    }
+    // 2. Enable the OpenAI-compatible endpoint — the ONLY disruptive step.
+    //
+    //    OpenClaw watches its own config file and auto-restarts the gateway on any
+    //    `gateway.*` change (reload rule kind:"restart", default mode "hybrid").
+    //    So the WRITE below is what takes the gateway briefly offline — not a
+    //    separate restart afterwards. An earlier version prompted AFTER the write
+    //    and then issued its own `gateway restart`, which meant the operator's
+    //    gateway had already bounced before they saw the warning (and bounced a
+    //    second time). The confirmation must gate the write itself.
+    if (getPath(cfg, ENDPOINT_PATH) === true) {
+        log(`${ENDPOINT_PATH} already enabled — nothing to change, no restart.`);
+    }
+    else if (flags.noRestart) {
+        log(`${ENDPOINT_PATH} is disabled; enabling it edits the gateway config and restarts the gateway — skipped because --no-restart.`);
+        log(`Enable it when ready with: openclaw config set ${ENDPOINT_PATH} true`);
+    }
+    else {
+        const proceed = flags.yes ||
+            (await confirm('Enabling the OpenClaw chat endpoint edits your gateway config, which briefly restarts the gateway (offline for a moment). Continue?'));
+        if (!proceed) {
+            log('left the chat endpoint disabled and your gateway untouched. Re-run when ready.');
+            return;
+        }
+        // Whether the config write auto-restarts depends on the reload mode: "hybrid"
+        // (default) and "restart" bounce the gateway for us; "hot" and "off" won't
+        // apply a gateway change, so we restart explicitly to make the endpoint live.
+        const reloadMode = getPath(cfg, 'gateway.reload.mode');
+        const autoRestarts = reloadMode === undefined || reloadMode === 'hybrid' || reloadMode === 'restart';
+        const how = enableEndpoint(cfgPath);
+        log(`enabled ${ENDPOINT_PATH} (${how === 'cli' ? 'via openclaw config' : 'via direct config edit'}).`);
+        if (autoRestarts) {
+            log('gateway is restarting to apply (OpenClaw auto-restarts on a config change).');
+        }
+        else {
+            log(`restarting gateway to apply (reload mode "${String(reloadMode)}" won't auto-apply a gateway change)…`);
+            const restart = openclaw('gateway restart');
+            if (!restart.ok) {
+                throw new Error(`gateway restart failed: ${restart.stderr || restart.stdout || 'unknown error'} — run \`openclaw gateway restart\` manually.`);
+            }
+            log('gateway restarted.');
+        }
+    }
+    // 4. Attach and stay connected. This makes `init` the ONLY command an operator
+    //    runs — setup and going-live in one shot. Opt out with --no-connect (e.g.
+    //    to run the connector under a process manager separately).
+    if (flags.noConnect) {
+        log('setup complete. Start the agent later with: helix-core connect --adapter openclaw');
+        return;
+    }
+    let config;
+    try {
+        config = (0, config_1.resolveConfig)();
+    }
+    catch (err) {
+        // No connector identity on this box (init ran without --token and none was
+        // pre-configured). Setup is still done; just can't auto-connect.
+        log(`setup complete. ${err instanceof Error ? err.message : String(err)}`);
+        log('re-run with your personal agent token to go live: helix-core init openclaw --token <token>');
+        return;
+    }
+    log('setup complete — bringing the agent online…');
+    const connector = new connector_1.Connector({
+        config,
+        adapter: new openclaw_adapter_1.OpenClawAdapter({ agentId: flags.agent }),
+        client: (0, version_1.packageInfo)(),
+    });
+    connector.start();
+    const shutdown = (signal) => {
+        console.log(`\n[helix-core] ${signal} — shutting down`);
+        connector.stop();
+        process.exit(0);
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4FH,gDAMC;AAuFD,0CA0HC;AAjTD,iDAA0C;AAC1C,uCAAyB;AACzB,uCAAyB;AACzB,2CAA6B;AAC7B,mDAAqC;AACrC,qCAA8D;AAC9D,2CAAwC;AACxC,yDAAqD;AACrD,uCAAwC;AAExC,MAAM,aAAa,GAAG,gDAAgD,CAAC;AACvE,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAChC,MAAM,YAAY,GAAG,KAAK,CAAC;AAuB3B;;;mCAGmC;AACnC,KAAK,UAAU,eAAe,CAAC,KAAa,EAAE,YAAoB;IAChE,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC9C,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,uBAAuB,EAAE;YAChD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC;SAChC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,eAAe,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,yCAAyC,CAAC,CAAC;IAC5J,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,+GAA+G,CAAC,CAAC;IACnI,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,CAAC;YAAC,MAAM,GAAI,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA0B,CAAC,OAAO,IAAI,EAAE,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;QACnG,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,CAAC,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACtF,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA2B,CAAC;IAC1D,IAAI,CAAC,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IACzG,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;AAC3D,CAAC;AAED;iFACiF;AACjF,SAAS,uBAAuB,CAAC,KAA0D;IACzF,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;IACpE,MAAM,QAAQ,GAAG,YAAY,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,IAAI,OAAO,QAAQ,CAAC,SAAS,KAAK,QAAQ;QACxE,CAAC,CAAE,QAAQ,CAAC,SAAqC;QACjD,CAAC,CAAC,EAAE,CAAC,CAAC;IACR,QAAQ,CAAC,SAAS,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC;IAC3C,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAChF,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;gFAGgF;AAChF,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,GAAG,GAAG,IAAA,yBAAS,EAAC,YAAY,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9E,IAAI,GAAG,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;IAChG,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;AACxG,CAAC;AAED;iGACiG;AACjG,SAAgB,kBAAkB;IAChC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC;IACrD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,EAAE,CAAC;IAC/C,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IAClD,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,WAAW,EAAE,eAAe,CAAC,CAAC;AAC/D,CAAC;AAED;;;wEAGwE;AACxE,SAAS,YAAY,CAAC,IAAY,EAAE,MAAM,GAAG,KAAK;IAChD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,IAAI,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzC,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM;QAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,mDAAmD;IACzG,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,OAAO,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAkC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,sCAAsC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;QACzJ,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,qEAAqE;AACrE,SAAS,OAAO,CAAC,GAA4B,EAAE,OAAe;IAC5D,IAAI,GAAG,GAAY,GAAG,CAAC;IACvB,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACtD,GAAG,GAAI,GAA+B,CAAC,GAAG,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,0EAA0E;AAC1E,SAAS,OAAO,CAAC,GAA4B,EAAE,OAAe,EAAE,KAAc;IAC5E,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,GAAG,GAAG,GAAG,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,KAAK,QAAQ;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;QACvD,GAAG,GAAG,GAAG,CAAC,CAAC,CAA4B,CAAC;IAC1C,CAAC;IACD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;AACrC,CAAC;AAED;yEACyE;AACzE,SAAS,OAAO,CAAC,QAAgB;IAC/B,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACxD,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACtF,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,EAAE,CAAC,QAAQ,CAAC,GAAG,QAAQ,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE;YAC3C,EAAE,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC3C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;sEACsE;AACtE,SAAS,sBAAsB,CAAC,KAA8B;IAC5D,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;IACpE,MAAM,QAAQ,GAAG,YAAY,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,IAAI,OAAO,QAAQ,CAAC,QAAQ,KAAK,QAAQ;QACtE,CAAC,CAAE,QAAQ,CAAC,QAAoC;QAChD,CAAC,CAAC,EAAE,CAAC,CAAC;IACR,QAAQ,CAAC,QAAQ,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC;IAC1C,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAChF,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;+EAI+E;AAC/E,SAAS,cAAc,CAAC,OAAe;IACrC,QAAQ,CAAC,cAAc,aAAa,qBAAqB,CAAC,CAAC,CAAC,cAAc;IAC1E,IAAI,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAEzE,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACxC,OAAO,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,CAAC,CAAC;IAClC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACxE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,0CAA0C;AACnC,KAAK,UAAU,eAAe,CAAC,KAAgB;IACpD,MAAM,GAAG,GAAG,CAAC,CAAS,EAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;IAElE,+EAA+E;IAC/E,gFAAgF;IAChF,0EAA0E;IAC1E,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,YAAY,GAAG,IAAA,4BAAmB,EAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpD,GAAG,CAAC,2BAA2B,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,KAAK,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;QAC/D,uBAAuB,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;QAC9E,GAAG,CAAC,gBAAgB,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC;IACtD,CAAC;IAED,+EAA+E;IAC/E,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,EAAE,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,yGAAyG,CAC1G,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;IACrC,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAClC,GAAG,CAAC,0BAA0B,OAAO,EAAE,CAAC,CAAC;IAEzC,6EAA6E;IAC7E,gFAAgF;IAChF,8EAA8E;IAC9E,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IAC7C,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC;IAClE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;IACnD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,QAAQ,KAAK,OAAO,IAAI,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1F,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,gBAAgB,CAAC;IAExD,MAAM,KAAK,GAA4B,EAAE,GAAG,EAAE,oBAAoB,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC;IACpF,IAAI,KAAK;QAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;IAE/B,MAAM,OAAO,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;IAC9C,GAAG,CAAC,4BAA4B,OAAO,kBAAkB,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACtF,IAAI,QAAQ,KAAK,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;QACnC,GAAG,CAAC,4HAA4H,CAAC,CAAC;IACpI,CAAC;IAED,uEAAuE;IACvE,EAAE;IACF,+EAA+E;IAC/E,6EAA6E;IAC7E,0EAA0E;IAC1E,8EAA8E;IAC9E,2EAA2E;IAC3E,4EAA4E;IAC5E,gEAAgE;IAChE,IAAI,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,KAAK,IAAI,EAAE,CAAC;QACzC,GAAG,CAAC,GAAG,aAAa,mDAAmD,CAAC,CAAC;IAC3E,CAAC;SAAM,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QAC3B,GAAG,CAAC,GAAG,aAAa,6GAA6G,CAAC,CAAC;QACnI,GAAG,CAAC,kDAAkD,aAAa,OAAO,CAAC,CAAC;IAC9E,CAAC;SAAM,CAAC;QACN,MAAM,OAAO,GACX,KAAK,CAAC,GAAG;YACT,CAAC,MAAM,OAAO,CACZ,qIAAqI,CACtI,CAAC,CAAC;QACL,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,GAAG,CAAC,gFAAgF,CAAC,CAAC;YACtF,OAAO;QACT,CAAC;QACD,8EAA8E;QAC9E,2EAA2E;QAC3E,8EAA8E;QAC9E,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC;QACvD,MAAM,YAAY,GAChB,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,SAAS,CAAC;QAClF,MAAM,GAAG,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QACpC,GAAG,CAAC,WAAW,aAAa,KAAK,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,wBAAwB,IAAI,CAAC,CAAC;QACvG,IAAI,YAAY,EAAE,CAAC;YACjB,GAAG,CAAC,6EAA6E,CAAC,CAAC;QACrF,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,6CAA6C,MAAM,CAAC,UAAU,CAAC,uCAAuC,CAAC,CAAC;YAC5G,MAAM,OAAO,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAAC;YAC5C,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;gBAChB,MAAM,IAAI,KAAK,CAAC,2BAA2B,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,IAAI,eAAe,+CAA+C,CAAC,CAAC;YACjJ,CAAC;YACD,GAAG,CAAC,oBAAoB,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,8EAA8E;IAC9E,+DAA+D;IAC/D,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACpB,GAAG,CAAC,mFAAmF,CAAC,CAAC;QACzF,OAAO;IACT,CAAC;IAED,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,IAAA,sBAAa,GAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,2EAA2E;QAC3E,iEAAiE;QACjE,GAAG,CAAC,mBAAmB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3E,GAAG,CAAC,4FAA4F,CAAC,CAAC;QAClG,OAAO;IACT,CAAC;IAED,GAAG,CAAC,6CAA6C,CAAC,CAAC;IACnD,MAAM,SAAS,GAAG,IAAI,qBAAS,CAAC;QAC9B,MAAM;QACN,OAAO,EAAE,IAAI,kCAAe,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;QACtD,MAAM,EAAE,IAAA,qBAAW,GAAE;KACtB,CAAC,CAAC;IACH,SAAS,CAAC,KAAK,EAAE,CAAC;IAElB,MAAM,QAAQ,GAAG,CAAC,MAAc,EAAQ,EAAE;QACxC,OAAO,CAAC,GAAG,CAAC,kBAAkB,MAAM,kBAAkB,CAAC,CAAC;QACxD,SAAS,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;AACnD,CAAC"}

package/dist/openclaw-adapter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * OpenClaw adapter — bridges a Helix chat turn to a locally-running OpenClaw
+ * gateway. This is the piece that makes an OpenClaw instance a Helix
+ * PersonalAgent: the connector owns the socket, this owns "how a turn is
+ * answered" by forwarding it to the gateway's OpenAI-compatible endpoint and
+ * streaming the reply back.
+ *
+ * There is NO proxy and nothing gets configured on OpenClaw's side beyond
+ * enabling the endpoint — the connector is the client. Flow:
+ *
+ *   Helix chat → agents-api → /ws/connector/:slug → Connector
+ *     → OpenClawAdapter.runTurn() → POST gateway /v1/chat/completions (SSE)
+ *
+ * Requires the gateway's OpenAI-compatible endpoint to be enabled (off by
+ * default): `gateway.http.endpoints.chatCompletions.enabled = true`.
+ */
+import type { AgentAdapter, TurnContext, TurnEmitter, TurnResult } from './adapter';
+export interface OpenClawAdapterOptions {
+    /** Gateway base URL (http/https). Default http://127.0.0.1:18789. */
+    baseUrl?: string;
+    /** Bearer token for the gateway (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN).
+     *  Optional — omitted if the gateway runs with auth disabled. */
+    token?: string;
+    /** OpenClaw agent id to route turns to (encoded as model `openclaw:<id>`). */
+    agentId?: string;
+}
+/**
+ * Resolve OpenClaw connection settings. Precedence (low → high):
+ *   built-in defaults  <  ~/.helix/config.json (`openclaw` block)  <  env  <  opts
+ *
+ * Env: OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, OPENCLAW_AGENT_ID.
+ */
+export declare function resolveOpenClawOptions(opts?: OpenClawAdapterOptions): Required<Pick<OpenClawAdapterOptions, 'baseUrl' | 'agentId'>> & {
+    token?: string;
+};
+/**
+ * Streams turns from Helix to an OpenClaw gateway's OpenAI-compatible
+ * `/v1/chat/completions` endpoint (same run path as `openclaw agent`).
+ */
+export declare class OpenClawAdapter implements AgentAdapter {
+    readonly name = "openclaw";
+    readonly version = "0.1.0";
+    readonly capabilities: string[];
+    private readonly baseUrl;
+    private readonly token?;
+    private readonly agentId;
+    constructor(options?: OpenClawAdapterOptions);
+    runTurn(ctx: TurnContext, emit: TurnEmitter): Promise<TurnResult>;
+}
+//# sourceMappingURL=openclaw-adapter.d.ts.map

package/dist/openclaw-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openclaw-adapter.d.ts","sourceRoot":"","sources":["../src/openclaw-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAMpF,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;qEACiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,GAAE,sBAA2B,GAAG,QAAQ,CAAC,IAAI,CAAC,sBAAsB,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAwB5J;AAcD;;;GAGG;AACH,qBAAa,eAAgB,YAAW,YAAY;IAClD,QAAQ,CAAC,IAAI,cAAc;IAC3B,QAAQ,CAAC,OAAO,WAAmB;IACnC,QAAQ,CAAC,YAAY,WAAgB;IAErC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,GAAE,sBAA2B;IAO1C,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;CAqFxE"}

package/dist/openclaw-adapter.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * OpenClaw adapter — bridges a Helix chat turn to a locally-running OpenClaw
+ * gateway. This is the piece that makes an OpenClaw instance a Helix
+ * PersonalAgent: the connector owns the socket, this owns "how a turn is
+ * answered" by forwarding it to the gateway's OpenAI-compatible endpoint and
+ * streaming the reply back.
+ *
+ * There is NO proxy and nothing gets configured on OpenClaw's side beyond
+ * enabling the endpoint — the connector is the client. Flow:
+ *
+ *   Helix chat → agents-api → /ws/connector/:slug → Connector
+ *     → OpenClawAdapter.runTurn() → POST gateway /v1/chat/completions (SSE)
+ *
+ * Requires the gateway's OpenAI-compatible endpoint to be enabled (off by
+ * default): `gateway.http.endpoints.chatCompletions.enabled = true`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenClawAdapter = void 0;
+exports.resolveOpenClawOptions = resolveOpenClawOptions;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const ADAPTER_VERSION = '0.1.0';
+const DEFAULT_GATEWAY_URL = 'http://127.0.0.1:18789';
+const DEFAULT_AGENT_ID = 'main';
+/**
+ * Resolve OpenClaw connection settings. Precedence (low → high):
+ *   built-in defaults  <  ~/.helix/config.json (`openclaw` block)  <  env  <  opts
+ *
+ * Env: OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, OPENCLAW_AGENT_ID.
+ */
+function resolveOpenClawOptions(opts = {}) {
+    const file = readOpenClawConfigBlock();
+    const str = (v) => typeof v === 'string' && v.trim() ? v.trim() : undefined;
+    const baseUrl = opts.baseUrl ??
+        str(process.env.OPENCLAW_GATEWAY_URL) ??
+        str(file.baseUrl) ??
+        str(file.url) ??
+        DEFAULT_GATEWAY_URL;
+    const token = opts.token ??
+        str(process.env.OPENCLAW_GATEWAY_TOKEN) ??
+        str(file.token);
+    const agentId = opts.agentId ??
+        str(process.env.OPENCLAW_AGENT_ID) ??
+        str(file.agentId) ??
+        DEFAULT_AGENT_ID;
+    return { baseUrl: baseUrl.replace(/\/+$/, ''), token, agentId };
+}
+function readOpenClawConfigBlock() {
+    const configPath = path.join(os.homedir(), '.helix', 'config.json');
+    if (!fs.existsSync(configPath))
+        return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        const block = parsed && typeof parsed === 'object' ? parsed.openclaw : undefined;
+        return block && typeof block === 'object' ? block : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Streams turns from Helix to an OpenClaw gateway's OpenAI-compatible
+ * `/v1/chat/completions` endpoint (same run path as `openclaw agent`).
+ */
+class OpenClawAdapter {
+    name = 'openclaw';
+    version = ADAPTER_VERSION;
+    capabilities = ['openclaw'];
+    baseUrl;
+    token;
+    agentId;
+    constructor(options = {}) {
+        const resolved = resolveOpenClawOptions(options);
+        this.baseUrl = resolved.baseUrl;
+        this.token = resolved.token;
+        this.agentId = resolved.agentId;
+    }
+    async runTurn(ctx, emit) {
+        const started = Date.now();
+        const url = `${this.baseUrl}/v1/chat/completions`;
+        emit.status('thinking');
+        const headers = { 'Content-Type': 'application/json' };
+        if (this.token)
+            headers.Authorization = `Bearer ${this.token}`;
+        const body = JSON.stringify({
+            model: `openclaw:${this.agentId}`,
+            stream: true,
+            // Deriving a stable session key from `user` lets a multi-turn Helix chat
+            // reuse one OpenClaw agent session (see gateway "Session behavior").
+            user: ctx.sessionId,
+            messages: [{ role: 'user', content: ctx.message }],
+        });
+        let res;
+        try {
+            res = await fetch(url, { method: 'POST', headers, body, signal: ctx.signal });
+        }
+        catch (err) {
+            if (ctx.signal.aborted)
+                throw new Error('aborted');
+            throw new Error(`OpenClaw gateway unreachable at ${this.baseUrl} — is \`openclaw gateway\` running? (${err instanceof Error ? err.message : String(err)})`);
+        }
+        if (!res.ok) {
+            const detail = (await res.text().catch(() => '')).slice(0, 500);
+            if (res.status === 404) {
+                throw new Error(`OpenClaw gateway returned 404 for ${url} — enable the OpenAI endpoint: gateway.http.endpoints.chatCompletions.enabled = true`);
+            }
+            if (res.status === 401 || res.status === 403) {
+                throw new Error(`OpenClaw gateway rejected auth (${res.status}) — check the gateway token. ${detail}`);
+            }
+            throw new Error(`OpenClaw gateway error ${res.status}: ${detail || res.statusText}`);
+        }
+        if (!res.body)
+            throw new Error('OpenClaw gateway returned no response body');
+        let model;
+        let usage;
+        let sawContent = false;
+        const decoder = new TextDecoder();
+        let buffer = '';
+        // SSE: events separated by a blank line; each carries `data: <json>` lines,
+        // terminated by `data: [DONE]`. We tolerate multi-line data and CRLF.
+        for await (const chunk of res.body) {
+            if (ctx.signal.aborted)
+                throw new Error('aborted');
+            buffer += decoder.decode(chunk, { stream: true });
+            let sep;
+            while ((sep = indexOfEvent(buffer)) !== -1) {
+                const rawEvent = buffer.slice(0, sep);
+                buffer = buffer.slice(sep).replace(/^(\r?\n){1,2}/, '');
+                const dataStr = extractData(rawEvent);
+                if (dataStr === null)
+                    continue;
+                if (dataStr === '[DONE]') {
+                    buffer = '';
+                    break;
+                }
+                let json;
+                try {
+                    json = JSON.parse(dataStr);
+                }
+                catch {
+                    continue;
+                }
+                if (typeof json?.model === 'string')
+                    model = json.model;
+                if (json?.usage)
+                    usage = json.usage;
+                const delta = json?.choices?.[0]?.delta?.content;
+                if (typeof delta === 'string' && delta.length) {
+                    sawContent = true;
+                    emit.delta(delta);
+                }
+            }
+        }
+        if (!sawContent)
+            emit.status('done');
+        return {
+            model,
+            usage,
+            costUsd: null, // gateway runs don't report cost through this endpoint
+            durationMs: Date.now() - started,
+        };
+    }
+}
+exports.OpenClawAdapter = OpenClawAdapter;
+/** Index just past the end of the first complete SSE event (its blank-line
+ *  delimiter), or -1 if no complete event is buffered yet. */
+function indexOfEvent(buf) {
+    const nn = buf.indexOf('\n\n');
+    const rn = buf.indexOf('\r\n\r\n');
+    if (nn === -1)
+        return rn === -1 ? -1 : rn + 4;
+    if (rn === -1)
+        return nn + 2;
+    return Math.min(nn + 2, rn + 4);
+}
+/** Concatenate the `data:` lines of one SSE event, or null if it has none. */
+function extractData(event) {
+    const parts = [];
+    for (const line of event.split(/\r?\n/)) {
+        if (line.startsWith('data:'))
+            parts.push(line.slice(5).replace(/^ /, ''));
+    }
+    return parts.length ? parts.join('\n') : null;
+}
+//# sourceMappingURL=openclaw-adapter.js.map

package/dist/openclaw-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openclaw-adapter.js","sourceRoot":"","sources":["../src/openclaw-adapter.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spark-strategic/helix-core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Helix Core — the minimal local runtime you run to connect a personal agent to Helix. Other tools (MCP, etc.) ship as their own packages that Core runs.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",