@agenticros/core 0.5.0

package/dist/transport-pool.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `TransportPool` — Phase 1.d shared multi-robot transport pool.
+ *
+ * Lives in `@agenticros/core` so every adapter (Claude Code, Gemini,
+ * future ones) can route per-robot transports through the same battle-
+ * tested implementation. OpenClaw's plugin uses a thinner add-on
+ * because its existing service has long-lived eager-connect / poll
+ * semantics that don't compose cleanly with a generic pool.
+ *
+ * Semantics:
+ *
+ *   - Pool key is `__global__` when the robot has no per-robot
+ *     `transport` override in config — every robot then shares one
+ *     connection (the legacy / single-transport behaviour). Opting
+ *     into `config.robots[]` is NOT a breaking change for that path.
+ *
+ *   - Pool key is `robot.id` when the robot DOES declare an override.
+ *     A distinct transport is materialised on first use and cached
+ *     for subsequent tool calls.
+ *
+ *   - Acquires are lazy — the constructor never opens a connection.
+ *     The first call to `acquire()` for a given key triggers the
+ *     create + connect dance, gated by `connectWithTimeout()`.
+ *
+ *   - Concurrent first-acquires on the same key share one in-flight
+ *     connect promise — important when an MCP server gets two
+ *     near-simultaneous tool calls right after startup.
+ *
+ *   - Cached entries that drop to a non-`connected` state are
+ *     rebuilt on the next acquire (self-heal — matches the pre-pool
+ *     `connect()` behaviour).
+ *
+ *   - `disconnectAll()` drains every entry and is safe to call on
+ *     SIGINT/SIGTERM. Errors on individual disconnects are swallowed
+ *     so one misbehaving transport can't block the others from
+ *     cleaning up.
+ *
+ * The default factory is `createTransport` from `./transport/factory`.
+ * Adapter shutdowns / tests can inject a fake factory by passing one
+ * to the constructor — see packages/core/src/__tests__/transport-pool.test.ts
+ * for the unit-test seam.
+ */
+import type { AgenticROSConfig, ResolvedRobot, RosTransport, TransportConfig } from "./index.js";
+export declare const TRANSPORT_POOL_GLOBAL_KEY = "__global__";
+export type TransportFactory = (cfg: TransportConfig) => Promise<RosTransport>;
+export declare class TransportPool {
+    private readonly factory;
+    private readonly entries;
+    /** Promises kept while a connection is in flight, so concurrent acquires share the same connect. */
+    private readonly inFlight;
+    constructor(factory?: TransportFactory);
+    /**
+     * Acquire (lazy-connect on first call) the transport for this robot.
+     * See the module docstring for the full key + caching contract.
+     */
+    acquire(config: AgenticROSConfig, robot: ResolvedRobot): Promise<RosTransport>;
+    /**
+     * Pre-warm the active robot's transport at server start — used by
+     * adapters that want to pay the connect-latency tax upfront instead
+     * of on the first tool call.
+     */
+    connectActive(config: AgenticROSConfig): Promise<void>;
+    /**
+     * Disconnect every transport in the pool. Safe to call multiple
+     * times. Errors on individual disconnects are swallowed.
+     */
+    disconnectAll(): Promise<void>;
+    /** Visible for tests: how many distinct transports are alive right now. */
+    get size(): number;
+    /** Visible for tests: list of pool keys currently cached. */
+    keys(): string[];
+    private acquireByKey;
+}
+//# sourceMappingURL=transport-pool.d.ts.map

package/dist/transport-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-pool.d.ts","sourceRoot":"","sources":["../src/transport-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,eAAe,EAChB,MAAM,YAAY,CAAC;AAUpB,eAAO,MAAM,yBAAyB,eAAe,CAAC;AAEtD,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAE/E,qBAAa,aAAa;IAKZ,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,oGAAoG;IACpG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4C;gBAExC,OAAO,GAAE,gBAAkC;IAExE;;;OAGG;IACG,OAAO,CAAC,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAWpF;;;;OAIG;IACG,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5D;;;OAGG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAcpC,2EAA2E;IAC3E,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,6DAA6D;IAC7D,IAAI,IAAI,MAAM,EAAE;YAIF,YAAY;CAgC3B"}

package/dist/transport-pool.js

