@cotal-ai/connector-core 0.8.1 → 0.8.2

package/dist/control.d.ts

@@ -17,8 +17,27 @@ export interface HookEvent {
 }
 /** Maps one hook event to the JSON reply the runtime applies. */
 export type HookHandle = (agent: MeshAgent, ev: HookEvent) => Promise<Record<string, unknown>>;
+export interface ControlServerOpts {
+    /** Fail loud on a bind we can't hold. A managed listener (the in-agent MCP server, the Hermes
+     *  sidecar) MUST own its endpoint: if `listen` errors (e.g. a squatter already holds the win32
+     *  pipe → `EADDRINUSE`; libuv binds with `FILE_FLAG_FIRST_PIPE_INSTANCE`), the process exits
+     *  rather than running on with a hijacked or no-op control plane. Default off (an ad-hoc/test
+     *  server logs and stays up). */
+    fatalBind?: boolean;
+    /** Cooperative shutdown: invoked on an AUTHENTICATED `{op:"shutdown"}` frame. The connector runs
+     *  its own clean teardown (close the server, `agent.stop()` to leave the mesh, then exit) — the
+     *  server never owns `process.exit`. Absent → shutdown frames are accepted + acked but inert. */
+    onShutdown?: () => void;
+}
 /** The context block injected into a turn when peer messages are waiting (else undefined). */
 export declare function formatInjection(items: InboxItem[]): string | undefined;
-/** Start the control socket. One newline-delimited JSON request → one reply per connection. */
-export declare function startControlServer(agent: MeshAgent, socketPath: string, handle: HookHandle): Server;
+/** Start the authenticated control server. One newline-delimited JSON {@link ControlFrame} → one
+ *  reply per connection. The first thing every connection does is validate its `token` against the
+ *  endpoint's (constant-time) — a mismatch is dropped before `handle` (or `onShutdown`) ever runs,
+ *  so an unauthenticated local process that finds/guesses the path still can't drive presence,
+ *  inject peer messages, or shut the agent down. */
+export declare function startControlServer(agent: MeshAgent, endpoint: {
+    path: string;
+    token: string;
+}, handle: HookHandle, opts?: ControlServerOpts): Server;
 //# sourceMappingURL=control.d.ts.map

package/dist/control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../src/control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAErD,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvD,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,iEAAiE;AACjE,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAa/F,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,GAAG,SAAS,CAKtE;AAED,+FAA+F;AAC/F,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAChB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,UAAU,GACjB,MAAM,CAuCR"}
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../src/control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAGrD,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvD,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,iEAAiE;AACjE,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAU/F,MAAM,WAAW,iBAAiB;IAChC;;;;qCAIiC;IACjC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;qGAEiG;IACjG,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AA+BD,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,GAAG,SAAS,CAKtE;AAED;;;;oDAIoD;AACpD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EACzC,MAAM,EAAE,UAAU,EAClB,IAAI,GAAE,iBAAsB,GAC3B,MAAM,CAkFR"}

package/dist/control.js

@@ -10,6 +10,24 @@
  */
 import { createServer } from "node:net";
 import { existsSync, unlinkSync } from "node:fs";
+import { createHash, timingSafeEqual } from "node:crypto";
+/** Hard cap on the first (only) frame: a control request is a token + one small lifecycle event —
+ *  kilobytes at most. Generous headroom for a legit event, tiny next to the ~512MB string limit an
+ *  unauthenticated spewer would otherwise drive `buf` toward to crash the process. */
+const MAX_FRAME_BYTES = 1 << 20; // 1 MiB
+/** ABSOLUTE deadline (not an idle timeout — a slow-loris dribbling one byte at a time would keep
+ *  resetting an idle timer) for a connection to deliver its complete auth frame. Past it, an
+ *  unauthenticated connection is dropped so a local process can't camp on a finite pipe instance.
+ *  Cleared the instant a full frame is in hand (the token-bearing client then owns the connection). */
+const AUTH_DEADLINE_MS = 5_000;
+/** Constant-time match of a presented token against the endpoint's. Both sides are SHA-256'd first
+ *  so the compare is fixed-length (and length-independent) regardless of the presented value — a
+ *  non-string or wrong-length token can never throw `timingSafeEqual` or leak length via timing. */
+function tokenMatches(presented, digest) {
+    if (typeof presented !== "string")
+        return false;
+    return timingSafeEqual(createHash("sha256").update(presented).digest(), digest);
+}
 function who(i) {
     return i.fromRole ? `${i.fromName}/${i.fromRole}` : i.fromName;
 }
