@thinkwell/conductor 0.2.0

package/dist/message-queue.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Central message queue for the conductor
+ *
+ * All routing flows through this queue, preserving message ordering.
+ * The queue supports async iteration, allowing the conductor's main loop
+ * to consume messages as they arrive.
+ */
+import type { ConductorMessage } from "./types.js";
+/**
+ * A message queue with async iteration support.
+ *
+ * Messages can be pushed from multiple sources (client, proxies, agent)
+ * and are consumed in order by the conductor's event loop.
+ */
+export declare class MessageQueue {
+    private queue;
+    private resolvers;
+    private closed;
+    /**
+     * Push a message onto the queue.
+     *
+     * If there's a waiting consumer, the message is delivered immediately.
+     * Otherwise, it's buffered until the next consumer is ready.
+     */
+    push(message: ConductorMessage): void;
+    /**
+     * Close the queue, causing the async iterator to complete.
+     */
+    close(): void;
+    /**
+     * Check if the queue has been closed
+     */
+    isClosed(): boolean;
+    /**
+     * Async iterator for consuming messages.
+     *
+     * This allows the conductor to use `for await` to process messages:
+     * ```typescript
+     * for await (const msg of messageQueue) {
+     *   await handleMessage(msg);
+     * }
+     * ```
+     */
+    [Symbol.asyncIterator](): AsyncIterator<ConductorMessage>;
+}
+//# sourceMappingURL=message-queue.d.ts.map

package/dist/message-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-queue.d.ts","sourceRoot":"","sources":["../src/message-queue.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAarC;;OAEG;IACH,KAAK,IAAI,IAAI;IAUb;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;;;;;;;;OASG;IACI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,gBAAgB,CAAC;CA4BjE"}

package/dist/message-queue.js

@@ -0,0 +1,90 @@
+/**
+ * Central message queue for the conductor
+ *
+ * All routing flows through this queue, preserving message ordering.
+ * The queue supports async iteration, allowing the conductor's main loop
+ * to consume messages as they arrive.
+ */
+/**
+ * A message queue with async iteration support.
+ *
+ * Messages can be pushed from multiple sources (client, proxies, agent)
+ * and are consumed in order by the conductor's event loop.
+ */
+export class MessageQueue {
+    queue = [];
+    resolvers = [];
+    closed = false;
+    /**
+     * Push a message onto the queue.
+     *
+     * If there's a waiting consumer, the message is delivered immediately.
+     * Otherwise, it's buffered until the next consumer is ready.
+     */
+    push(message) {
+        if (this.closed) {
+            return;
+        }
+        if (this.resolvers.length > 0) {
+            const resolve = this.resolvers.shift();
+            resolve(message);
+        }
+        else {
+            this.queue.push(message);
+        }
+    }
+    /**
+     * Close the queue, causing the async iterator to complete.
+     */
+    close() {
+        this.closed = true;
+        // Wake up any waiting consumers so they can exit
+        for (const resolve of this.resolvers) {
+            // Push a shutdown message to signal completion
+            resolve({ type: "shutdown" });
+        }
+        this.resolvers = [];
+    }
+    /**
+     * Check if the queue has been closed
+     */
+    isClosed() {
+        return this.closed;
+    }
+    /**
+     * Async iterator for consuming messages.
+     *
+     * This allows the conductor to use `for await` to process messages:
+     * ```typescript
+     * for await (const msg of messageQueue) {
+     *   await handleMessage(msg);
+     * }
+     * ```
+     */
+    async *[Symbol.asyncIterator]() {
+        while (!this.closed) {
+            let message;
+            if (this.queue.length > 0) {
+                message = this.queue.shift();
+            }
+            else {
+                message = await new Promise((resolve) => {
+                    this.resolvers.push(resolve);
+                });
+            }
+            // Check for shutdown message
+            if (message.type === "shutdown") {
+                return;
+            }
+            yield message;
+        }
+        // Drain any remaining messages in the queue
+        while (this.queue.length > 0) {
+            const message = this.queue.shift();
+            if (message.type !== "shutdown") {
+                yield message;
+            }
+        }
+    }
+}
+//# sourceMappingURL=message-queue.js.map