@@ -0,0 +1,135 @@
+/**
+ * `TransportPool` — Phase 1.d shared multi-robot transport pool.
+ *
+ * Lives in `@agenticros/core` so every adapter (Claude Code, Gemini,
+ * future ones) can route per-robot transports through the same battle-
+ * tested implementation. OpenClaw's plugin uses a thinner add-on
+ * because its existing service has long-lived eager-connect / poll
+ * semantics that don't compose cleanly with a generic pool.
+ *
+ * Semantics:
+ *
+ *   - Pool key is `__global__` when the robot has no per-robot
+ *     `transport` override in config — every robot then shares one
+ *     connection (the legacy / single-transport behaviour). Opting
+ *     into `config.robots[]` is NOT a breaking change for that path.
+ *
+ *   - Pool key is `robot.id` when the robot DOES declare an override.
+ *     A distinct transport is materialised on first use and cached
+ *     for subsequent tool calls.
+ *
+ *   - Acquires are lazy — the constructor never opens a connection.
+ *     The first call to `acquire()` for a given key triggers the
+ *     create + connect dance, gated by `connectWithTimeout()`.
+ *
+ *   - Concurrent first-acquires on the same key share one in-flight
+ *     connect promise — important when an MCP server gets two
+ *     near-simultaneous tool calls right after startup.
+ *
+ *   - Cached entries that drop to a non-`connected` state are
+ *     rebuilt on the next acquire (self-heal — matches the pre-pool
+ *     `connect()` behaviour).
+ *
+ *   - `disconnectAll()` drains every entry and is safe to call on
+ *     SIGINT/SIGTERM. Errors on individual disconnects are swallowed
+ *     so one misbehaving transport can't block the others from
+ *     cleaning up.
+ *
+ * The default factory is `createTransport` from `./transport/factory`.
+ * Adapter shutdowns / tests can inject a fake factory by passing one
+ * to the constructor — see packages/core/src/__tests__/transport-pool.test.ts
+ * for the unit-test seam.
+ */
+import { createTransport, getTransportConfig, getTransportConfigForRobot, hasRobotTransportOverride, resolveRobot, } from "./index.js";
+const CONNECT_TIMEOUT_MS = 15_000;
+export const TRANSPORT_POOL_GLOBAL_KEY = "__global__";
+export class TransportPool {
+    factory;
+    entries = new Map();
+    /** Promises kept while a connection is in flight, so concurrent acquires share the same connect. */
+    inFlight = new Map();
+    constructor(factory = createTransport) {
+        this.factory = factory;
+    }
+    /**
+     * Acquire (lazy-connect on first call) the transport for this robot.
+     * See the module docstring for the full key + caching contract.
+     */
+    async acquire(config, robot) {
+        const key = hasRobotTransportOverride(config, robot.id)
+            ? robot.id
+            : TRANSPORT_POOL_GLOBAL_KEY;
+        return this.acquireByKey(key, () => key === TRANSPORT_POOL_GLOBAL_KEY
+            ? getTransportConfig(config)
+            : getTransportConfigForRobot(config, robot.id));
+    }
+    /**
+     * Pre-warm the active robot's transport at server start — used by
+     * adapters that want to pay the connect-latency tax upfront instead
+     * of on the first tool call.
+     */
+    async connectActive(config) {
+        const robot = resolveRobot(config);
+        await this.acquire(config, robot);
+    }
+    /**
+     * Disconnect every transport in the pool. Safe to call multiple
+     * times. Errors on individual disconnects are swallowed.
+     */
+    async disconnectAll() {
+        const pending = [];
+        for (const t of this.entries.values()) {
+            pending.push(t.disconnect().catch(() => {
+                /* best-effort drain */
+            }));
+        }
+        this.entries.clear();
+        this.inFlight.clear();
+        await Promise.all(pending);
+    }
+    /** Visible for tests: how many distinct transports are alive right now. */
+    get size() {
+        return this.entries.size;
+    }
+    /** Visible for tests: list of pool keys currently cached. */
+    keys() {
+        return Array.from(this.entries.keys());
+    }
+    async acquireByKey(key, resolveCfg) {
+        const cached = this.entries.get(key);
+        if (cached && cached.getStatus() === "connected")
+            return cached;
+        // A second concurrent acquire on the same key joins the in-flight
+        // connect rather than starting a duplicate.
+        const flight = this.inFlight.get(key);
+        if (flight)
+            return flight;
+        if (cached) {
+            // Stale entry (e.g. router restarted under us). Drop it cleanly.
+            this.entries.delete(key);
+            cached.disconnect().catch(() => { });
+        }
+        const connectFlight = (async () => {
+            const cfg = resolveCfg();
+            const t = await this.factory(cfg);
+            await connectWithTimeout(t);
+            this.entries.set(key, t);
+            return t;
+        })();
+        this.inFlight.set(key, connectFlight);
+        try {
+            return await connectFlight;
+        }
+        finally {
+            this.inFlight.delete(key);
+        }
+    }
+}
+async function connectWithTimeout(t) {
+    const timeout = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error(`Transport connection timed out after ${CONNECT_TIMEOUT_MS / 1000}s. ` +
+            "Is zenohd running? (e.g. ws://localhost:10000). Check config and adapter logs.")), CONNECT_TIMEOUT_MS);
+    });
+    await Promise.race([t.connect(), timeout]);
+}
+//# sourceMappingURL=transport-pool.js.map

package/dist/transport-pool.js.map

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

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@agenticros/core",
+  "version": "0.5.0",
+  "type": "module",
+  "description": "AgenticROS core — platform-agnostic ROS2 transport, types, and config (the dep every AgenticROS skill imports).",
+  "keywords": [
+    "agenticros",
+    "ros2",
+    "robotics",
+    "zenoh",
+    "rosbridge",
+    "webrtc",
+    "skill-sdk"
+  ],
+  "homepage": "https://github.com/agenticros/agenticros#readme",
+  "bugs": "https://github.com/agenticros/agenticros/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agenticros/agenticros.git",
+    "directory": "packages/core"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts.map",
+    "!dist/**/__tests__/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"dist/memory/__tests__/*.test.js\" \"dist/__tests__/*.test.js\"",
+    "prepublishOnly": "npm run build",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "@eclipse-zenoh/zenoh-ts": "^1.9.0",
+    "@foxglove/cdr": "^3.5.0",
+    "@foxglove/rosmsg": "^4.2.2",
+    "@foxglove/rosmsg2-serialization": "^3.1.0",
+    "node-datachannel": "^0.12.0",
+    "ws": "^8.18.0",
+    "zod": "^3.24.0"
+  },
+  "optionalDependencies": {
+    "rclnodejs": "^1.8.1"
+  },
+  "peerDependencies": {
+    "mem0ai": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mem0ai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.7.0"
+  },
+  "author": "PlaiPin",
+  "license": "Apache-2.0"
+}