@glubean/port 0.1.0

package/README.md

@@ -0,0 +1,203 @@
+# Glubean Port
+
+Glubean Port is a small runtime adapter layer for local coding agents.
+
+The MVP exposes a neutral `session + turn + event + capability` API and includes Codex app-server, Claude Code, and Gemini ACP providers. Provider-specific runtime details are kept behind a typed adapter boundary, so callers can build their own orchestration on top without inheriting another caller's workflow concepts.
+
+## Scope
+
+- `@glubean/port` core types and `createPort()`.
+- Codex app-server over line-delimited JSON-RPC on stdio.
+- Claude Code over `--output-format stream-json`.
+- Gemini over ACP JSON-RPC on stdio.
+- Event normalization from provider notifications into `AgentEvent`.
+- Token usage telemetry via `token.usage` events when the provider reports it.
+- Structured JSON turns with optional Zod 4 validation and retry.
+- Local lifecycle state for sessions, managed turns, cancellation, wait results,
+  and in-memory event replay with sequence cursors.
+- Fixture tests that do not require a real Codex login or model call.
+
+Not in this MVP:
+
+- Caller orchestration state.
+- Domain-specific high-level APIs.
+
+## API Shape
+
+```ts
+import { createPort } from "@glubean/port"
+
+const port = await createPort({
+  provider: "codex",
+  cwd: process.cwd(),
+})
+
+const session = await port.sessions.create({
+  approvalPolicy: "on-request",
+  sandbox: "workspace-write",
+})
+
+for await (const event of port.turns.start({
+  sessionId: session.id,
+  input: [{ type: "text", text: "Review the current diff." }],
+})) {
+  console.log(event)
+}
+
+await port.close()
+```
+
+Managed lifecycle:
+
+```ts
+const session = await port.sessions.create()
+
+const turn = await port.turns.submit({
+  sessionId: session.id,
+  input: [{ type: "text", text: "Work on the leased task." }],
+  timeoutMs: 5 * 60_000,
+})
+
+for await (const event of port.turns.stream({ ...turn, afterSeq: 0 })) {
+  console.log(event.seq, event.type)
+  if (event.type === "turn.completed") break
+}
+
+const result = await port.turns.wait(turn)
+console.log(result.status, result.text)
+```
+
+Structured output:
+
+```ts
+import { z } from "zod"
+import { createPort } from "@glubean/port"
+
+const port = await createPort({ provider: "claude", cwd: process.cwd() })
+const session = await port.sessions.create()
+
+const result = await port.turns.startStructured({
+  sessionId: session.id,
+  input: [{ type: "text", text: "Return { ok: true }." }],
+  schema: z.object({ ok: z.literal(true) }),
+  maxRetries: 2,
+})
+
+console.log(result.data)
+```
+
+## Local Development
+
+Node 24 can run the TypeScript sources directly.
+
+```sh
+npm test
+npm run typecheck
+```
+
+To run live provider integrations, make sure `codex`, `claude`, and `gemini` are installed and authenticated:
+
+```sh
+npm run test:integration
+```
+
+To run a live Codex smoke:
+
+```sh
+npm run smoke:codex -- "Say ok and stop."
+```
+
+## Design Notes
+
+The public Port API is intentionally not a mirror of any provider:
+
+- Codex uses `thread` and `turn`.
+- ACP providers use `session` and `prompt`.
+- Claude Code currently exposes a stream-json CLI shape rather than a public JSON-RPC appserver.
+
+Port keeps provider-specific names in the adapter and exposes stable terms upward:
+
+- `sessions`
+- `turns`
+- `AgentEvent`
+- `capabilities`
+
+Token usage is reported as a neutral `token.usage` event with normalized
+`inputTokens`, `outputTokens`, `cachedInputTokens`, `reasoningOutputTokens`,
+and `totalTokens` fields when available. Managed turn status and wait results
+also expose the latest `usage` snapshot for the turn.
+
+Structured output is implemented above the provider adapters. Codex and Claude Code use native JSON Schema support; Gemini currently uses prompt constraints plus local validation and retry.
+
+Runtime options are split into provider-neutral fields and provider-specific fields. The selected provider binds the options type:
+
+```ts
+await createPort({
+  provider: "codex",
+  options: {
+    model: "gpt-5.5",
+    effort: "high",
+    sandbox: "workspace-write",
+  },
+})
+
+await createPort({
+  provider: "claude",
+  options: {
+    model: "sonnet",
+    permissionMode: "plan",
+    thinking: { type: "adaptive" },
+  },
+})
+
+await createPort({
+  provider: "gemini",
+  options: {
+    model: "gemini-2.5-pro",
+    approvalMode: "plan",
+    settingsPath: "/path/to/gemini-settings.json",
+  },
+})
+```
+
+Lifecycle state is also implemented above the provider adapters. Providers only
+need to expose create/resume/start/cancel primitives; Port records local
+session and turn status, stores an in-memory event log, and exposes replay via
+`events({ afterSeq })` or `turns.stream({ sessionId, turnId, afterSeq })`.
+This is intentionally runtime-level only: workflow envelopes, policy labels,
+ack/result protocols, and durable controller state stay above Port.
+
+## Type sync with consumers
+
+Port now ships a built artefact set: `dist/index.js` (JS) and
+`dist/index.d.ts` (full type declarations). `package.json#exports`
+points consumers at those, not at `src/`. Most consumers can therefore
+import Port's types directly — no shim needed — once they install the
+current packed tgz.
+
+For consumers still pinned to an older tgz (or `file:` link from
+before the dist build), a compile-time shim of the export surface
+still exists. The current shim of record:
+
+  - `gloop` → `gloop/src/types/glubean-port.d.ts` (narrow ambient
+    module declaring only the symbols `gloop`'s reviewer adapters
+    consume: `createPort`, `Port`, `RuntimeOptions`,
+    `RuntimeOptionsFor<P>`, `StartStructuredTurnInput`,
+    `StructuredTurnResult`, `StructuredTurnError`, the per-provider
+    enums like `ClaudePermissionMode` / `GeminiApprovalMode`, etc.)
+
+While the shim is in use, when you change the exported type surface
+in `src/index.ts` / `src/types.ts` — adding a field to
+`RuntimeOptions`, a new `StructuredTurnError` subclass, an additional
+provider id, anything that affects what `import type` consumers see —
+update the consumer's shim in the same change so the shim stays a
+strict subset of the dist declaration. TypeScript merges the two; the
+shim must NEVER tighten a field declared in the dist (only widen or
+add). Skipping the update leaves the consumer's `tsc` green against a
+stale view of Port's types and the divergence surfaces only at
+runtime.
+
+Removing a consumer's shim is a separate change: rebuild the
+consumer's lockfile against a tgz that ships dist, verify `tsc`
+greenness directly against `dist/index.d.ts`, then delete the shim
+file in a follow-up commit.