package/dist/message-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-queue.js","sourceRoot":"","sources":["../src/message-queue.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;GAKG;AACH,MAAM,OAAO,YAAY;IACf,KAAK,GAAuB,EAAE,CAAC;IAC/B,SAAS,GAA2C,EAAE,CAAC;IACvD,MAAM,GAAG,KAAK,CAAC;IAEvB;;;;;OAKG;IACH,IAAI,CAAC,OAAyB;QAC5B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QAED,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAG,CAAC;YACxC,OAAO,CAAC,OAAO,CAAC,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,iDAAiD;QACjD,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACrC,+CAA+C;YAC/C,OAAO,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;QAChC,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAC3B,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACpB,IAAI,OAAyB,CAAC;YAE9B,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1B,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAG,CAAC;YAChC,CAAC;iBAAM,CAAC;gBACN,OAAO,GAAG,MAAM,IAAI,OAAO,CAAmB,CAAC,OAAO,EAAE,EAAE;oBACxD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC/B,CAAC,CAAC,CAAC;YACL,CAAC;YAED,6BAA6B;YAC7B,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAChC,OAAO;YACT,CAAC;YAED,MAAM,OAAO,CAAC;QAChB,CAAC;QAED,4CAA4C;QAC5C,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAG,CAAC;YACpC,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAChC,MAAM,OAAO,CAAC;YAChB,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Internal types for the conductor
+ */
+import type { JsonRpcMessage, Dispatch } from "@thinkwell/protocol";
+/**
+ * Role identifiers for the conductor's connections
+ */
+export type RoleId = "client" | "agent" | "proxy" | "conductor";
+/**
+ * Role relationships - encode at runtime what Rust does at compile time
+ */
+export declare const ROLE_COUNTERPART: Record<RoleId, RoleId>;
+/**
+ * Index identifying a source component for right-to-left messages
+ */
+export type SourceIndex = {
+    type: "proxy";
+    index: number;
+} | {
+    type: "successor";
+};
+/**
+ * Messages flowing through the conductor's central queue
+ */
+export type ConductorMessage = {
+    type: "left-to-right";
+    targetIndex: number;
+    dispatch: Dispatch;
+} | {
+    type: "right-to-left";
+    sourceIndex: SourceIndex;
+    dispatch: Dispatch;
+} | {
+    type: "mcp-connection-received";
+    acpUrl: string;
+    connectionId: string;
+} | {
+    type: "mcp-connection-established";
+    connectionId: string;
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+} | {
+    type: "mcp-client-to-server";
+    connectionId: string;
+    dispatch: Dispatch;
+} | {
+    type: "mcp-connection-disconnected";
+    connectionId: string;
+} | {
+    type: "shutdown";
+};
+/**
+ * A bidirectional connection to a component (client, proxy, or agent)
+ */
+export interface ComponentConnection {
+    /** Send a message to this component */
+    send(message: JsonRpcMessage): void;
+    /** Receive messages from this component */
+    messages: AsyncIterable<JsonRpcMessage>;
+    /** Close the connection */
+    close(): Promise<void>;
+}
+/**
+ * Factory for creating component connections
+ */
+export interface ComponentConnector {
+    /** Open a bidirectional JSON-RPC connection */
+    connect(): Promise<ComponentConnection>;
+}
+/**
+ * ACP initialize request structure
+ */
+export interface InitializeRequest {
+    method: "initialize" | "acp/initialize";
+    params?: {
+        clientInfo?: {
+            name?: string;
+            version?: string;
+        };
+        capabilities?: {
+            mcp_acp_transport?: boolean;
+            [key: string]: unknown;
+        };
+        _meta?: {
+            proxy?: boolean;
+            [key: string]: unknown;
+        };
+        mcpServers?: Array<{
+            name: string;
+            url: string;
+            type?: string;
+        }>;
+        [key: string]: unknown;
+    };
+}
+/**
+ * ACP initialize response structure
+ */
+export interface InitializeResponse {
+    serverInfo?: {
+        name?: string;
+        version?: string;
+    };
+    capabilities?: {
+        mcp_acp_transport?: boolean;
+        [key: string]: unknown;
+    };
+    _meta?: {
+        proxy?: boolean;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Result of component instantiation
+ */
+export interface InstantiatedComponents {
+    proxies: ComponentConnector[];
+    agent: ComponentConnector;
+}
+/**
+ * Interface for instantiating components when the first initialize request arrives
+ */
+export interface ComponentInstantiator {
+    instantiate(initRequest: InitializeRequest): Promise<InstantiatedComponents>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * Internal types for the conductor
+ */
+/**
+ * Role relationships - encode at runtime what Rust does at compile time
+ */
+export const ROLE_COUNTERPART = {
+    client: "agent",
+    agent: "client",
+    proxy: "conductor",
+    conductor: "proxy",
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA2B;IACtD,MAAM,EAAE,OAAO;IACf,KAAK,EAAE,QAAQ;IACf,KAAK,EAAE,WAAW;IAClB,SAAS,EAAE,OAAO;CACnB,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@thinkwell/conductor",
+  "version": "0.2.0",
+  "description": "TypeScript conductor for ACP proxy chains - orchestrates message routing between clients, proxies, and agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "acp",
+    "mcp",
+    "thinkwell",
+    "conductor",
+    "proxy",
+    "agent"
+  ],
+  "author": "David Herman",
+  "license": "MIT",
+  "dependencies": {
+    "@thinkwell/protocol": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.4",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "node --test --import tsx src/**/*.test.ts"
+  }
+}