@@ -29,11 +47,21 @@ export function formatInjection(items) {
     const tail = `(Reply with cotal_send / cotal_dm, or cotal_roster to see who's here.)`;
     return `${head}\n${items.map(fmtItem).join("\n")}\n${tail}`;
 }
-/** Start the control socket. One newline-delimited JSON request → one reply per connection. */
-export function startControlServer(agent, socketPath, handle) {
-    if (existsSync(socketPath)) {
+/** Start the authenticated control server. One newline-delimited JSON {@link ControlFrame} → one
+ *  reply per connection. The first thing every connection does is validate its `token` against the
+ *  endpoint's (constant-time) — a mismatch is dropped before `handle` (or `onShutdown`) ever runs,
+ *  so an unauthenticated local process that finds/guesses the path still can't drive presence,
+ *  inject peer messages, or shut the agent down. */
+export function startControlServer(agent, endpoint, handle, opts = {}) {
+    const { path } = endpoint;
+    const digest = createHash("sha256").update(endpoint.token).digest();
+    // Stale-socket cleanup is POSIX-only: a win32 named pipe is not a filesystem entry to unlink, and
+    // a live one there is a SQUATTER the fatal `EADDRINUSE` is meant to catch — never clear it. (With
+    // a token-random path a stale POSIX socket from a dead predecessor is itself near-impossible, but
+    // the unlink stays as cheap insurance against an exact-path leftover.)
+    if (process.platform !== "win32" && existsSync(path)) {
         try {
-            unlinkSync(socketPath); // clear a stale socket from a dead predecessor
+            unlinkSync(path);
         }
         catch {
             /* ignore */
@@ -41,19 +69,52 @@ export function startControlServer(agent, socketPath, handle) {
     }
     const server = createServer((sock) => {
         let buf = "";
+        let handled = false; // one frame per connection — ignore anything after the first line
         sock.setEncoding("utf8");
+        // Bound an UNAUTHENTICATED peer: on Windows the named pipe's default DACL lets any local process
+        // connect, so a client that streams bytes with no newline (would grow `buf` toward the ~512MB
+        // string limit → crashes this long-lived process), that connects and sends nothing, OR that
+        // dribbles a byte at a time (a slow-loris) to camp on a finite pipe instance must be cut off
+        // BEFORE auth. MAX_FRAME_BYTES caps a spewing one; an ABSOLUTE deadline (reset-proof, unlike an
+        // idle timeout) reaps a silent/slow one. A legit client sends one small line immediately.
+        const deadline = setTimeout(() => sock.destroy(), AUTH_DEADLINE_MS);
+        deadline.unref?.(); // never hold the process open on an unauthenticated connection
+        sock.on("close", () => clearTimeout(deadline));
         sock.on("data", async (d) => {
+            if (handled)
+                return;
             buf += d;
+            if (buf.length > MAX_FRAME_BYTES) {
+                sock.destroy(); // oversized pre-newline — drop hard, never half-close (it keeps spewing)
+                return;
+            }
             const nl = buf.indexOf("\n");
             if (nl < 0)
                 return; // wait for the full line
-            let ev = {};
+            handled = true;
+            clearTimeout(deadline); // full frame in hand — the token-bearing client now owns the connection
+            let frame = {};
             try {
-                ev = JSON.parse(buf.slice(0, nl) || "{}");
+                frame = JSON.parse(buf.slice(0, nl) || "{}");
             }
             catch {
-                /* malformed — treat as empty */
+                /* malformed — fails the auth check below and is dropped */
+            }
+            if (!tokenMatches(frame.token, digest)) {
+                sock.destroy(); // unauthenticated — drop hard before handle/onShutdown (no half-open)
+                return;
             }
+            if (frame.op === "shutdown") {
+                try {
+                    sock.end(JSON.stringify({ ok: true }) + "\n");
+                }
+                catch {
+                    /* client gone */
+                }
+                opts.onShutdown?.();
+                return;
+            }
+            const ev = (frame.event ?? {});
             const reply = await handle(agent, ev);
             try {
                 sock.end(JSON.stringify(reply) + "\n");
@@ -66,8 +127,19 @@ export function startControlServer(agent, socketPath, handle) {
             /* ignore client errors */
         });
     });
-    server.on("error", (e) => process.stderr.write(`[cotal-connector] control server error: ${e.message}\n`));
-    server.listen(socketPath, () => process.stderr.write(`[cotal-connector] control socket: ${socketPath}\n`));
+    let bound = false;
+    server.on("error", (e) => {
+        process.stderr.write(`[cotal-connector] control server error: ${e.message}\n`);
+        // A bind we never held (listen errored before "listening", e.g. EADDRINUSE from a squatter) is
+        // fatal for a managed listener — better to die than serve a hijacked/no-op control plane. A
+        // post-bind error is just logged.
+        if (opts.fatalBind && !bound)
+            process.exit(1);
+    });
+    server.listen(path, () => {
+        bound = true;
+        process.stderr.write(`[cotal-connector] control socket: ${path}\n`); // path is leakage-safe; the token never logs
+    });
     return server;
 }
 //# sourceMappingURL=control.js.map

package/dist/control.js.map

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

package/dist/launch.d.ts

@@ -23,9 +23,15 @@ import type { McpServerSpec } from "@cotal-ai/core";
 export declare const MODEL_PROVIDER_KEYS: readonly ["OPENCODE_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENROUTER_API_KEY", "NOUS_API_KEY"];
 /** Build the base env a spawned agent runs with: the OS allow-list plus any named keys the
  *  connector declares the agent needs — `providerKeys` (the model-provider key) and `mcpKeys`
- *  (the `${VAR}` secrets a shared MCP server references, see {@link mcpServerEnvKeys}). Every
- *  entry is copied from the manager's env BY NAME and only when present — never required, never
- *  spread wholesale, so the operator's unrelated secrets don't bleed into the child (P3). */
+ *  (the `${VAR}` secrets a shared MCP server references, see {@link mcpServerEnvKeys}). Every entry
+ *  is copied from the manager's env BY NAME and only when present — never required, never spread
+ *  wholesale, so the operator's unrelated secrets don't bleed into the child (P3).
+ *
+ *  Matching is CASE-INSENSITIVE and each value is copied under the OS's OWN key casing: Windows
+ *  spells these `Path`/`ComSpec`/`windir`, so a canonical-only copy would either miss them (a plain
+ *  read of `process.env.SystemRoot` differs from `process.env.systemroot`) or, worse, emit BOTH
+ *  `Path` and `PATH` — a case-duplicate Windows process creation chokes on. Keying off the source
+ *  env's actual casing (one entry per lowercased name) forwards each var exactly once. */
 export declare function launchEnv(opts?: {
     providerKeys?: readonly string[];
     mcpKeys?: readonly string[];

package/dist/launch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../src/launch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAsCpD;;;;+EAI+E;AAC/E,eAAO,MAAM,mBAAmB,4GAMtB,CAAC;AAEX;;;;6FAI6F;AAC7F,wBAAgB,SAAS,CACvB,IAAI,GAAE;IAAE,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GAC3E,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB;AAED;;;;;mFAKmF;AACnF,wBAAgB,MAAM,CAAC,IAAI,EAAE;IAC3B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMzB;AAED;;;;kEAIkE;AAClE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,MAAM,EAAE,CAcjF"}
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../src/launch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AA0DpD;;;;+EAI+E;AAC/E,eAAO,MAAM,mBAAmB,4GAMtB,CAAC;AAEX;;;;;;;;;;0FAU0F;AAC1F,wBAAgB,SAAS,CACvB,IAAI,GAAE;IAAE,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GAC3E,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAexB;AAED;;;;;mFAKmF;AACnF,wBAAgB,MAAM,CAAC,IAAI,EAAE;IAC3B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMzB;AAED;;;;kEAIkE;AAClE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,MAAM,EAAE,CAcjF"}

package/dist/launch.js

@@ -2,7 +2,11 @@
  *  COLORTERM), resolve home/config/data roots (HOME / XDG_*_HOME on Unix,
  *  USERPROFILE / APPDATA / LOCALAPPDATA on Windows), locale (LANG / LC_*), timezone (TZ), temp
  *  dirs, session/runtime dir (XDG_RUNTIME_DIR), and the shell it may invoke. NOT a model key,
- *  NOT an operator secret. A fixed, named allow-list. */
+ *  NOT an operator secret. A fixed, named allow-list; each entry is forwarded only when present,
+ *  so the Unix-only and Windows-only names below coexist harmlessly on either OS. Names are matched
+ *  case-insensitively against the source env and copied under the source's own key (see
+ *  {@link launchEnv}), so Windows casing (`Path`, `ComSpec`, `windir`) is forwarded without ever
+ *  emitting a case-duplicate (`Path` AND `PATH`) that Windows process creation would choke on. */
 const OS_ENV_ALLOW = [
     "PATH",
     "HOME",
@@ -32,6 +36,22 @@ const OS_ENV_ALLOW = [
     "APPDATA",
     "LOCALAPPDATA",
     "XDG_RUNTIME_DIR",
+    // Windows system env. SystemRoot is mandatory: without it a spawned process aborts at startup
+    // (node `InitializeOnce`, winsock/ICU can't load) — and a `pty`-runtime (ConPTY) child does NOT
+    // inherit it the way a plain child_process does, so a manager-spawned agent dies before its first
+    // line. The rest let agents resolve the system drive, arch, and Program/Data roots they shell out
+    // to. Absent on POSIX (skipped); present only on Windows.
+    "SystemRoot",
+    "windir",
+    "SystemDrive",
+    "PROCESSOR_ARCHITECTURE",
+    "NUMBER_OF_PROCESSORS",
+    "ALLUSERSPROFILE",
+    "ProgramData",
+    "ProgramFiles",
+    "ProgramFiles(x86)",
+    "CommonProgramFiles",
+    "PUBLIC",
 ];
 /** Model-provider API keys a key-based connector may forward to its child. claude needs none
  *  (macOS Keychain / OAuth token, not an env key) → strong isolation for free; opencode/hermes
@@ -47,21 +67,34 @@ export const MODEL_PROVIDER_KEYS = [
 ];
 /** Build the base env a spawned agent runs with: the OS allow-list plus any named keys the
  *  connector declares the agent needs — `providerKeys` (the model-provider key) and `mcpKeys`
- *  (the `${VAR}` secrets a shared MCP server references, see {@link mcpServerEnvKeys}). Every
- *  entry is copied from the manager's env BY NAME and only when present — never required, never
- *  spread wholesale, so the operator's unrelated secrets don't bleed into the child (P3). */
+ *  (the `${VAR}` secrets a shared MCP server references, see {@link mcpServerEnvKeys}). Every entry
+ *  is copied from the manager's env BY NAME and only when present — never required, never spread
+ *  wholesale, so the operator's unrelated secrets don't bleed into the child (P3).
+ *
+ *  Matching is CASE-INSENSITIVE and each value is copied under the OS's OWN key casing: Windows
+ *  spells these `Path`/`ComSpec`/`windir`, so a canonical-only copy would either miss them (a plain
+ *  read of `process.env.SystemRoot` differs from `process.env.systemroot`) or, worse, emit BOTH
+ *  `Path` and `PATH` — a case-duplicate Windows process creation chokes on. Keying off the source
+ *  env's actual casing (one entry per lowercased name) forwards each var exactly once. */
 export function launchEnv(opts = {}) {
     const env = {};
-    for (const k of OS_ENV_ALLOW) {
-        const v = process.env[k];
-        if (v !== undefined)
-            env[k] = v;
-    }
-    for (const k of [...(opts.providerKeys ?? []), ...(opts.mcpKeys ?? [])]) {
-        const v = process.env[k];
+    // lowercased name -> the OS's actual key casing; one entry per var (the OS env has no case-dup),
+    // so every allow-list name resolves to a single source key and the result carries no case-dup.
+    const sourceKey = new Map();
+    for (const k of Object.keys(process.env))
+        sourceKey.set(k.toLowerCase(), k);
+    const copy = (name) => {
+        const src = sourceKey.get(name.toLowerCase());
+        if (src === undefined)
+            return;
+        const v = process.env[src];
         if (v !== undefined)
-            env[k] = v;
-    }
+            env[src] = v;
+    };
+    for (const k of OS_ENV_ALLOW)
+        copy(k);
+    for (const k of [...(opts.providerKeys ?? []), ...(opts.mcpKeys ?? [])])
+        copy(k);
     return env;
 }
 /** The agent's resolved access policy as `COTAL_*` env, when present. Forwarded by each connector

package/dist/launch.js.map

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

package/dist/relay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../src/relay.ts"],"names":[],"mappings":"AAmCA,6FAA6F;AAC7F,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAsClD"}
+{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../src/relay.ts"],"names":[],"mappings":"AAkCA,6FAA6F;AAC7F,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAiDlD"}

package/dist/relay.js

@@ -8,8 +8,7 @@
  * entry points are one-liners over {@link runHookRelay}.
  */
 import { connect } from "node:net";
-import { configFromEnv, hasIdentity } from "./config.js";
-import { controlSocketPath } from "./runtime.js";
+import { hasIdentity } from "./config.js";
 const TIMEOUT_MS = 2000;
 function readStdin() {
     return new Promise((resolve) => {
@@ -35,9 +34,22 @@ function done(out) {
 export async function runHookRelay() {
     if (!hasIdentity())
         return done(""); // plain session, not a managed one — no-op
+    // Path + token come from the launch env (shared with the in-agent server, which we inherited from);
+    // never recomputed from public identity. Absent → not an authenticated control session: no-op (fail
+    // open, so a hook never blocks the user's session).
+    const path = process.env.COTAL_CONTROL_SOCKET;
+    const token = process.env.COTAL_CONTROL_TOKEN;
+    if (!path || !token)
+        return done("");
     const raw = (await readStdin()).trim() || "{}";
-    const cfg = configFromEnv();
-    const sock = connect(controlSocketPath(cfg.space, cfg.name));
+    let event = {};
+    try {
+        event = JSON.parse(raw); // the hook event the runtime piped in
+    }
+    catch {
+        /* malformed — relay an empty event under a valid token */
+    }
+    const sock = connect(path);
     let reply = "";
     let settled = false;
     const finish = (out) => {
@@ -54,7 +66,7 @@ export async function runHookRelay() {
     };
     const timer = setTimeout(() => finish(""), TIMEOUT_MS);
     sock.setEncoding("utf8");
-    sock.on("connect", () => sock.write(raw + "\n"));
+    sock.on("connect", () => sock.write(JSON.stringify({ token, event }) + "\n"));
     sock.on("data", (d) => {
         reply += d;
         const nl = reply.indexOf("\n");

package/dist/relay.js.map

@@ -1 +1 @@
-{"version":3,"file":"relay.js","sourceRoot":"","sources":["../src/relay.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"relay.js","sourceRoot":"","sources":["../src/relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,UAAU,GAAG,IAAI,CAAC;AAExB,SAAS,SAAS;IAChB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK;YAAE,OAAO,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5C,IAAI,CAAC,GAAG,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAClC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC1C,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1C,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,IAAI,CAAC,GAAW;IACvB,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACrB,IAAI,CAAC,CAAC;QAAE,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,uCAAuC;IACvE,wFAAwF;IACxF,iGAAiG;IACjG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAC1C,CAAC;AAED,6FAA6F;AAC7F,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,IAAI,CAAC,WAAW,EAAE;QAAE,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,2CAA2C;IAChF,oGAAoG;IACpG,oGAAoG;IACpG,oDAAoD;IACpD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;IAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IAC9C,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC;IACrC,MAAM,GAAG,GAAG,CAAC,MAAM,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC;IAC/C,IAAI,KAAK,GAAY,EAAE,CAAC;IACxB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,sCAAsC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,0DAA0D;IAC5D,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3B,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,MAAM,GAAG,CAAC,GAAW,EAAQ,EAAE;QACnC,IAAI,OAAO;YAAE,OAAO;QACpB,OAAO,GAAG,IAAI,CAAC;QACf,IAAI,CAAC;YACH,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;QAAC,MAAM,CAAC;YACP,YAAY;QACd,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,CAAC,CAAC;IACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;IAEvD,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACzB,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAC9E,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE;QACpB,KAAK,IAAI,CAAC,CAAC;QACX,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;YACZ,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACpB,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,gCAAgC;IAC9C,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;QAClB,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,MAAM,CAAC,KAAK,CAAC,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/runtime.d.ts

@@ -1,7 +1,24 @@
 /**
- * Deterministic path to a connector's local control socket. Both the long-lived
- * MCP server (which listens) and its short-lived hooks (which connect) compute
- * this from the SAME identity, so they always agree without a discovery step.
+ * A connector's local control endpoint: the OS path its lifecycle hooks (and the manager's
+ * cooperative-shutdown call) connect to, plus the shared secret that authenticates the first frame.
+ *
+ * The path id is `sha256(space\0name\0pid\0token)` (base64url, ≤32) — unguessable and
+ * collision-free without leaking identity; the 256-bit `token` is the actual auth boundary (the
+ * server validates it with a constant-time compare before doing anything — see `control.ts`).
+ *
+ * Transport is per-platform but the same `node:net` path string drives both: win32 has no
+ * filesystem AF_UNIX socket Node can bind, so the path is a named pipe (`\\.\pipe\…`) whose default
+ * DACL lets ANY local process connect — which is exactly why the token, not the path, is the
+ * security boundary there. POSIX uses a per-user `tmpdir` socket.
+ *
+ * Minted ONCE at launch (in the manager's process, via the connector's `buildLaunch`). Both ends —
+ * the in-agent server that LISTENS and the short-lived hooks that CONNECT — then read `path`+`token`
+ * from the child env (`COTAL_CONTROL_SOCKET`/`COTAL_CONTROL_TOKEN`), never recompute them from
+ * public identity; the manager keeps them in memory for the cooperative shutdown. (`process.pid` is
+ * just generation-time entropy — the value flows by env, so it never has to match across processes.)
  */
-export declare function controlSocketPath(space: string, name: string): string;
+export declare function controlEndpoint(space: string, name: string, token?: string): {
+    path: string;
+    token: string;
+};
 //# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAErE"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAA8C,GACpD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAQjC"}

package/dist/runtime.js

@@ -1,16 +1,31 @@
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-const ILLEGAL = /[^A-Za-z0-9_-]/g;
-function tok(s) {
-    const t = s.trim().replace(ILLEGAL, "_");
-    return t.length ? t.slice(0, 40) : "_";
-}
+import { createHash, randomBytes } from "node:crypto";
 /**
- * Deterministic path to a connector's local control socket. Both the long-lived
- * MCP server (which listens) and its short-lived hooks (which connect) compute
- * this from the SAME identity, so they always agree without a discovery step.
+ * A connector's local control endpoint: the OS path its lifecycle hooks (and the manager's
+ * cooperative-shutdown call) connect to, plus the shared secret that authenticates the first frame.
+ *
+ * The path id is `sha256(space\0name\0pid\0token)` (base64url, ≤32) — unguessable and
+ * collision-free without leaking identity; the 256-bit `token` is the actual auth boundary (the
+ * server validates it with a constant-time compare before doing anything — see `control.ts`).
+ *
+ * Transport is per-platform but the same `node:net` path string drives both: win32 has no
+ * filesystem AF_UNIX socket Node can bind, so the path is a named pipe (`\\.\pipe\…`) whose default
+ * DACL lets ANY local process connect — which is exactly why the token, not the path, is the
+ * security boundary there. POSIX uses a per-user `tmpdir` socket.
+ *
+ * Minted ONCE at launch (in the manager's process, via the connector's `buildLaunch`). Both ends —
+ * the in-agent server that LISTENS and the short-lived hooks that CONNECT — then read `path`+`token`
+ * from the child env (`COTAL_CONTROL_SOCKET`/`COTAL_CONTROL_TOKEN`), never recompute them from
+ * public identity; the manager keeps them in memory for the cooperative shutdown. (`process.pid` is
+ * just generation-time entropy — the value flows by env, so it never has to match across processes.)
  */
-export function controlSocketPath(space, name) {
-    return join(tmpdir(), `cotal-${tok(space)}-${tok(name)}.sock`);
+export function controlEndpoint(space, name, token = randomBytes(32).toString("base64url")) {
+    const id = createHash("sha256")
+        .update(`${space}\0${name}\0${process.pid}\0${token}`)
+        .digest("base64url")
+        .slice(0, 32);
+    const path = process.platform === "win32" ? `\\\\.\\pipe\\cotal-${id}` : join(tmpdir(), `cotal-${id}.sock`);
+    return { path, token };
 }
 //# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,OAAO,GAAG,iBAAiB,CAAC;AAElC,SAAS,GAAG,CAAC,CAAS;IACpB,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACzC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,IAAY;IAC3D,OAAO,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACjE,CAAC"}
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEtD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAa,EACb,IAAY,EACZ,QAAgB,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;IAErD,MAAM,EAAE,GAAG,UAAU,CAAC,QAAQ,CAAC;SAC5B,MAAM,CAAC,GAAG,KAAK,KAAK,IAAI,KAAK,OAAO,CAAC,GAAG,KAAK,KAAK,EAAE,CAAC;SACrD,MAAM,CAAC,WAAW,CAAC;SACnB,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChB,MAAM,IAAI,GACR,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,sBAAsB,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACjG,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cotal-ai/connector-core",
   "description": "Shared MCP-bridge runtime for Cotal connectors: the mesh agent, cotal_* tools, and hook relay.",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
     "@cotal-ai/core": ">=0.1.0"
   },
   "devDependencies": {
-    "@cotal-ai/core": "0.8.1"
+    "@cotal-ai/core": "0.8.2"
   },
   "files": [
     "dist"