package/dist/async-queue.d.ts

@@ -0,0 +1,7 @@
+export declare class AsyncQueue<T> implements AsyncIterable<T> {
+    #private;
+    push(item: T): void;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+//# sourceMappingURL=async-queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"async-queue.d.ts","sourceRoot":"","sources":["../src/async-queue.ts"],"names":[],"mappings":"AAAA,qBAAa,UAAU,CAAC,CAAC,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;;IAKpD,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAUnB,KAAK,IAAI,IAAI;IAQb,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;CAc3C"}

package/dist/async-queue.js

@@ -0,0 +1,37 @@
+export class AsyncQueue {
+    #items = [];
+    #waiters = [];
+    #closed = false;
+    push(item) {
+        if (this.#closed)
+            return;
+        const waiter = this.#waiters.shift();
+        if (waiter) {
+            waiter({ value: item, done: false });
+            return;
+        }
+        this.#items.push(item);
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const waiter of this.#waiters.splice(0)) {
+            waiter({ value: undefined, done: true });
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const item = this.#items.shift();
+                if (item !== undefined) {
+                    return Promise.resolve({ value: item, done: false });
+                }
+                if (this.#closed) {
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise((resolve) => this.#waiters.push(resolve));
+            },
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import type { CreatePortInput, CreatePortInputFor, Port } from "./types.ts";
+export * from "./types.ts";
+export { CodexEventNormalizer } from "./providers/codex-normalizer.ts";
+export { codexCapabilities, createCodexAdapter, createCodexPort, createCodexThreadParams } from "./providers/codex.ts";
+export { claudeCapabilities, createClaudeAdapter, createClaudePort } from "./providers/claude.ts";
+export { geminiCapabilities, createGeminiAdapter, createGeminiPort } from "./providers/gemini.ts";
+export type { ProviderAdapter } from "./providers/adapter.ts";
+export { JsonRpcLineConnection } from "./json-rpc.ts";
+export { StructuredTurnError } from "./structured.ts";
+export declare function createPort(input: CreatePortInputFor<"codex">): Promise<Port<"codex">>;
+export declare function createPort(input: CreatePortInputFor<"claude">): Promise<Port<"claude">>;
+export declare function createPort(input: CreatePortInputFor<"gemini">): Promise<Port<"gemini">>;
+export declare function createPort(input: CreatePortInput): Promise<Port>;
+//# 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,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAK5E,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACvH,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAClG,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAClG,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,wBAAsB,UAAU,CAAC,KAAK,EAAE,kBAAkB,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;AAC7F,wBAAsB,UAAU,CAAC,KAAK,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC/F,wBAAsB,UAAU,CAAC,KAAK,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC/F,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+import { createCodexPort } from "./providers/codex.js";
+import { createClaudePort } from "./providers/claude.js";
+import { createGeminiPort } from "./providers/gemini.js";
+export * from "./types.js";
+export { CodexEventNormalizer } from "./providers/codex-normalizer.js";
+export { codexCapabilities, createCodexAdapter, createCodexPort, createCodexThreadParams } from "./providers/codex.js";
+export { claudeCapabilities, createClaudeAdapter, createClaudePort } from "./providers/claude.js";
+export { geminiCapabilities, createGeminiAdapter, createGeminiPort } from "./providers/gemini.js";
+export { JsonRpcLineConnection } from "./json-rpc.js";
+export { StructuredTurnError } from "./structured.js";
+export async function createPort(input) {
+    switch (input.provider) {
+        case "codex":
+            return createCodexPort({ ...input, provider: "codex" });
+        case "claude":
+            return createClaudePort({ ...input, provider: "claude" });
+        case "gemini":
+            return createGeminiPort({ ...input, provider: "gemini" });
+        default:
+            throw new Error(`Unsupported provider: ${input.provider}`);
+    }
+}

package/dist/json-rpc.d.ts

@@ -0,0 +1,31 @@
+import type { Readable, Writable } from "node:stream";
+import type { JsonValue } from "./types.ts";
+export type JsonRpcId = string | number | null;
+export type JsonRpcMessage = {
+    jsonrpc?: "2.0";
+    id?: JsonRpcId;
+    method?: string;
+    params?: JsonValue;
+    result?: JsonValue;
+    error?: {
+        code?: number;
+        message?: string;
+        data?: JsonValue;
+    };
+};
+export type JsonRpcNotification = {
+    method: string;
+    params?: JsonValue;
+};
+type RequestListener = (request: JsonRpcNotification) => JsonValue | undefined | Promise<JsonValue | undefined>;
+export declare class JsonRpcLineConnection {
+    #private;
+    constructor(input: Readable, output: Writable);
+    onNotification(listener: (notification: JsonRpcNotification) => void): () => void;
+    onRequest(listener: RequestListener): () => void;
+    request(method: string, params?: JsonValue): Promise<JsonValue | undefined>;
+    notify(method: string, params?: JsonValue): void;
+    close(): void;
+}
+export {};
+//# sourceMappingURL=json-rpc.d.ts.map

package/dist/json-rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-rpc.d.ts","sourceRoot":"","sources":["../src/json-rpc.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAE/C,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,CAAC,EAAE,KAAK,CAAC;IAChB,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC;CAC/D,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAOF,KAAK,eAAe,GAAG,CAAC,OAAO,EAAE,mBAAmB,KAAK,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;AAEhH,qBAAa,qBAAqB;;gBAQpB,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ;IAS7C,cAAc,CAAC,QAAQ,EAAE,CAAC,YAAY,EAAE,mBAAmB,KAAK,IAAI,GAAG,MAAM,IAAI;IAKjF,SAAS,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,IAAI;IAKhD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAS3E,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI;IAIhD,KAAK,IAAI,IAAI;CA0Fd"}

package/dist/json-rpc.js

@@ -0,0 +1,122 @@
+import { EventEmitter } from "node:events";
+export class JsonRpcLineConnection {
+    #input;
+    #output;
+    #nextId = 0;
+    #buffer = "";
+    #pending = new Map();
+    #events = new EventEmitter();
+    constructor(input, output) {
+        this.#input = input;
+        this.#output = output;
+        this.#input.setEncoding("utf8");
+        this.#input.on("data", (chunk) => this.#acceptChunk(chunk));
+        this.#input.on("error", (error) => this.#rejectAll(error));
+        this.#input.on("close", () => this.#rejectAll(new Error("JSON-RPC input closed")));
+    }
+    onNotification(listener) {
+        this.#events.on("notification", listener);
+        return () => this.#events.off("notification", listener);
+    }
+    onRequest(listener) {
+        this.#events.on("request", listener);
+        return () => this.#events.off("request", listener);
+    }
+    request(method, params) {
+        const id = ++this.#nextId;
+        const message = { jsonrpc: "2.0", id, method, params };
+        this.#write(message);
+        return new Promise((resolve, reject) => {
+            this.#pending.set(id, { resolve, reject });
+        });
+    }
+    notify(method, params) {
+        this.#write({ jsonrpc: "2.0", method, params });
+    }
+    close() {
+        this.#rejectAll(new Error("JSON-RPC connection closed"));
+        this.#input.destroy();
+        this.#output.end();
+    }
+    #write(message) {
+        this.#output.write(`${JSON.stringify(message)}\n`);
+    }
+    #acceptChunk(chunk) {
+        this.#buffer += chunk;
+        while (true) {
+            const newlineIndex = this.#buffer.indexOf("\n");
+            if (newlineIndex === -1)
+                break;
+            const line = this.#buffer.slice(0, newlineIndex).trim();
+            this.#buffer = this.#buffer.slice(newlineIndex + 1);
+            if (line)
+                this.#acceptLine(line);
+        }
+    }
+    #acceptLine(line) {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            this.#events.emit("notification", {
+                method: "port/invalid-json",
+                params: { line },
+            });
+            return;
+        }
+        if (message.id !== undefined && (message.result !== undefined || message.error !== undefined)) {
+            const pending = this.#pending.get(message.id);
+            if (!pending)
+                return;
+            this.#pending.delete(message.id);
+            if (message.error) {
+                pending.reject(new Error(message.error.message ?? "JSON-RPC request failed"));
+                return;
+            }
+            pending.resolve(message.result);
+            return;
+        }
+        if (message.id !== undefined && typeof message.method === "string") {
+            void this.#acceptRequest(message.id, message.method, message.params);
+            return;
+        }
+        if (typeof message.method === "string") {
+            this.#events.emit("notification", {
+                method: message.method,
+                params: message.params,
+            });
+        }
+    }
+    async #acceptRequest(id, method, params) {
+        const listeners = this.#events.listeners("request");
+        if (listeners.length === 0) {
+            this.#write({
+                jsonrpc: "2.0",
+                id,
+                error: { code: -32601, message: `Method not found: ${method}` },
+            });
+            return;
+        }
+        try {
+            const result = await listeners[0]({ method, params });
+            this.#write({ jsonrpc: "2.0", id, result });
+        }
+        catch (error) {
+            this.#write({
+                jsonrpc: "2.0",
+                id,
+                error: {
+                    code: -32000,
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            });
+        }
+    }
+    #rejectAll(error) {
+        for (const pending of this.#pending.values()) {
+            pending.reject(error);
+        }
+        this.#pending.clear();
+    }
+}

package/dist/lifecycle.d.ts

@@ -0,0 +1,4 @@
+import type { ProviderAdapter } from "./providers/adapter.ts";
+import type { Port, ProviderId } from "./types.ts";
+export declare function createLifecyclePort<P extends ProviderId>(adapter: ProviderAdapter<P>): Port<P>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,OAAO,KAAK,EAMV,IAAI,EACJ,UAAU,EAkBX,MAAM,YAAY,CAAC;AAiCpB,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,UAAU,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAE9F"}