@glubean/port 0.1.0

package/dist/providers/gemini.js

@@ -0,0 +1,378 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+import process from "node:process";
+import { AsyncQueue } from "../async-queue.js";
+import { JsonRpcLineConnection } from "../json-rpc.js";
+import { createPortFromAdapter } from "../port.js";
+import { providerRuntimeOptions, resolveRuntimeOptions } from "../options.js";
+import { normalizeTokenUsage } from "../token-usage.js";
+import { completedTurn } from "./common.js";
+export const geminiCapabilities = {
+    provider: "gemini",
+    nativeRpc: true,
+    transport: "stdio",
+    sessions: {
+        create: true,
+        resume: true,
+        attach: true,
+        status: true,
+        list: true,
+        close: true,
+    },
+    turns: {
+        start: true,
+        submit: true,
+        status: true,
+        wait: true,
+        cancel: true,
+        steer: false,
+        outputSchema: false,
+    },
+    events: {
+        messageDelta: true,
+        reasoningDelta: true,
+        toolLifecycle: true,
+        tokenUsage: true,
+        planUpdates: true,
+        diffUpdates: true,
+    },
+    structuredOutput: {
+        jsonMode: true,
+        nativeJsonSchema: false,
+        localValidation: true,
+        retry: true,
+    },
+    lifecycle: {
+        localState: true,
+        eventReplay: "memory",
+        status: "local",
+    },
+};
+export async function createGeminiPort(options) {
+    return createPortFromAdapter(await createGeminiAdapter(options));
+}
+export async function createGeminiAdapter(options) {
+    const runtime = new GeminiAcpRuntime(options);
+    await runtime.start();
+    return runtime.adapter;
+}
+class GeminiAcpRuntime {
+    #options;
+    #process;
+    #rpc;
+    #events = new EventEmitter();
+    #closed = false;
+    #activeTurns = new Map();
+    constructor(options) {
+        this.#options = options;
+    }
+    get adapter() {
+        return {
+            id: "gemini",
+            capabilities: geminiCapabilities,
+            createSession: (input = {}) => this.#createSession(input),
+            resumeSession: (input) => this.#resumeSession(input),
+            startTurn: (input) => this.#startTurn(input),
+            cancelTurn: (input) => this.#cancelTurn(input),
+            events: () => this.#allEvents(),
+            close: () => this.close(),
+        };
+    }
+    async start() {
+        if (this.#rpc)
+            return;
+        const runtimeOptions = resolveRuntimeOptions({ cwd: this.#options.cwd, options: this.#options.options });
+        const geminiOptions = providerRuntimeOptions(runtimeOptions);
+        const command = this.#options.command ?? "gemini";
+        const args = this.#options.args ?? buildGeminiArgs(runtimeOptions);
+        this.#process = spawn(command, args, {
+            cwd: runtimeOptions.cwd ?? process.cwd(),
+            stdio: ["pipe", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                ...this.#options.env,
+                ...(geminiOptions.settingsPath ? { GEMINI_CLI_SYSTEM_SETTINGS_PATH: geminiOptions.settingsPath } : {}),
+                NO_COLOR: "1",
+            },
+            shell: false,
+        });
+        this.#process.stderr.on("data", (chunk) => {
+            const message = chunk.toString("utf8").trim();
+            if (message)
+                this.#emit({ type: "error", message });
+        });
+        this.#process.on("exit", (code, signal) => {
+            if (!this.#closed) {
+                this.#emit({ type: "error", message: `Gemini ACP exited: code=${code ?? "null"} signal=${signal ?? "null"}` });
+            }
+        });
+        this.#rpc = new JsonRpcLineConnection(this.#process.stdout, this.#process.stdin);
+        this.#rpc.onNotification((notification) => {
+            for (const event of this.#normalizeNotification(notification))
+                this.#emit(event);
+        });
+        this.#rpc.onRequest((request) => this.#handleClientRequest(request));
+        await this.#rpc.request("initialize", {
+            protocolVersion: 1,
+            clientInfo: { name: "glubean-port", version: "0.0.0" },
+            clientCapabilities: {
+                fs: { readTextFile: false, writeTextFile: false },
+                terminal: false,
+                auth: { terminal: false },
+            },
+        });
+    }
+    async close() {
+        this.#closed = true;
+        this.#rpc?.close();
+        this.#process?.kill();
+    }
+    async #createSession(input) {
+        await this.start();
+        const runtimeOptions = resolveRuntimeOptions(input, this.#options.options);
+        const result = asRecord(await this.#requireRpc().request("session/new", {
+            cwd: runtimeOptions.cwd ?? this.#options.cwd ?? this.#options.options?.cwd ?? process.cwd(),
+            mcpServers: [],
+        }));
+        const id = asString(result.sessionId);
+        if (!id)
+            throw new Error("Gemini session/new response did not include sessionId");
+        await this.#applySessionOptions(id, runtimeOptions);
+        return {
+            id,
+            provider: "gemini",
+            native: { sessionId: id },
+        };
+    }
+    async #resumeSession(input) {
+        await this.start();
+        const runtimeOptions = resolveRuntimeOptions(input, this.#options.options);
+        await this.#requireRpc().request("session/load", {
+            sessionId: input.id,
+            cwd: runtimeOptions.cwd ?? this.#options.cwd ?? this.#options.options?.cwd ?? process.cwd(),
+            mcpServers: [],
+        });
+        await this.#applySessionOptions(input.id, runtimeOptions);
+        return {
+            id: input.id,
+            provider: "gemini",
+            native: { sessionId: input.id },
+        };
+    }
+    async *#startTurn(input) {
+        await this.start();
+        const runtimeOptions = resolveRuntimeOptions(input, this.#options.options);
+        const turnId = randomUUID();
+        const queue = new AsyncQueue();
+        const unsubscribe = this.#subscribe((event) => {
+            if ("sessionId" in event && event.sessionId && event.sessionId !== input.sessionId)
+                return;
+            if ("turnId" in event && event.turnId && event.turnId !== turnId)
+                return;
+            queue.push(event);
+        });
+        this.#activeTurns.set(input.sessionId, turnId);
+        const started = { type: "turn.started", sessionId: input.sessionId, turnId };
+        yield started;
+        this.#emit(started);
+        try {
+            await this.#applySessionOptions(input.sessionId, runtimeOptions);
+            const result = asRecord(await this.#requireRpc().request("session/prompt", {
+                sessionId: input.sessionId,
+                messageId: turnId,
+                prompt: toAcpPrompt(input.input),
+            }));
+            for (const event of tokenUsageEvents(result.usageMetadata ?? result.usage, input.sessionId, turnId))
+                this.#emit(event);
+            const stopReason = asString(result.stopReason);
+            const completed = completedTurn(input.sessionId, turnId, stopReason === "cancelled" ? "cancelled" : "completed");
+            this.#emit(completed);
+            queue.close();
+            for await (const event of queue)
+                yield event;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const errorEvent = { type: "error", sessionId: input.sessionId, turnId, message };
+            const completed = completedTurn(input.sessionId, turnId, "failed", message);
+            this.#emit(errorEvent);
+            this.#emit(completed);
+            queue.close();
+            for await (const event of queue)
+                yield event;
+        }
+        finally {
+            this.#activeTurns.delete(input.sessionId);
+            unsubscribe();
+            queue.close();
+        }
+    }
+    async #cancelTurn(input) {
+        await this.start();
+        this.#requireRpc().notify("session/cancel", { sessionId: input.sessionId });
+    }
+    async #applySessionOptions(sessionId, options) {
+        if (options.model) {
+            await this.#requireRpc().request("session/set_model", {
+                sessionId,
+                modelId: options.model,
+            });
+        }
+        const approvalMode = providerRuntimeOptions(options).approvalMode ?? toGeminiApprovalMode(options);
+        if (approvalMode) {
+            await this.#requireRpc().request("session/set_mode", {
+                sessionId,
+                modeId: approvalMode,
+            });
+        }
+    }
+    #normalizeNotification(notification) {
+        if (notification.method !== "session/update")
+            return [];
+        const params = asRecord(notification.params);
+        const sessionId = asString(params.sessionId);
+        if (!sessionId)
+            return [];
+        const turnId = this.#activeTurns.get(sessionId);
+        const update = asRecord(params.update);
+        const kind = asString(update.sessionUpdate);
+        const usageEvents = tokenUsageEvents(update.usageMetadata ?? update.usage ?? params.usageMetadata ?? params.usage, sessionId, turnId);
+        if (kind === "agent_message_chunk") {
+            const text = textFromAcpContent(update.content);
+            return [
+                ...(text ? [{ type: "message.delta", sessionId, turnId, role: "assistant", text }] : []),
+                ...usageEvents,
+            ];
+        }
+        if (kind === "agent_thought_chunk") {
+            const text = textFromAcpContent(update.content);
+            return [
+                ...(text ? [{ type: "reasoning.delta", sessionId, turnId, text }] : []),
+                ...usageEvents,
+            ];
+        }
+        if (kind === "plan") {
+            const entries = Array.isArray(update.entries) ? update.entries : [];
+            return turnId
+                ? [{
+                        type: "plan.updated",
+                        sessionId,
+                        turnId,
+                        steps: entries.flatMap((entry) => {
+                            const record = asRecord(entry);
+                            const step = asString(record.content);
+                            const status = normalizePlanStatus(asString(record.status));
+                            return step ? [{ step, status }] : [];
+                        }),
+                    }, ...usageEvents]
+                : usageEvents;
+        }
+        if (kind === "tool_call" || kind === "tool_call_update") {
+            const toolCallId = asString(update.toolCallId);
+            if (!toolCallId)
+                return usageEvents;
+            const title = asString(update.title) ?? "tool";
+            const status = asString(update.status);
+            if (status === "completed" || status === "failed") {
+                return [{ type: "tool.completed", sessionId, turnId, toolCallId, name: title, result: toJsonValue(update.rawOutput) }, ...usageEvents];
+            }
+            return [{ type: "tool.started", sessionId, turnId, toolCall: { id: toolCallId, name: title, input: toJsonValue(update.rawInput) } }, ...usageEvents];
+        }
+        return usageEvents;
+    }
+    #handleClientRequest(request) {
+        if (request.method === "session/request_permission") {
+            const params = asRecord(request.params);
+            const options = Array.isArray(params.options) ? params.options.map(asRecord) : [];
+            const rejected = options.find((option) => asString(option.kind)?.startsWith("reject"));
+            const selected = rejected ?? options[0];
+            const optionId = asString(selected?.optionId);
+            return optionId ? { outcome: "selected", optionId } : { outcome: "cancelled" };
+        }
+        throw new Error(`Unsupported Gemini client request: ${request.method}`);
+    }
+    #allEvents() {
+        const queue = new AsyncQueue();
+        const unsubscribe = this.#subscribe((event) => queue.push(event));
+        return {
+            [Symbol.asyncIterator]() {
+                const iterator = queue[Symbol.asyncIterator]();
+                return {
+                    next: () => iterator.next(),
+                    return: async () => {
+                        unsubscribe();
+                        queue.close();
+                        return { value: undefined, done: true };
+                    },
+                };
+            },
+        };
+    }
+    #subscribe(listener) {
+        this.#events.on("event", listener);
+        return () => this.#events.off("event", listener);
+    }
+    #emit(event) {
+        this.#events.emit("event", event);
+    }
+    #requireRpc() {
+        if (!this.#rpc)
+            throw new Error("Gemini runtime is not started");
+        return this.#rpc;
+    }
+}
+function toAcpPrompt(input) {
+    return input.map((item) => {
+        if (item.type === "text")
+            return { type: "text", text: item.text };
+        return { type: "text", text: `[local image: ${item.path}]` };
+    });
+}
+export function buildGeminiArgs(options = {}) {
+    const geminiOptions = providerRuntimeOptions(options);
+    const args = ["--acp"];
+    if (options.model)
+        args.push("--model", options.model);
+    const approvalMode = geminiOptions.approvalMode ?? toGeminiApprovalMode(options);
+    if (approvalMode)
+        args.push("--approval-mode", approvalMode);
+    if (geminiOptions.enableSandbox)
+        args.push("--sandbox");
+    return args;
+}
+function toGeminiApprovalMode(options) {
+    if (options.sandbox === "read-only")
+        return "plan";
+    if (options.approvalPolicy === "never")
+        return "yolo";
+    if (options.approvalPolicy === "on-failure")
+        return "auto_edit";
+    return undefined;
+}
+function textFromAcpContent(value) {
+    const content = asRecord(value);
+    if (asString(content.type) !== "text")
+        return undefined;
+    return asString(content.text);
+}
+function normalizePlanStatus(value) {
+    if (value === "in_progress" || value === "completed")
+        return value;
+    return "pending";
+}
+function tokenUsageEvents(value, sessionId, turnId) {
+    const usage = normalizeTokenUsage(value);
+    return usage ? [{ type: "token.usage", sessionId, ...(turnId ? { turnId } : {}), usage, native: toJsonValue(value) }] : [];
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function toJsonValue(value) {
+    if (value === undefined)
+        return undefined;
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/structured.d.ts

@@ -0,0 +1,8 @@
+import type { ProviderAdapter } from "./providers/adapter.ts";
+import type { StartStructuredTurnInput, StructuredTurnAttempt, StructuredTurnResult } from "./types.ts";
+export declare class StructuredTurnError extends Error {
+    attempts: StructuredTurnAttempt[];
+    constructor(message: string, attempts: StructuredTurnAttempt[]);
+}
+export declare function startStructuredTurn<T>(adapter: ProviderAdapter, input: StartStructuredTurnInput<T>): Promise<StructuredTurnResult<T>>;
+//# sourceMappingURL=structured.d.ts.map

package/dist/structured.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured.d.ts","sourceRoot":"","sources":["../src/structured.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAIV,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAIpB,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,EAAE,qBAAqB,EAAE,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,EAAE;CAK/D;AAED,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAmDlC"}

package/dist/structured.js

@@ -0,0 +1,127 @@
+const DEFAULT_MAX_RETRIES = 2;
+export class StructuredTurnError extends Error {
+    attempts;
+    constructor(message, attempts) {
+        super(message);
+        this.name = "StructuredTurnError";
+        this.attempts = attempts;
+    }
+}
+export async function startStructuredTurn(adapter, input) {
+    const outputSchema = input.outputSchema ?? (input.schema ? await zodToJsonSchema(input.schema) : undefined);
+    const maxRetries = input.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const shouldForceJson = input.jsonMode ?? Boolean(input.schema || outputSchema);
+    const attempts = [];
+    let lastError = "No attempt was run.";
+    for (let index = 0; index <= maxRetries; index += 1) {
+        const events = [];
+        let text = "";
+        const turnInput = {
+            ...input,
+            input: buildAttemptInput(input.input, {
+                attemptIndex: index,
+                shouldForceJson,
+                outputSchema,
+                lastError,
+                providerHasNativeSchema: adapter.capabilities.structuredOutput.nativeJsonSchema,
+            }),
+            ...(outputSchema && adapter.capabilities.structuredOutput.nativeJsonSchema ? { outputSchema } : {}),
+        };
+        try {
+            let failedTurnError;
+            for await (const event of adapter.startTurn(turnInput)) {
+                events.push(event);
+                if (event.type === "message.delta")
+                    text += event.text;
+                if (event.type === "turn.completed" && event.status !== "completed") {
+                    failedTurnError = event.error ?? `Turn ended with status ${event.status}`;
+                }
+            }
+            if (failedTurnError)
+                throw new Error(failedTurnError);
+            const json = parseJsonText(text);
+            const validated = input.schema?.safeParse(json);
+            if (validated && !validated.success) {
+                lastError = formatValidationError(validated.error);
+                attempts.push({ index, events, text, error: lastError });
+                continue;
+            }
+            const data = validated?.success ? validated.data : json;
+            attempts.push({ index, events, text });
+            return { data, json, text, attempts };
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+            attempts.push({ index, events, text, error: lastError });
+        }
+    }
+    throw new StructuredTurnError(`Structured turn failed after ${attempts.length} attempt(s): ${lastError}`, attempts);
+}
+function buildAttemptInput(input, options) {
+    if (!options.shouldForceJson)
+        return input;
+    if (options.attemptIndex > 0) {
+        return [
+            {
+                type: "text",
+                text: [
+                    "The previous response failed JSON validation.",
+                    "Return only corrected JSON. Do not include markdown fences or commentary.",
+                    `Validation error: ${options.lastError}`,
+                    options.outputSchema ? `Required JSON Schema: ${JSON.stringify(options.outputSchema)}` : "",
+                ].filter(Boolean).join("\n"),
+            },
+        ];
+    }
+    const instruction = [
+        "Return only valid JSON. Do not include markdown fences or commentary.",
+        options.outputSchema && !options.providerHasNativeSchema
+            ? `The JSON must match this JSON Schema: ${JSON.stringify(options.outputSchema)}`
+            : "",
+    ].filter(Boolean).join("\n");
+    return [...input, { type: "text", text: instruction }];
+}
+function parseJsonText(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        throw new Error("Provider returned an empty response.");
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+        if (fenced?.[1])
+            return JSON.parse(fenced[1].trim());
+        const objectStart = trimmed.indexOf("{");
+        const objectEnd = trimmed.lastIndexOf("}");
+        if (objectStart >= 0 && objectEnd > objectStart) {
+            return JSON.parse(trimmed.slice(objectStart, objectEnd + 1));
+        }
+        const arrayStart = trimmed.indexOf("[");
+        const arrayEnd = trimmed.lastIndexOf("]");
+        if (arrayStart >= 0 && arrayEnd > arrayStart) {
+            return JSON.parse(trimmed.slice(arrayStart, arrayEnd + 1));
+        }
+        throw new Error("Provider response was not parseable JSON.");
+    }
+}
+async function zodToJsonSchema(schema) {
+    try {
+        const zod = await import("zod");
+        const toJSONSchema = zod.toJSONSchema;
+        if (typeof toJSONSchema !== "function")
+            return undefined;
+        return JSON.parse(JSON.stringify(toJSONSchema(schema)));
+    }
+    catch {
+        return undefined;
+    }
+}
+function formatValidationError(error) {
+    const issues = error.issues;
+    if (Array.isArray(issues))
+        return JSON.stringify(issues);
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}

package/dist/token-usage.d.ts

@@ -0,0 +1,4 @@
+import type { JsonValue, TokenUsage } from "./types.ts";
+export declare function normalizeTokenUsage(value: unknown): TokenUsage | undefined;
+export declare function toJsonValue(value: unknown): JsonValue | undefined;
+//# sourceMappingURL=token-usage.d.ts.map

package/dist/token-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-usage.d.ts","sourceRoot":"","sources":["../src/token-usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAoC1E;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAGjE"}

package/dist/token-usage.js

@@ -0,0 +1,59 @@
+export function normalizeTokenUsage(value) {
+    const record = asRecord(value);
+    const cacheCreationInputTokens = readNumber(record, ["cacheCreationInputTokens", "cache_creation_input_tokens"]);
+    const cacheReadInputTokens = readNumber(record, ["cacheReadInputTokens", "cache_read_input_tokens"]);
+    const cachedInputTokens = readNumber(record, [
+        "cachedInputTokens",
+        "cached_input_tokens",
+        "cachedContentTokenCount",
+        "cached_content_token_count",
+        "cached_tokens",
+    ]) ?? readNumber(asRecord(record.input_tokens_details ?? record.inputTokensDetails), ["cached_tokens", "cachedTokens"])
+        ?? addNumbers(cacheCreationInputTokens, cacheReadInputTokens);
+    const usage = {
+        inputTokens: readNumber(record, ["inputTokens", "input_tokens", "promptTokens", "prompt_tokens", "promptTokenCount"]),
+        outputTokens: readNumber(record, [
+            "outputTokens",
+            "output_tokens",
+            "completionTokens",
+            "completion_tokens",
+            "candidatesTokenCount",
+        ]),
+        totalTokens: readNumber(record, ["totalTokens", "total_tokens", "totalTokenCount"]),
+        cachedInputTokens,
+        cacheCreationInputTokens,
+        cacheReadInputTokens,
+        reasoningOutputTokens: readNumber(record, [
+            "reasoningOutputTokens",
+            "reasoning_output_tokens",
+            "reasoningTokens",
+            "reasoning_tokens",
+            "thoughtsTokenCount",
+        ]) ?? readNumber(asRecord(record.output_tokens_details ?? record.outputTokensDetails), ["reasoning_tokens", "reasoningTokens"]),
+    };
+    return compactUsage(usage);
+}
+export function toJsonValue(value) {
+    if (value === undefined)
+        return undefined;
+    return JSON.parse(JSON.stringify(value));
+}
+function compactUsage(usage) {
+    const compact = Object.fromEntries(Object.entries(usage).filter(([, value]) => typeof value === "number"));
+    return Object.keys(compact).length > 0 ? compact : undefined;
+}
+function readNumber(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "number" && Number.isFinite(value))
+            return value;
+    }
+    return undefined;
+}
+function addNumbers(...values) {
+    const present = values.filter((value) => typeof value === "number");
+    return present.length > 0 ? present.reduce((sum, value) => sum + value, 0) : undefined;
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}