@spark-strategic/helix-core 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# @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**.
+
+> 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.
+
+## 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();
+```
+
+- 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:
+
+- **`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.
+
+## Extending
+
+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.

package/dist/adapter.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Agent adapter contract — the seam between the Helix transport and whatever
+ * actually answers a chat turn (an OpenClaw instance, a local LLM, a canned
+ * bot…). The connector owns the socket and the frame protocol; an adapter only
+ * has to turn a turn's text into streamed output. This keeps the transport
+ * reusable and adapters trivially unit-testable with no socket.
+ *
+ * Extensibility note: adapters are the intended extension point for personal
+ * agents. Additional package tools (e.g. a future Helix MCP server) are separate
+ * CLI subcommands, NOT adapters — see cli.ts. Do not overload this interface with
+ * tool-hosting concerns.
+ */
+/** Everything an adapter is handed for one turn. `raw` carries the full inbound
+ *  payload for adapters that want fields beyond the typed subset — but treat the
+ *  typed fields as the stable contract; anything in `raw` may change. */
+export interface TurnContext {
+    sessionId: string;
+    message: string;
+    agentId?: string;
+    model?: string;
+    providerRef?: string;
+    user?: {
+        id?: string;
+        email?: string;
+        name?: string;
+    };
+    org?: string;
+    agentName?: string;
+    designatedContact?: string;
+    scopeDirective?: string;
+    /** Full inbound `chat_message` payload, verbatim. Forward-compat escape hatch. */
+    raw: Record<string, unknown>;
+    /** Aborts when Helix sends `chat_close` (user hit stop) or the socket drops.
+     *  A well-behaved adapter should stop streaming promptly when this fires. */
+    signal: AbortSignal;
+}
+/** How an adapter streams a turn back. The connector maps these to wire frames;
+ *  it emits the terminal `chat_done`/`chat_error` itself (from runTurn resolving
+ *  or throwing), so an adapter never touches transport. */
+export interface TurnEmitter {
+    /** Append streamed assistant text. */
+    delta(text: string): void;
+    /** Surface a tool-use chip (cosmetic; the label is shown to the user as-is). */
+    tool(name: string, phase: 'call' | 'result', ok?: boolean): void;
+    /** Update the live "processing…" status line (optional, coalesced by the UI). */
+    status(text: string): void;
+}
+/** Optional attribution an adapter can return so Helix can ledger the turn. */
+export interface TurnResult {
+    providerRef?: string;
+    model?: string;
+    costUsd?: number | null;
+    usage?: unknown;
+    durationMs?: number;
+}
+export interface AgentAdapter {
+    /** Stable adapter id, reported in the hello frame (e.g. 'echo', 'openclaw'). */
+    readonly name: string;
+    /** Adapter semver, reported in the hello frame. */
+    readonly version: string;
+    /** Extra capability flags this adapter contributes to the hello frame. */
+    readonly capabilities?: string[];
+    /** Run one turn. Resolve = the turn succeeded (connector emits chat_done);
+     *  throw = it failed (connector emits chat_error). Honor `ctx.signal`. */
+    runTurn(ctx: TurnContext, emit: TurnEmitter): Promise<TurnResult | void>;
+}
+/**
+ * Reference adapter: streams the user's own message back a few characters at a
+ * time. Exists so the connector is runnable end-to-end out of the box and as the
+ * copy-paste starting point for a real adapter. Not meant for production use.
+ */
+export declare class EchoAdapter implements AgentAdapter {
+    readonly name = "echo";
+    readonly version = "0.1.0";
+    readonly capabilities: never[];
+    runTurn(ctx: TurnContext, emit: TurnEmitter): Promise<TurnResult>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;yEAEyE;AACzE,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B;iFAC6E;IAC7E,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;2DAE2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gFAAgF;IAChF,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,EAAE,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACjE,iFAAiF;IACjF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC;8EAC0E;IAC1E,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;CAC1E;AAED;;;;GAIG;AACH,qBAAa,WAAY,YAAW,YAAY;IAC9C,QAAQ,CAAC,IAAI,UAAU;IACvB,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,YAAY,UAAM;IAErB,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;CAWxE"}

package/dist/adapter.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Agent adapter contract — the seam between the Helix transport and whatever
+ * actually answers a chat turn (an OpenClaw instance, a local LLM, a canned
+ * bot…). The connector owns the socket and the frame protocol; an adapter only
+ * has to turn a turn's text into streamed output. This keeps the transport
+ * reusable and adapters trivially unit-testable with no socket.
+ *
+ * Extensibility note: adapters are the intended extension point for personal
+ * agents. Additional package tools (e.g. a future Helix MCP server) are separate
+ * CLI subcommands, NOT adapters — see cli.ts. Do not overload this interface with
+ * tool-hosting concerns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EchoAdapter = void 0;
+/**
+ * Reference adapter: streams the user's own message back a few characters at a
+ * time. Exists so the connector is runnable end-to-end out of the box and as the
+ * copy-paste starting point for a real adapter. Not meant for production use.
+ */
+class EchoAdapter {
+    name = 'echo';
+    version = '0.1.0';
+    capabilities = [];
+    async runTurn(ctx, emit) {
+        const started = Date.now();
+        const reply = `You said: ${ctx.message}`;
+        emit.status('echoing');
+        for (let i = 0; i < reply.length; i += 8) {
+            if (ctx.signal.aborted)
+                throw new Error('aborted');
+            emit.delta(reply.slice(i, i + 8));
+            await sleep(20);
+        }
+        return { costUsd: 0, durationMs: Date.now() - started };
+    }
+}
+exports.EchoAdapter = EchoAdapter;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAwDH;;;;GAIG;AACH,MAAa,WAAW;IACb,IAAI,GAAG,MAAM,CAAC;IACd,OAAO,GAAG,OAAO,CAAC;IAClB,YAAY,GAAG,EAAE,CAAC;IAE3B,KAAK,CAAC,OAAO,CAAC,GAAgB,EAAE,IAAiB;QAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,aAAa,GAAG,CAAC,OAAO,EAAE,CAAC;QACzC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YACzC,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO;gBAAE,MAAM,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;YACnD,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAClC,MAAM,KAAK,CAAC,EAAE,CAAC,CAAC;QAClB,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;IAC1D,CAAC;CACF;AAhBD,kCAgBC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * `helix-core` CLI.
+ *
+ * Structured as a subcommand registry from day one so future package tools (e.g.
+ * a `helix-core mcp` server) slot in beside `connect` without reshaping the
+ * entrypoint. Each command is a small handler; unknown commands print help.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;GAMG"}

package/dist/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * `helix-core` CLI.
+ *
+ * Structured as a subcommand registry from day one so future package tools (e.g.
+ * a `helix-core mcp` server) slot in beside `connect` without reshaping the
+ * entrypoint. Each command is a small handler; unknown commands print help.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_1 = require("./config");
+const connector_1 = require("./connector");
+const adapter_1 = require("./adapter");
+const version_1 = require("./version");
+/** Minimal flag parser: `--key value`, `--key=value`, and boolean `--flag`. */
+function parseArgs(argv) {
+    const [command = 'connect', ...rest] = argv;
+    const flags = {};
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (!arg.startsWith('--'))
+            continue;
+        const body = arg.slice(2);
+        const eq = body.indexOf('=');
+        if (eq >= 0) {
+            flags[body.slice(0, eq)] = body.slice(eq + 1);
+        }
+        else if (i + 1 < rest.length && !rest[i + 1].startsWith('--')) {
+            flags[body] = rest[i + 1];
+            i += 1;
+        }
+        else {
+            flags[body] = true;
+        }
+    }
+    return { command, flags };
+}
+function overridesFromFlags(flags) {
+    const o = {};
+    if (typeof flags.url === 'string')
+        o.agentsApiUrl = flags.url;
+    if (typeof flags.slug === 'string')
+        o.slug = flags.slug;
+    if (typeof flags.key === 'string')
+        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) {
+    switch ((name ?? 'echo').toLowerCase()) {
+        case 'echo':
+            return new adapter_1.EchoAdapter();
+        default:
+            throw new Error(`Unknown adapter "${name}". Built-in: echo. 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 client = (0, version_1.packageInfo)();
+    const connector = new connector_1.Connector({ config, adapter, client });
+    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'));
+}
+const HELP = `helix-core — connect a personal agent (and future tools) to Helix
+
+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
+
+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)
+
+Config also resolves from ~/.helix/config.json (a "connector" block) and env:
+  HELIX_AGENTS_API_URL, HELIX_CONNECTOR_SLUG, HELIX_CONNECTOR_KEY
+`;
+function main() {
+    const { command, flags } = parseArgs(process.argv.slice(2));
+    if (flags.help || command === 'help') {
+        console.log(HELP);
+        return;
+    }
+    if (flags.version || command === 'version') {
+        const info = (0, version_1.packageInfo)();
+        console.log(`${info.name} ${info.version} (protocol ${version_1.PROTOCOL_VERSION})`);
+        return;
+    }
+    switch (command) {
+        case 'connect':
+            try {
+                runConnect(flags);
+            }
+            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);
+            process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Connector configuration resolution. Precedence (low → high):
+ *   built-in defaults  <  ~/.helix/config.json  <  environment  <  explicit opts
+ *
+ * Reuses the same `~/.helix/config.json` file and `HELIX_AGENTS_API_URL` env var
+ * as helix-os, so a box already running a Helix node needs only the two
+ * connector-specific secrets (slug + key) added.
+ */
+export interface ConnectorConfig {
+    /** agents-api base URL (http/https; converted to ws/wss for the socket). */
+    agentsApiUrl: string;
+    /** PersonalAgent.slug — the routable handle this connector attaches as. */
+    slug: string;
+    /** Shared secret presented on the socket. Matches PersonalAgent.connectorKey. */
+    key: string;
+}
+export type ConfigOverrides = Partial<ConnectorConfig>;
+/**
+ * Resolve the effective connector config. Throws a clear error if a required
+ * secret (slug/key) is missing after all sources are merged.
+ */
+export declare function resolveConfig(overrides?: ConfigOverrides): ConnectorConfig;
+/** Build the connector WebSocket URL from resolved config. */
+export declare function connectorWsUrl(config: ConnectorConfig): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +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"}

package/dist/config.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Connector configuration resolution. Precedence (low → high):
+ *   built-in defaults  <  ~/.helix/config.json  <  environment  <  explicit opts
+ *
+ * Reuses the same `~/.helix/config.json` file and `HELIX_AGENTS_API_URL` env var
+ * as helix-os, so a box already running a Helix node needs only the two
+ * connector-specific secrets (slug + key) added.
+ */
+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.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';
+function readConfigFile() {
+    const configPath = path.join(os.homedir(), '.helix', 'config.json');
+    if (!fs.existsSync(configPath))
+        return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch (err) {
+        console.warn('helix-core: failed to parse ~/.helix/config.json:', err);
+        return {};
+    }
+}
+function str(v) {
+    return typeof v === 'string' && v.trim() ? v.trim() : undefined;
+}
+/**
+ * Resolve the effective connector config. Throws a clear error if a required
+ * secret (slug/key) is missing after all sources are merged.
+ */
+function resolveConfig(overrides = {}) {
+    const file = readConfigFile();
+    // The connector reads its own block under `connector` in ~/.helix/config.json,
+    // falling back to top-level for the shared agentsApiUrl.
+    const fileConnector = (file.connector && typeof file.connector === 'object'
+        ? file.connector
+        : {});
+    const agentsApiUrl = overrides.agentsApiUrl ??
+        str(process.env.HELIX_AGENTS_API_URL) ??
+        str(fileConnector.agentsApiUrl) ??
+        str(file.agentsApiUrl) ??
+        DEFAULT_AGENTS_API_URL;
+    const slug = overrides.slug ??
+        str(process.env.HELIX_CONNECTOR_SLUG) ??
+        str(fileConnector.slug);
+    const key = overrides.key ??
+        str(process.env.HELIX_CONNECTOR_KEY) ??
+        str(fileConnector.key);
+    const missing = [];
+    if (!slug)
+        missing.push('slug (HELIX_CONNECTOR_SLUG or --slug)');
+    if (!key)
+        missing.push('key (HELIX_CONNECTOR_KEY or --key)');
+    if (missing.length) {
+        throw new Error(`helix-core: missing required config: ${missing.join(', ')}`);
+    }
+    return { agentsApiUrl, slug: slug, key: key };
+}
+/** Build the connector WebSocket URL from resolved config. */
+function connectorWsUrl(config) {
+    const base = config.agentsApiUrl.replace(/^http/, 'ws').replace(/\/+$/, '');
+    return `${base}/ws/connector/${encodeURIComponent(config.slug)}?key=${encodeURIComponent(config.key)}`;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/connector.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The Helix local connector: a thin, long-lived WebSocket client that attaches a
+ * PersonalAgent to agents-api over `/ws/connector/:slug` and services chat turns
+ * by delegating to a pluggable {@link AgentAdapter}.
+ *
+ * Scope is deliberately narrow (cf. the much heavier helix-os node): no terminal,
+ * no logs, no workflow execution — just the chat_* turn lifecycle plus a hello
+ * handshake for version reporting. Everything agent-specific lives behind the
+ * adapter; everything transport-specific lives here.
+ */
+import type { AgentAdapter } from './adapter';
+import type { ConnectorConfig } from './config';
+export interface Logger {
+    debug(msg: string, meta?: unknown): void;
+    info(msg: string, meta?: unknown): void;
+    warn(msg: string, meta?: unknown): void;
+    error(msg: string, meta?: unknown): void;
+}
+export interface ConnectorOptions {
+    config: ConnectorConfig;
+    adapter: AgentAdapter;
+    /** This package's identity, reported in the hello frame for update nudges. */
+    client: {
+        name: string;
+        version: string;
+    };
+    logger?: Logger;
+    pingIntervalMs?: number;
+    pongTimeoutMs?: number;
+    maxReconnectDelayMs?: number;
+}
+export declare class Connector {
+    private readonly opts;
+    private ws;
+    private stopped;
+    private reconnectAttempts;
+    private pingTimer;
+    private pongTimer;
+    /** In-flight turns, keyed by sessionId, so chat_close can abort the right one. */
+    private readonly turns;
+    private readonly log;
+    private readonly pingIntervalMs;
+    private readonly pongTimeoutMs;
+    private readonly maxReconnectDelayMs;
+    constructor(opts: ConnectorOptions);
+    /** Open the socket and keep it open (auto-reconnect) until {@link stop}. */
+    start(): void;
+    /** Close the socket for good and abort any in-flight turns. */
+    stop(): void;
+    private connect;
+    private scheduleReconnect;
+    private startPingLoop;
+    private onPong;
+    private clearTimers;
+    private sendHello;
+    private onMessage;
+    private onChatStart;
+    private onChatClose;
+    private onChatMessage;
+    private sendRaw;
+}
+//# sourceMappingURL=connector.d.ts.map

package/dist/connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../src/connector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAwC,MAAM,WAAW,CAAC;AACpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAehD,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1C;AASD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,YAAY,CAAC;IACtB,8EAA8E;IAC9E,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAMD,qBAAa,SAAS;IAcR,OAAO,CAAC,QAAQ,CAAC,IAAI;IAbjC,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,SAAS,CAA+B;IAChD,kFAAkF;IAClF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsC;IAE5D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;gBAEhB,IAAI,EAAE,gBAAgB;IAOnD,4EAA4E;IAC5E,KAAK,IAAI,IAAI;IAKb,+DAA+D;IAC/D,IAAI,IAAI,IAAI;IAWZ,OAAO,CAAC,OAAO;IAqCf,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,SAAS;IAcjB,OAAO,CAAC,SAAS;IAyBjB,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,WAAW;YAML,aAAa;IAiD3B,OAAO,CAAC,OAAO;CAWhB"}

package/dist/connector.js

@@ -0,0 +1,295 @@
+"use strict";
+/**
+ * The Helix local connector: a thin, long-lived WebSocket client that attaches a
+ * PersonalAgent to agents-api over `/ws/connector/:slug` and services chat turns
+ * by delegating to a pluggable {@link AgentAdapter}.
+ *
+ * Scope is deliberately narrow (cf. the much heavier helix-os node): no terminal,
+ * no logs, no workflow execution — just the chat_* turn lifecycle plus a hello
+ * handshake for version reporting. Everything agent-specific lives behind the
+ * adapter; everything transport-specific lives here.
+ */
+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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Connector = void 0;
+const ws_1 = __importDefault(require("ws"));
+const os = __importStar(require("os"));
+const config_1 = require("./config");
+const protocol_1 = require("./protocol");
+const consoleLogger = {
+    debug: (m, x) => console.debug(`[helix-core] ${m}`, x ?? ''),
+    info: (m, x) => console.log(`[helix-core] ${m}`, x ?? ''),
+    warn: (m, x) => console.warn(`[helix-core] ${m}`, x ?? ''),
+    error: (m, x) => console.error(`[helix-core] ${m}`, x ?? ''),
+};
+const DEFAULT_PING_INTERVAL_MS = 30000;
+const DEFAULT_PONG_TIMEOUT_MS = 10000;
+const DEFAULT_MAX_RECONNECT_DELAY_MS = 60000;
+class Connector {
+    opts;
+    ws = null;
+    stopped = false;
+    reconnectAttempts = 0;
+    pingTimer = null;
+    pongTimer = null;
+    /** In-flight turns, keyed by sessionId, so chat_close can abort the right one. */
+    turns = new Map();
+    log;
+    pingIntervalMs;
+    pongTimeoutMs;
+    maxReconnectDelayMs;
+    constructor(opts) {
+        this.opts = opts;
+        this.log = opts.logger ?? consoleLogger;
+        this.pingIntervalMs = opts.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
+        this.pongTimeoutMs = opts.pongTimeoutMs ?? DEFAULT_PONG_TIMEOUT_MS;
+        this.maxReconnectDelayMs = opts.maxReconnectDelayMs ?? DEFAULT_MAX_RECONNECT_DELAY_MS;
+    }
+    /** Open the socket and keep it open (auto-reconnect) until {@link stop}. */
+    start() {
+        this.stopped = false;
+        this.connect();
+    }
+    /** Close the socket for good and abort any in-flight turns. */
+    stop() {
+        this.stopped = true;
+        this.clearTimers();
+        for (const [, abort] of this.turns)
+            abort.abort();
+        this.turns.clear();
+        if (this.ws) {
+            try {
+                this.ws.close(1000, 'shutting down');
+            }
+            catch { /* ignore */ }
+            this.ws = null;
+        }
+    }
+    connect() {
+        const url = (0, config_1.connectorWsUrl)(this.opts.config);
+        this.log.info(`connecting as "${this.opts.config.slug}"`, { url: url.split('?')[0] });
+        const ws = new ws_1.default(url);
+        this.ws = ws;
+        ws.on('open', () => {
+            this.reconnectAttempts = 0;
+            this.log.info('connected');
+            this.sendHello();
+            this.startPingLoop();
+        });
+        // The `ws` client auto-replies to server WS-level pings with pong, which is
+        // what keeps agents-api's `lastPingAt` fresh. We track our OWN ping/pong to
+        // detect a dead server and force a reconnect.
+        ws.on('pong', () => { this.onPong(); });
+        ws.on('message', (data) => { this.onMessage(data); });
+        ws.on('close', (code, reason) => {
+            this.log.warn(`disconnected (${code} ${reason.toString() || ''})`);
+            this.clearTimers();
+            // A dropped socket kills every in-flight turn; abort so adapters unwind.
+            for (const [, abort] of this.turns)
+                abort.abort();
+            this.turns.clear();
+            if (this.ws === ws)
+                this.ws = null;
+            this.scheduleReconnect();
+        });
+        ws.on('error', (err) => {
+            this.log.error('socket error', err instanceof Error ? err.message : String(err));
+            // 'close' fires after 'error'; reconnect is scheduled there.
+        });
+    }
+    scheduleReconnect() {
+        if (this.stopped)
+            return;
+        this.reconnectAttempts += 1;
+        const delay = Math.min(this.maxReconnectDelayMs, 1000 * Math.pow(2, Math.min(this.reconnectAttempts, 6)));
+        this.log.info(`reconnecting in ${Math.round(delay / 1000)}s (attempt ${this.reconnectAttempts})`);
+        setTimeout(() => { if (!this.stopped)
+            this.connect(); }, delay);
+    }
+    // --- Keepalive -----------------------------------------------------------
+    startPingLoop() {
+        this.clearTimers();
+        this.pingTimer = setInterval(() => {
+            if (!this.ws || this.ws.readyState !== ws_1.default.OPEN)
+                return;
+            try {
+                this.ws.ping();
+            }
+            catch { /* ignore */ }
+            // If no pong before the timeout, the socket is a zombie — terminate it and
+            // let 'close' drive a reconnect.
+            if (this.pongTimer)
+                clearTimeout(this.pongTimer);
+            this.pongTimer = setTimeout(() => {
+                this.log.warn('pong timeout — terminating stale socket');
+                try {
+                    this.ws?.terminate();
+                }
+                catch { /* ignore */ }
+            }, this.pongTimeoutMs);
+        }, this.pingIntervalMs);
+    }
+    onPong() {
+        if (this.pongTimer) {
+            clearTimeout(this.pongTimer);
+            this.pongTimer = null;
+        }
+    }
+    clearTimers() {
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = null;
+        }
+        if (this.pongTimer) {
+            clearTimeout(this.pongTimer);
+            this.pongTimer = null;
+        }
+    }
+    // --- Handshake -----------------------------------------------------------
+    sendHello() {
+        const hello = {
+            type: 'connector_hello',
+            protocol: protocol_1.PROTOCOL_VERSION,
+            client: this.opts.client,
+            adapter: { name: this.opts.adapter.name, version: this.opts.adapter.version },
+            capabilities: ['chat', ...(this.opts.adapter.capabilities ?? [])],
+            host: { platform: os.platform(), arch: os.arch(), node: process.version },
+        };
+        this.sendRaw(hello);
+    }
+    // --- Inbound dispatch ----------------------------------------------------
+    onMessage(data) {
+        const frame = (0, protocol_1.parseServerFrame)(data.toString());
+        if (!frame) {
+            this.log.debug('dropping unparseable frame');
+            return;
+        }
+        switch (frame.type) {
+            case 'ping':
+                // App-level ping; WS-level pong already handled by the client. No-op.
+                return;
+            case 'chat_start':
+                this.onChatStart(frame.payload ?? {});
+                return;
+            case 'chat_message':
+                void this.onChatMessage(frame.payload ?? {});
+                return;
+            case 'chat_close':
+                this.onChatClose(frame.payload ?? {});
+                return;
+            default:
+                // Forward-compat: an unknown frame from a newer server is ignored, not
+                // fatal. This is the promise that lets Helix add frames without breaking
+                // older connectors (see protocol.ts).
+                this.log.debug(`ignoring unknown frame "${frame.type}"`);
+        }
+    }
+    onChatStart(payload) {
+        const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : undefined;
+        if (!sessionId)
+            return;
+        // Ack so the surface can enable its composer; the turn itself spawns on the
+        // following chat_message (mirrors helix-os handleChatStart).
+        this.sendRaw((0, protocol_1.chatStarted)(sessionId));
+    }
+    onChatClose(payload) {
+        const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : undefined;
+        if (!sessionId)
+            return;
+        this.turns.get(sessionId)?.abort();
+    }
+    async onChatMessage(payload) {
+        const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : undefined;
+        const message = typeof payload.message === 'string' ? payload.message : undefined;
+        if (!sessionId || message === undefined)
+            return;
+        if (this.turns.has(sessionId)) {
+            this.sendRaw((0, protocol_1.chatError)(sessionId, 'A turn is already in progress for this session'));
+            return;
+        }
+        const abort = new AbortController();
+        this.turns.set(sessionId, abort);
+        const emit = {
+            delta: (text) => this.sendRaw((0, protocol_1.chatDelta)(sessionId, text)),
+            tool: (name, phase, ok) => this.sendRaw((0, protocol_1.chatTool)(sessionId, name, phase, ok)),
+            status: (text) => this.sendRaw((0, protocol_1.chatStatus)(sessionId, text)),
+        };
+        const ctx = {
+            sessionId,
+            message,
+            agentId: typeof payload.agentId === 'string' ? payload.agentId : undefined,
+            model: typeof payload.model === 'string' ? payload.model : undefined,
+            providerRef: typeof payload.providerRef === 'string' ? payload.providerRef : undefined,
+            user: (payload.user && typeof payload.user === 'object') ? payload.user : undefined,
+            org: typeof payload.org === 'string' ? payload.org : undefined,
+            agentName: typeof payload.agentName === 'string' ? payload.agentName : undefined,
+            designatedContact: typeof payload.designatedContact === 'string' ? payload.designatedContact : undefined,
+            scopeDirective: typeof payload.scopeDirective === 'string' ? payload.scopeDirective : undefined,
+            raw: payload,
+            signal: abort.signal,
+        };
+        this.log.info('turn starting', { sessionId, agentId: ctx.agentId });
+        try {
+            const result = (await this.opts.adapter.runTurn(ctx, emit));
+            this.sendRaw((0, protocol_1.chatDone)(sessionId, result ?? {}));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.sendRaw((0, protocol_1.chatError)(sessionId, msg));
+        }
+        finally {
+            this.turns.delete(sessionId);
+            this.log.info('turn ended', { sessionId });
+        }
+    }
+    // --- Outbound ------------------------------------------------------------
+    sendRaw(frame) {
+        if (!this.ws || this.ws.readyState !== ws_1.default.OPEN) {
+            this.log.debug('drop outbound frame (socket not open)', { type: frame.type });
+            return;
+        }
+        try {
+            this.ws.send(JSON.stringify(frame));
+        }
+        catch (err) {
+            this.log.warn('failed to send frame', err instanceof Error ? err.message : String(err));
+        }
+    }
+}
+exports.Connector = Connector;
+//# sourceMappingURL=connector.js.map

package/dist/connector.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Public API surface for `@spark-strategic/helix-core`.
+ *
+ * Embedders (e.g. an OpenClaw process that wants to be a personal agent) import
+ * the {@link Connector} and supply their own {@link AgentAdapter}, rather than
+ * shelling out to the CLI. The CLI (cli.ts) is just one consumer of this surface.
+ */
+export * from './protocol';
+export * from './adapter';
+export * from './config';
+export * from './connector';
+export { packageInfo, PROTOCOL_VERSION } from './version';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Public API surface for `@spark-strategic/helix-core`.
+ *
+ * Embedders (e.g. an OpenClaw process that wants to be a personal agent) import
+ * the {@link Connector} and supply their own {@link AgentAdapter}, rather than
+ * shelling out to the CLI. The CLI (cli.ts) is just one consumer of this surface.
+ */
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOL_VERSION = exports.packageInfo = void 0;
+__exportStar(require("./protocol"), exports);
+__exportStar(require("./adapter"), exports);
+__exportStar(require("./config"), exports);
+__exportStar(require("./connector"), exports);
+var version_1 = require("./version");
+Object.defineProperty(exports, "packageInfo", { enumerable: true, get: function () { return version_1.packageInfo; } });
+Object.defineProperty(exports, "PROTOCOL_VERSION", { enumerable: true, get: function () { return version_1.PROTOCOL_VERSION; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/protocol.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Wire protocol for the Helix local connector.
+ *
+ * This is the ONE place the on-the-wire contract lives, and it is deliberately
+ * conservative because the server (agents-api) and this client version
+ * independently: a user's installed package may be older OR newer than the
+ * agents-api it dials into. Two rules keep that safe and are why nothing here
+ * should be made "clever":
+ *
+ *   1. Inbound frames are `{ type, payload, timestamp }` (see agents-api
+ *      sendToConnector). We switch on `type` and hand `payload` to a handler.
+ *      An UNKNOWN inbound `type` is ignored, never fatal — so the server can add
+ *      new frames later without breaking older connectors.
+ *
+ *   2. Outbound chat frames are FLAT (`{ type, sessionId, ... }`), byte-identical
+ *      to what a Helix node emits (helix-os chat.ts), because agents-api routes
+ *      them home by `sessionId` through the SAME handler nodes use. Do not wrap
+ *      them in an envelope.
+ *
+ * PROTOCOL_VERSION is an integer bumped ONLY on a breaking wire change. Additive,
+ * optional-field, or new-frame changes must NOT bump it — announce those via
+ * `capabilities` on the hello frame instead, so old and new peers interoperate.
+ */
+/** Bump ONLY on a breaking wire change. Additive changes ride `capabilities`. */
+export declare const PROTOCOL_VERSION = 1;
+/** Inbound envelope as sent by agents-api (`sendToConnector`). */
+export interface ServerFrame {
+    type: string;
+    payload?: Record<string, unknown>;
+    timestamp?: string;
+}
+/** Payload of a `chat_message` frame (the fields this client reads; more may ride). */
+export interface ChatMessagePayload {
+    sessionId?: string;
+    message?: string;
+    agentId?: string;
+    model?: string;
+    providerRef?: string;
+    user?: {
+        id?: string;
+        email?: string;
+        name?: string;
+    };
+    org?: string;
+    agentName?: string;
+    designatedContact?: string;
+    scopeDirective?: string;
+}
+/** The connector's self-report, sent once on connect. Consumed by agents-api to
+ *  populate `PersonalAgent.installMeta` so Helix can flag an out-of-date client.
+ *  Every field is additive: unknown fields are ignored by an older server. */
+export interface HelloFrame {
+    type: 'connector_hello';
+    /** Wire protocol this client speaks. */
+    protocol: number;
+    /** The published package: name + semver. This is what Helix compares to "latest
+     *  known" to decide whether to nudge the user to update. */
+    client: {
+        name: string;
+        version: string;
+    };
+    /** The agent adapter backing this connector (echo, an OpenClaw bridge, …). */
+    adapter: {
+        name: string;
+        version: string;
+    };
+    /** Feature flags — the forward-compatible extension seam. New abilities are
+     *  announced here (e.g. 'chat', later 'mcp') instead of bumping `protocol`. */
+    capabilities: string[];
+    /** Best-effort host identity for operator diagnostics. */
+    host: {
+        platform: string;
+        arch: string;
+        node: string;
+    };
+}
+/** Parse a raw socket message into a ServerFrame, or null if it isn't one we can
+ *  use. Never throws — malformed input is dropped, not fatal. */
+export declare function parseServerFrame(data: unknown): ServerFrame | null;
+export declare const chatStarted: (sessionId: string) => Record<string, unknown>;
+export declare const chatDelta: (sessionId: string, text: string) => Record<string, unknown>;
+export declare const chatTool: (sessionId: string, name: string, phase: "call" | "result", ok?: boolean) => Record<string, unknown>;
+export declare const chatStatus: (sessionId: string, text: string) => Record<string, unknown>;
+export declare const chatDone: (sessionId: string, done?: {
+    usage?: unknown;
+    costUsd?: number | null;
+    providerRef?: string;
+    model?: string;
+    durationMs?: number;
+}) => Record<string, unknown>;
+export declare const chatError: (sessionId: string, message: string) => Record<string, unknown>;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,uFAAuF;AACvF,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;8EAE8E;AAC9E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,iBAAiB,CAAC;IACxB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB;gEAC4D;IAC5D,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,8EAA8E;IAC9E,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C;mFAC+E;IAC/E,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,0DAA0D;IAC1D,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD;AAED;iEACiE;AACjE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAoBlE;AAID,eAAO,MAAM,WAAW,GAAI,WAAW,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAGpE,CAAC;AAEH,eAAO,MAAM,SAAS,GAAI,WAAW,MAAM,EAAE,MAAM,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAIhF,CAAC;AAEH,eAAO,MAAM,QAAQ,GACnB,WAAW,MAAM,EACjB,MAAM,MAAM,EACZ,OAAO,MAAM,GAAG,QAAQ,EACxB,KAAK,OAAO,KACX,MAAM,CAAC,MAAM,EAAE,OAAO,CAMvB,CAAC;AAEH,eAAO,MAAM,UAAU,GAAI,WAAW,MAAM,EAAE,MAAM,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAIjF,CAAC;AAEH,eAAO,MAAM,QAAQ,GACnB,WAAW,MAAM,EACjB,OAAM;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,KACjH,MAAM,CAAC,MAAM,EAAE,OAAO,CAQvB,CAAC;AAEH,eAAO,MAAM,SAAS,GAAI,WAAW,MAAM,EAAE,SAAS,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAInF,CAAC"}

package/dist/protocol.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Wire protocol for the Helix local connector.
+ *
+ * This is the ONE place the on-the-wire contract lives, and it is deliberately
+ * conservative because the server (agents-api) and this client version
+ * independently: a user's installed package may be older OR newer than the
+ * agents-api it dials into. Two rules keep that safe and are why nothing here
+ * should be made "clever":
+ *
+ *   1. Inbound frames are `{ type, payload, timestamp }` (see agents-api
+ *      sendToConnector). We switch on `type` and hand `payload` to a handler.
+ *      An UNKNOWN inbound `type` is ignored, never fatal — so the server can add
+ *      new frames later without breaking older connectors.
+ *
+ *   2. Outbound chat frames are FLAT (`{ type, sessionId, ... }`), byte-identical
+ *      to what a Helix node emits (helix-os chat.ts), because agents-api routes
+ *      them home by `sessionId` through the SAME handler nodes use. Do not wrap
+ *      them in an envelope.
+ *
+ * PROTOCOL_VERSION is an integer bumped ONLY on a breaking wire change. Additive,
+ * optional-field, or new-frame changes must NOT bump it — announce those via
+ * `capabilities` on the hello frame instead, so old and new peers interoperate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chatError = exports.chatDone = exports.chatStatus = exports.chatTool = exports.chatDelta = exports.chatStarted = exports.PROTOCOL_VERSION = void 0;
+exports.parseServerFrame = parseServerFrame;
+/** Bump ONLY on a breaking wire change. Additive changes ride `capabilities`. */
+exports.PROTOCOL_VERSION = 1;
+/** Parse a raw socket message into a ServerFrame, or null if it isn't one we can
+ *  use. Never throws — malformed input is dropped, not fatal. */
+function parseServerFrame(data) {
+    let obj = data;
+    if (typeof data === 'string') {
+        try {
+            obj = JSON.parse(data);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!obj || typeof obj !== 'object')
+        return null;
+    const type = obj.type;
+    if (typeof type !== 'string')
+        return null;
+    const payload = obj.payload;
+    return {
+        type,
+        payload: payload && typeof payload === 'object' ? payload : undefined,
+        timestamp: typeof obj.timestamp === 'string'
+            ? obj.timestamp
+            : undefined,
+    };
+}
+// --- Outbound flat chat frames (mirror helix-os chat.ts exactly) ------------
+const chatStarted = (sessionId) => ({
+    type: 'chat_started',
+    sessionId,
+});
+exports.chatStarted = chatStarted;
+const chatDelta = (sessionId, text) => ({
+    type: 'chat_delta',
+    sessionId,
+    text,
+});
+exports.chatDelta = chatDelta;
+const chatTool = (sessionId, name, phase, ok) => ({
+    type: 'chat_tool',
+    sessionId,
+    name,
+    phase,
+    ...(ok === undefined ? {} : { ok }),
+});
+exports.chatTool = chatTool;
+const chatStatus = (sessionId, text) => ({
+    type: 'chat_status',
+    sessionId,
+    text,
+});
+exports.chatStatus = chatStatus;
+const chatDone = (sessionId, done = {}) => ({
+    type: 'chat_done',
+    sessionId,
+    usage: done.usage ?? null,
+    costUsd: done.costUsd ?? null,
+    ...(done.providerRef === undefined ? {} : { providerRef: done.providerRef }),
+    ...(done.model === undefined ? {} : { model: done.model }),
+    ...(done.durationMs === undefined ? {} : { durationMs: done.durationMs }),
+});
+exports.chatDone = chatDone;
+const chatError = (sessionId, message) => ({
+    type: 'chat_error',
+    sessionId,
+    message,
+});
+exports.chatError = chatError;
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AA+CH,4CAoBC;AAjED,iFAAiF;AACpE,QAAA,gBAAgB,GAAG,CAAC,CAAC;AA0ClC;iEACiE;AACjE,SAAgB,gBAAgB,CAAC,IAAa;IAC5C,IAAI,GAAG,GAAY,IAAI,CAAC;IACxB,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,IAAI,GAAI,GAA+B,CAAC,IAAI,CAAC;IACnD,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,OAAO,GAAI,GAA+B,CAAC,OAAO,CAAC;IACzD,OAAO;QACL,IAAI;QACJ,OAAO,EAAE,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAE,OAAmC,CAAC,CAAC,CAAC,SAAS;QAClG,SAAS,EAAE,OAAQ,GAA+B,CAAC,SAAS,KAAK,QAAQ;YACvE,CAAC,CAAG,GAA+B,CAAC,SAAoB;YACxD,CAAC,CAAC,SAAS;KACd,CAAC;AACJ,CAAC;AAED,+EAA+E;AAExE,MAAM,WAAW,GAAG,CAAC,SAAiB,EAA2B,EAAE,CAAC,CAAC;IAC1E,IAAI,EAAE,cAAc;IACpB,SAAS;CACV,CAAC,CAAC;AAHU,QAAA,WAAW,eAGrB;AAEI,MAAM,SAAS,GAAG,CAAC,SAAiB,EAAE,IAAY,EAA2B,EAAE,CAAC,CAAC;IACtF,IAAI,EAAE,YAAY;IAClB,SAAS;IACT,IAAI;CACL,CAAC,CAAC;AAJU,QAAA,SAAS,aAInB;AAEI,MAAM,QAAQ,GAAG,CACtB,SAAiB,EACjB,IAAY,EACZ,KAAwB,EACxB,EAAY,EACa,EAAE,CAAC,CAAC;IAC7B,IAAI,EAAE,WAAW;IACjB,SAAS;IACT,IAAI;IACJ,KAAK;IACL,GAAG,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC;CACpC,CAAC,CAAC;AAXU,QAAA,QAAQ,YAWlB;AAEI,MAAM,UAAU,GAAG,CAAC,SAAiB,EAAE,IAAY,EAA2B,EAAE,CAAC,CAAC;IACvF,IAAI,EAAE,aAAa;IACnB,SAAS;IACT,IAAI;CACL,CAAC,CAAC;AAJU,QAAA,UAAU,cAIpB;AAEI,MAAM,QAAQ,GAAG,CACtB,SAAiB,EACjB,OAAgH,EAAE,EACzF,EAAE,CAAC,CAAC;IAC7B,IAAI,EAAE,WAAW;IACjB,SAAS;IACT,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI;IACzB,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,IAAI;IAC7B,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;IAC5E,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IAC1D,GAAG,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC;CAC1E,CAAC,CAAC;AAXU,QAAA,QAAQ,YAWlB;AAEI,MAAM,SAAS,GAAG,CAAC,SAAiB,EAAE,OAAe,EAA2B,EAAE,CAAC,CAAC;IACzF,IAAI,EAAE,YAAY;IAClB,SAAS;IACT,OAAO;CACR,CAAC,CAAC;AAJU,QAAA,SAAS,aAInB"}

package/dist/version.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolve this package's own name + version at runtime (for the hello frame and
+ * `--version`). Read from package.json rather than hardcoded so a published build
+ * always reports the version it was actually cut at.
+ */
+export { PROTOCOL_VERSION } from './protocol';
+export declare function packageInfo(): {
+    name: string;
+    version: string;
+};
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAI9C,wBAAgB,WAAW,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAqB/D"}

package/dist/version.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Resolve this package's own name + version at runtime (for the hello frame and
+ * `--version`). Read from package.json rather than hardcoded so a published build
+ * always reports the version it was actually cut at.
+ */
+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.PROTOCOL_VERSION = void 0;
+exports.packageInfo = packageInfo;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+var protocol_1 = require("./protocol");
+Object.defineProperty(exports, "PROTOCOL_VERSION", { enumerable: true, get: function () { return protocol_1.PROTOCOL_VERSION; } });
+let cached = null;
+function packageInfo() {
+    if (cached)
+        return cached;
+    // Compiled to dist/version.js, so package.json is one level up; guard a couple
+    // of layouts (ts-node dev, nested installs) before falling back.
+    const candidates = [
+        path.join(__dirname, '..', 'package.json'),
+        path.join(__dirname, '..', '..', 'package.json'),
+    ];
+    for (const p of candidates) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(p, 'utf-8'));
+            if (pkg && typeof pkg.name === 'string') {
+                cached = { name: pkg.name, version: typeof pkg.version === 'string' ? pkg.version : '0.0.0' };
+                return cached;
+            }
+        }
+        catch {
+            /* try next candidate */
+        }
+    }
+    cached = { name: '@spark-strategic/helix-core', version: '0.0.0' };
+    return cached;
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AASH,kCAqBC;AA5BD,uCAAyB;AACzB,2CAA6B;AAE7B,uCAA8C;AAArC,4GAAA,gBAAgB,OAAA;AAEzB,IAAI,MAAM,GAA6C,IAAI,CAAC;AAE5D,SAAgB,WAAW;IACzB,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,iEAAiE;IACjE,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,cAAc,CAAC;QAC1C,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;KACjD,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;YACpD,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACxC,MAAM,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;gBAC9F,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,wBAAwB;QAC1B,CAAC;IACH,CAAC;IACD,MAAM,GAAG,EAAE,IAAI,EAAE,6BAA6B,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IACnE,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@spark-strategic/helix-core",
+  "version": "0.1.0",
+  "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",
+  "bin": {
+    "helix-core": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/cli.ts",
+    "start": "node dist/cli.js",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "helix",
+    "agent",
+    "connector",
+    "personal-agent"
+  ],
+  "author": "Spark Strategic",
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/ws": "^8.18.1",
+    "rimraf": "^5.0.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Spark-Strategic/helix.spark-strategic.ai.git",
+    "directory": "helix-core"
+  }
+}