@llm4ts/core 2.2.0 → 2.3.0

package/dist/providers/GeminiAcpSession.d.ts

@@ -0,0 +1,67 @@
+import * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import { ProviderError, type LlmError } from "../Errors.ts";
+import type { ProcessExecutorShape } from "../ProcessExecutor.ts";
+import { type JsonRecord, type JsonValue } from "./CliSupport.ts";
+/**
+ * ACP (Agent Client Protocol, `gemini --experimental-acp`) message shapes
+ * are best-effort against public docs (geminicli.com/docs/cli/acp-mode,
+ * agentclientprotocol.com) — there is no installed `gemini` binary in CI to
+ * verify against (the repo's CI constraint is exactly "no installed
+ * provider CLIs"). Tests here exercise this module against a scripted fake
+ * peer, the same posture ClaudeAgentSession.test.ts takes against a fake
+ * `claude` process. A first live run against a real `gemini` is an
+ * integration smoke test, not a substitute for that determinism.
+ */
+export declare const geminiAcpArgv: (model: string | undefined) => ReadonlyArray<string>;
+export declare const acpInitializeParams: JsonRecord;
+export declare const acpNewSessionParams: (cwd: string, mcpServerUrl: string) => JsonRecord;
+export declare const acpPromptParams: (sessionId: string, text: string) => JsonRecord;
+export declare const acpInitializeLine: (id: number) => string;
+export declare const acpNewSessionLine: (id: number, cwd: string, mcpServerUrl: string) => string;
+export declare const acpPromptLine: (id: number, sessionId: string, text: string) => string;
+export declare const acpPermissionResponseLine: (id: JsonValue, approved: boolean) => string;
+export declare const acpUnsupportedFsResponseLine: (id: JsonValue) => string;
+export declare class AcpTextChunk {
+    readonly text: string;
+    readonly _tag = "TextChunk";
+    constructor(text: string);
+}
+export declare class AcpToolCallObserved {
+    readonly id: string;
+    readonly name: string;
+    readonly input: JsonValue;
+    readonly _tag = "ToolCallObserved";
+    constructor(id: string, name: string, input: JsonValue);
+}
+export declare class AcpPermissionRequested {
+    readonly id: string;
+    readonly toolCallId: string;
+    readonly name: string;
+    readonly _tag = "PermissionRequested";
+    constructor(id: string, toolCallId: string, name: string);
+}
+export type AcpSessionEvent = AcpTextChunk | AcpToolCallObserved | AcpPermissionRequested;
+export interface AcpPromptResult {
+    readonly text: string;
+    readonly stopReason: string;
+}
+export interface AcpApprovalPolicy {
+    readonly decide: (toolName: string, input: JsonValue) => Effect.Effect<boolean>;
+}
+/**
+ * The safety decision belongs to whichever side actually executes the tool
+ * (pi, over the MCP bridge) — gemini's own permission prompt is a formality
+ * for a call this session never runs itself, so the default is to approve.
+ */
+export declare const alwaysApprove: AcpApprovalPolicy;
+export interface GeminiAcpSessionShape {
+    readonly events: Stream.Stream<AcpSessionEvent, LlmError>;
+    readonly newSession: (cwd: string, mcpServerUrl: string) => Effect.Effect<string, LlmError>;
+    readonly prompt: (sessionId: string, text: string) => Effect.Effect<AcpPromptResult, LlmError>;
+    readonly cancel: Effect.Effect<void>;
+}
+export declare const parseAcpSessionUpdate: (params: JsonValue | undefined) => AcpSessionEvent | undefined;
+export declare const openGeminiAcpSession: (executor: ProcessExecutorShape, argv: readonly string[], cwd: string, envVars?: Readonly<Record<string, string>> | undefined, approval?: AcpApprovalPolicy | undefined) => Effect.Effect<GeminiAcpSessionShape, ProviderError | import("../Errors.ts").UsageLimitError | import("../Errors.ts").AuthenticationError | import("../Errors.ts").InvalidRequestError | import("../Errors.ts").ParseError | import("../Errors.ts").ToolError | import("../Errors.ts").ConfigError | import("../Errors.ts").RateLimitError | import("../Errors.ts").TimeoutError | import("../Errors.ts").TurnLimitError, Scope.Scope>;
+//# sourceMappingURL=GeminiAcpSession.d.ts.map

package/dist/providers/GeminiAcpSession.d.ts.map

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

package/dist/providers/GeminiAcpSession.js

@@ -0,0 +1,239 @@
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as PubSub from "effect/PubSub";
+import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Stream from "effect/Stream";
+import { ProviderError } from "../Errors.js";
+import { isJsonRecord, jsonField, jsonStringField, jsonText, parseJsonLine } from "./CliSupport.js";
+/**
+ * ACP (Agent Client Protocol, `gemini --experimental-acp`) message shapes
+ * are best-effort against public docs (geminicli.com/docs/cli/acp-mode,
+ * agentclientprotocol.com) — there is no installed `gemini` binary in CI to
+ * verify against (the repo's CI constraint is exactly "no installed
+ * provider CLIs"). Tests here exercise this module against a scripted fake
+ * peer, the same posture ClaudeAgentSession.test.ts takes against a fake
+ * `claude` process. A first live run against a real `gemini` is an
+ * integration smoke test, not a substitute for that determinism.
+ */
+export const geminiAcpArgv = (model) => [
+    "gemini",
+    "--experimental-acp",
+    ...(model === undefined ? [] : ["-m", model])
+];
+const clientCapabilities = {
+    fs: { readTextFile: false, writeTextFile: false },
+    terminal: false
+};
+export const acpInitializeParams = {
+    protocolVersion: 1,
+    clientInfo: { name: "llm4ts", version: "1" },
+    clientCapabilities
+};
+export const acpNewSessionParams = (cwd, mcpServerUrl) => ({
+    cwd,
+    mcpServers: [{ type: "http", url: mcpServerUrl }]
+});
+export const acpPromptParams = (sessionId, text) => ({
+    sessionId,
+    prompt: [{ type: "text", text }]
+});
+const jsonRpcRequest = (id, method, params) => jsonText({ jsonrpc: "2.0", id, method, params });
+export const acpInitializeLine = (id) => jsonRpcRequest(id, "initialize", acpInitializeParams);
+export const acpNewSessionLine = (id, cwd, mcpServerUrl) => jsonRpcRequest(id, "session/new", acpNewSessionParams(cwd, mcpServerUrl));
+export const acpPromptLine = (id, sessionId, text) => jsonRpcRequest(id, "session/prompt", acpPromptParams(sessionId, text));
+export const acpPermissionResponseLine = (id, approved) => jsonText({
+    jsonrpc: "2.0",
+    id,
+    result: { outcome: approved ? "Approved" : "Denied" }
+});
+export const acpUnsupportedFsResponseLine = (id) => jsonText({
+    jsonrpc: "2.0",
+    id,
+    error: { code: -32601, message: "fs access not supported by this client" }
+});
+export class AcpTextChunk {
+    text;
+    _tag = "TextChunk";
+    constructor(text) {
+        this.text = text;
+    }
+}
+export class AcpToolCallObserved {
+    id;
+    name;
+    input;
+    _tag = "ToolCallObserved";
+    constructor(id, name, input) {
+        this.id = id;
+        this.name = name;
+        this.input = input;
+    }
+}
+export class AcpPermissionRequested {
+    id;
+    toolCallId;
+    name;
+    _tag = "PermissionRequested";
+    constructor(id, toolCallId, name) {
+        this.id = id;
+        this.toolCallId = toolCallId;
+        this.name = name;
+    }
+}
+/**
+ * The safety decision belongs to whichever side actually executes the tool
+ * (pi, over the MCP bridge) — gemini's own permission prompt is a formality
+ * for a call this session never runs itself, so the default is to approve.
+ */
+export const alwaysApprove = {
+    decide: () => Effect.succeed(true)
+};
+const contentTextOf = (value) => jsonStringField(jsonField(value, "content"), "text");
+/** `content_chunk` and `agent_message_chunk` are both seen across ACP revisions for a text delta. */
+const textChunkUpdate = (update) => {
+    const type = jsonStringField(update, "type");
+    return type === "content_chunk" || type === "agent_message_chunk"
+        ? contentTextOf(update)
+        : undefined;
+};
+const toolCallUpdate = (update) => {
+    if (jsonStringField(update, "type") !== "tool_call") {
+        return undefined;
+    }
+    const toolCall = jsonField(update, "toolCall");
+    const id = jsonStringField(toolCall, "id");
+    return id === undefined
+        ? undefined
+        : new AcpToolCallObserved(id, jsonStringField(toolCall, "name") ?? "", jsonField(toolCall, "input") ?? {});
+};
+export const parseAcpSessionUpdate = (params) => {
+    const update = jsonField(params, "update");
+    const text = textChunkUpdate(update);
+    return text !== undefined && text.length > 0 ? new AcpTextChunk(text) : toolCallUpdate(update);
+};
+export const openGeminiAcpSession = Effect.fn("@llm4ts/core/providers/GeminiAcpSession.open")(function* (executor, argv, cwd, envVars = {}, approval = alwaysApprove) {
+    const [stdin, stdout] = yield* executor.runBidirectional(argv, cwd, envVars);
+    const events = yield* PubSub.unbounded();
+    // Accumulated directly by the background reader below rather than via a
+    // subscription `prompt` opens on demand: a subscription opened only when
+    // `prompt` runs can race a canned/fast-replaying stdout (real or faked in
+    // tests) that the reader has already drained by then. One prompt in
+    // flight at a time (the single-active-session assumption) makes
+    // reset-then-read at each call's boundary sufficient.
+    const accumulatedText = yield* Ref.make("");
+    const nextId = yield* Ref.make(0);
+    const pending = yield* Ref.make(new Map());
+    const allocateId = Ref.updateAndGet(nextId, (current) => current + 1);
+    const registerPending = Effect.fn("@llm4ts/core/providers/GeminiAcpSession.registerPending")(function* (id) {
+        const deferred = yield* Deferred.make();
+        yield* Ref.update(pending, (current) => {
+            const next = new Map(current);
+            next.set(id, deferred);
+            return next;
+        });
+        return deferred;
+    });
+    const resolvePending = Effect.fn("@llm4ts/core/providers/GeminiAcpSession.resolvePending")(function* (id, result, error) {
+        const current = yield* Ref.get(pending);
+        const deferred = current.get(id);
+        if (deferred === undefined) {
+            return;
+        }
+        yield* Ref.update(pending, (map) => {
+            const next = new Map(map);
+            next.delete(id);
+            return next;
+        });
+        if (error !== undefined) {
+            yield* Deferred.fail(deferred, ProviderError.make({
+                message: `Gemini ACP error: ${jsonStringField(error, "message") ?? jsonText(error)}`
+            }));
+            return;
+        }
+        yield* Deferred.succeed(deferred, result ?? {});
+    });
+    const respondToPermission = Effect.fn("@llm4ts/core/providers/GeminiAcpSession.respondToPermission")(function* (requestId, toolName, input) {
+        const approved = yield* approval.decide(toolName, input);
+        yield* Queue.offer(stdin, acpPermissionResponseLine(requestId, approved));
+    });
+    const handleAgentRequest = Effect.fn("@llm4ts/core/providers/GeminiAcpSession.handleAgentRequest")(function* (id, method, params) {
+        switch (method) {
+            case "session/request_permission": {
+                const toolCall = jsonField(params, "toolCall");
+                const toolCallId = jsonStringField(toolCall, "id") ?? "";
+                const toolName = jsonStringField(toolCall, "name") ?? "";
+                yield* PubSub.publish(events, new AcpPermissionRequested(typeof id === "string" ? id : jsonText(id), toolCallId, toolName));
+                yield* respondToPermission(id, toolName, jsonField(toolCall, "input") ?? {});
+                return;
+            }
+            case "fs/read_text_file":
+            case "fs/write_text_file":
+                yield* Queue.offer(stdin, acpUnsupportedFsResponseLine(id));
+                return;
+            default:
+                return;
+        }
+    });
+    const handleLine = Effect.fn("@llm4ts/core/providers/GeminiAcpSession.handleLine")(function* (line) {
+        const json = parseJsonLine(line);
+        if (json === undefined || !isJsonRecord(json)) {
+            return;
+        }
+        const id = jsonField(json, "id");
+        const method = jsonStringField(json, "method");
+        if (method === "session/update") {
+            const event = parseAcpSessionUpdate(jsonField(json, "params"));
+            if (event !== undefined) {
+                if (event._tag === "TextChunk") {
+                    yield* Ref.update(accumulatedText, (current) => current + event.text);
+                }
+                yield* PubSub.publish(events, event);
+            }
+            return;
+        }
+        if (method !== undefined) {
+            if (id !== undefined) {
+                yield* handleAgentRequest(id, method, jsonField(json, "params"));
+            }
+            return;
+        }
+        if (typeof id === "number") {
+            yield* resolvePending(id, jsonField(json, "result"), jsonField(json, "error"));
+        }
+    });
+    yield* stdout.pipe(Stream.mapEffect(handleLine), Stream.runDrain, Effect.catch(() => Effect.void), Effect.forkScoped);
+    const call = Effect.fn("@llm4ts/core/providers/GeminiAcpSession.call")(function* (method, params) {
+        const id = yield* allocateId;
+        const deferred = yield* registerPending(id);
+        yield* Queue.offer(stdin, jsonRpcRequest(id, method, params));
+        return yield* Deferred.await(deferred);
+    });
+    const newSession = (cwd, mcpServerUrl) => Effect.gen(function* () {
+        yield* call("initialize", acpInitializeParams);
+        const result = yield* call("session/new", acpNewSessionParams(cwd, mcpServerUrl));
+        const sessionId = jsonStringField(result, "sessionId");
+        if (sessionId === undefined) {
+            return yield* ProviderError.make({
+                message: "Gemini ACP session/new did not return a sessionId"
+            });
+        }
+        return sessionId;
+    });
+    const prompt = (sessionId, text) => Effect.gen(function* () {
+        yield* Ref.set(accumulatedText, "");
+        const result = yield* call("session/prompt", acpPromptParams(sessionId, text));
+        const finalText = yield* Ref.get(accumulatedText);
+        return {
+            text: finalText,
+            stopReason: jsonStringField(result, "stopReason") ?? "Completed"
+        };
+    });
+    return {
+        events: Stream.fromPubSub(events),
+        newSession,
+        prompt,
+        cancel: Queue.shutdown(stdin)
+    };
+});
+//# sourceMappingURL=GeminiAcpSession.js.map

package/dist/providers/GeminiAcpSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GeminiAcpSession.js","sourceRoot":"","sources":["../../src/providers/GeminiAcpSession.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,GAAG,MAAM,YAAY,CAAA;AAEjC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,aAAa,EAAiB,MAAM,cAAc,CAAA;AAE3D,OAAO,EACL,YAAY,EACZ,SAAS,EACT,eAAe,EACf,QAAQ,EACR,aAAa,EAGd,MAAM,iBAAiB,CAAA;AAExB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAyB,EAAyB,EAAE,CAAC;IACjF,QAAQ;IACR,oBAAoB;IACpB,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;CAC9C,CAAA;AAED,MAAM,kBAAkB,GAAe;IACrC,EAAE,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE;IACjD,QAAQ,EAAE,KAAK;CAChB,CAAA;AAED,MAAM,CAAC,MAAM,mBAAmB,GAAe;IAC7C,eAAe,EAAE,CAAC;IAClB,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE;IAC5C,kBAAkB;CACnB,CAAA;AAED,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAW,EAAE,YAAoB,EAAc,EAAE,CAAC,CAAC;IACrF,GAAG;IACH,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC;CAClD,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,SAAiB,EAAE,IAAY,EAAc,EAAE,CAAC,CAAC;IAC/E,SAAS;IACT,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;CACjC,CAAC,CAAA;AAEF,MAAM,cAAc,GAAG,CAAC,EAAU,EAAE,MAAc,EAAE,MAAkB,EAAU,EAAE,CAChF,QAAQ,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAElD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,EAAU,EAAU,EAAE,CACtD,cAAc,CAAC,EAAE,EAAE,YAAY,EAAE,mBAAmB,CAAC,CAAA;AAEvD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,EAAU,EAAE,GAAW,EAAE,YAAoB,EAAU,EAAE,CACzF,cAAc,CAAC,EAAE,EAAE,aAAa,EAAE,mBAAmB,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,CAAA;AAE3E,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,EAAU,EAAE,SAAiB,EAAE,IAAY,EAAU,EAAE,CACnF,cAAc,CAAC,EAAE,EAAE,gBAAgB,EAAE,eAAe,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAA;AAExE,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,EAAa,EAAE,QAAiB,EAAU,EAAE,CACpF,QAAQ,CAAC;IACP,OAAO,EAAE,KAAK;IACd,EAAE;IACF,MAAM,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE;CACtD,CAAC,CAAA;AAEJ,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,EAAa,EAAU,EAAE,CACpE,QAAQ,CAAC;IACP,OAAO,EAAE,KAAK;IACd,EAAE;IACF,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,wCAAwC,EAAE;CAC3E,CAAC,CAAA;AAEJ,MAAM,OAAO,YAAY;IAEF;IADZ,IAAI,GAAG,WAAW,CAAA;IAC3B,YAAqB,IAAY;QAAZ,SAAI,GAAJ,IAAI,CAAQ;IAAG,CAAC;CACtC;AAED,MAAM,OAAO,mBAAmB;IAGnB;IACA;IACA;IAJF,IAAI,GAAG,kBAAkB,CAAA;IAClC,YACW,EAAU,EACV,IAAY,EACZ,KAAgB;QAFhB,OAAE,GAAF,EAAE,CAAQ;QACV,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAW;IACxB,CAAC;CACL;AAED,MAAM,OAAO,sBAAsB;IAGtB;IACA;IACA;IAJF,IAAI,GAAG,qBAAqB,CAAA;IACrC,YACW,EAAU,EACV,UAAkB,EAClB,IAAY;QAFZ,OAAE,GAAF,EAAE,CAAQ;QACV,eAAU,GAAV,UAAU,CAAQ;QAClB,SAAI,GAAJ,IAAI,CAAQ;IACpB,CAAC;CACL;AAaD;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAsB;IAC9C,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;CACnC,CAAA;AASD,MAAM,aAAa,GAAG,CAAC,KAA4B,EAAsB,EAAE,CACzE,eAAe,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,CAAA;AAEtD,qGAAqG;AACrG,MAAM,eAAe,GAAG,CAAC,MAA6B,EAAsB,EAAE;IAC5E,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5C,OAAO,IAAI,KAAK,eAAe,IAAI,IAAI,KAAK,qBAAqB;QAC/D,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC;QACvB,CAAC,CAAC,SAAS,CAAA;AACf,CAAC,CAAA;AAED,MAAM,cAAc,GAAG,CAAC,MAA6B,EAAmC,EAAE;IACxF,IAAI,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,WAAW,EAAE,CAAC;QACpD,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAC9C,MAAM,EAAE,GAAG,eAAe,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;IAC1C,OAAO,EAAE,KAAK,SAAS;QACrB,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,IAAI,mBAAmB,CACrB,EAAE,EACF,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,EACvC,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE,CACnC,CAAA;AACP,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,MAA6B,EACA,EAAE;IAC/B,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAC1C,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,CAAA;IACpC,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAA;AAChG,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,EAAE,CAAC,8CAA8C,CAAC,CAC3F,QAAQ,CAAC,EACP,QAA8B,EAC9B,IAA2B,EAC3B,GAAW,EACX,UAA4C,EAAE,EAC9C,WAA8B,aAAa;IAE3C,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;IAC5E,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,SAAS,EAAmB,CAAA;IACzD,wEAAwE;IACxE,yEAAyE;IACzE,0EAA0E;IAC1E,oEAAoE;IACpE,gEAAgE;IAChE,sDAAsD;IACtD,MAAM,eAAe,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC3C,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,CAC7B,IAAI,GAAG,EAAE,CACV,CAAA;IAED,MAAM,UAAU,GAAG,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,GAAG,CAAC,CAAC,CAAA;IAErE,MAAM,eAAe,GAAG,MAAM,CAAC,EAAE,CAAC,yDAAyD,CAAC,CAC1F,QAAQ,CAAC,EAAE,EAAU;QACnB,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAuB,CAAA;QAC5D,KAAK,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,EAAE;YACrC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAA;YAC7B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAA;YACtB,OAAO,IAAI,CAAA;QACb,CAAC,CAAC,CAAA;QACF,OAAO,QAAQ,CAAA;IACjB,CAAC,CACF,CAAA;IAED,MAAM,cAAc,GAAG,MAAM,CAAC,EAAE,CAAC,wDAAwD,CAAC,CACxF,QAAQ,CAAC,EAAE,EAAU,EAAE,MAA6B,EAAE,KAA4B;QAChF,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QACvC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QAChC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAM;QACR,CAAC;QACD,KAAK,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACjC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;YACzB,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;YACf,OAAO,IAAI,CAAA;QACb,CAAC,CAAC,CAAA;QACF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,CAClB,QAAQ,EACR,aAAa,CAAC,IAAI,CAAC;gBACjB,OAAO,EAAE,qBAAqB,eAAe,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE;aACrF,CAAC,CACH,CAAA;YACD,OAAM;QACR,CAAC;QACD,KAAK,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,CAAC,CAAA;IACjD,CAAC,CACF,CAAA;IAED,MAAM,mBAAmB,GAAG,MAAM,CAAC,EAAE,CACnC,6DAA6D,CAC9D,CAAC,QAAQ,CAAC,EAAE,SAAoB,EAAE,QAAgB,EAAE,KAAgB;QACnE,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;QACxD,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,yBAAyB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAA;IAC3E,CAAC,CAAC,CAAA;IAEF,MAAM,kBAAkB,GAAG,MAAM,CAAC,EAAE,CAClC,4DAA4D,CAC7D,CAAC,QAAQ,CAAC,EAAE,EAAa,EAAE,MAAc,EAAE,MAA6B;QACvE,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,4BAA4B,CAAC,CAAC,CAAC;gBAClC,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;gBAC9C,MAAM,UAAU,GAAG,eAAe,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,CAAA;gBACxD,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,CAAA;gBACxD,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CACnB,MAAM,EACN,IAAI,sBAAsB,CACxB,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAC1C,UAAU,EACV,QAAQ,CACT,CACF,CAAA;gBACD,KAAK,CAAC,CAAC,mBAAmB,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;gBAC5E,OAAM;YACR,CAAC;YACD,KAAK,mBAAmB,CAAC;YACzB,KAAK,oBAAoB;gBACvB,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,4BAA4B,CAAC,EAAE,CAAC,CAAC,CAAA;gBAC3D,OAAM;YACR;gBACE,OAAM;QACV,CAAC;IACH,CAAC,CAAC,CAAA;IAEF,MAAM,UAAU,GAAG,MAAM,CAAC,EAAE,CAAC,oDAAoD,CAAC,CAAC,QAAQ,CAAC,EAC1F,IAAY;QAEZ,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,CAAA;QAChC,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9C,OAAM;QACR,CAAC;QACD,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QAChC,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;QAE9C,IAAI,MAAM,KAAK,gBAAgB,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,qBAAqB,CAAC,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAA;YAC9D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;oBAC/B,KAAK,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAA;gBACvE,CAAC;gBACD,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;YACtC,CAAC;YACD,OAAM;QACR,CAAC;QAED,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;gBACrB,KAAK,CAAC,CAAC,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAA;YAClE,CAAC;YACD,OAAM;QACR,CAAC;QAED,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;YAC3B,KAAK,CAAC,CAAC,cAAc,CAAC,EAAE,EAAE,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;QAChF,CAAC;IACH,CAAC,CAAC,CAAA;IAEF,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAChB,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,EAC5B,MAAM,CAAC,QAAQ,EACf,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAC/B,MAAM,CAAC,UAAU,CAClB,CAAA;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC,8CAA8C,CAAC,CAAC,QAAQ,CAAC,EAC9E,MAAc,EACd,MAAkB;QAElB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,UAAU,CAAA;QAC5B,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,CAAA;QAC3C,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;QAC7D,OAAO,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;IACxC,CAAC,CAAC,CAAA;IAEF,MAAM,UAAU,GAAG,CAAC,GAAW,EAAE,YAAoB,EAAmC,EAAE,CACxF,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAClB,KAAK,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAA;QAC9C,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,aAAa,EAAE,mBAAmB,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,CAAA;QACjF,MAAM,SAAS,GAAG,eAAe,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;QACtD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,KAAK,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC;gBAC/B,OAAO,EAAE,mDAAmD;aAC7D,CAAC,CAAA;QACJ,CAAC;QACD,OAAO,SAAS,CAAA;IAClB,CAAC,CAAC,CAAA;IAEJ,MAAM,MAAM,GAAG,CAAC,SAAiB,EAAE,IAAY,EAA4C,EAAE,CAC3F,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAClB,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,eAAe,EAAE,EAAE,CAAC,CAAA;QACnC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAA;QAC9E,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,eAAe,CAAC,CAAA;QACjD,OAAO;YACL,IAAI,EAAE,SAAS;YACf,UAAU,EAAE,eAAe,CAAC,MAAM,EAAE,YAAY,CAAC,IAAI,WAAW;SACjE,CAAA;IACH,CAAC,CAAC,CAAA;IAEJ,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;QACjC,UAAU;QACV,MAAM;QACN,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;KAC9B,CAAA;AACH,CAAC,CACF,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/core",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Effect-native LLM contracts, providers, tools, evaluation, and observability",
   "license": "MIT",
   "type": "module",
@@ -46,6 +46,7 @@
     "./providers/ConnectorFactories": "./dist/providers/ConnectorFactories.js",
     "./providers/CopilotConnector": "./dist/providers/CopilotConnector.js",
     "./providers/CursorConnector": "./dist/providers/CursorConnector.js",
+    "./providers/GeminiAcpSession": "./dist/providers/GeminiAcpSession.js",
     "./providers/GeminiApiProvider": "./dist/providers/GeminiApiProvider.js",
     "./providers/GeminiCliProvider": "./dist/providers/GeminiCliProvider.js",
     "./providers/GeminiModels": "./dist/providers/GeminiModels.js",

package/src/providers/GeminiAcpSession.ts

@@ -0,0 +1,344 @@
+import * as Deferred from "effect/Deferred"
+import * as Effect from "effect/Effect"
+import * as PubSub from "effect/PubSub"
+import * as Queue from "effect/Queue"
+import * as Ref from "effect/Ref"
+import type * as Scope from "effect/Scope"
+import * as Stream from "effect/Stream"
+import { ProviderError, type LlmError } from "../Errors.ts"
+import type { ProcessExecutorShape } from "../ProcessExecutor.ts"
+import {
+  isJsonRecord,
+  jsonField,
+  jsonStringField,
+  jsonText,
+  parseJsonLine,
+  type JsonRecord,
+  type JsonValue
+} from "./CliSupport.ts"
+
+/**
+ * ACP (Agent Client Protocol, `gemini --experimental-acp`) message shapes
+ * are best-effort against public docs (geminicli.com/docs/cli/acp-mode,
+ * agentclientprotocol.com) — there is no installed `gemini` binary in CI to
+ * verify against (the repo's CI constraint is exactly "no installed
+ * provider CLIs"). Tests here exercise this module against a scripted fake
+ * peer, the same posture ClaudeAgentSession.test.ts takes against a fake
+ * `claude` process. A first live run against a real `gemini` is an
+ * integration smoke test, not a substitute for that determinism.
+ */
+export const geminiAcpArgv = (model: string | undefined): ReadonlyArray<string> => [
+  "gemini",
+  "--experimental-acp",
+  ...(model === undefined ? [] : ["-m", model])
+]
+
+const clientCapabilities: JsonRecord = {
+  fs: { readTextFile: false, writeTextFile: false },
+  terminal: false
+}
+
+export const acpInitializeParams: JsonRecord = {
+  protocolVersion: 1,
+  clientInfo: { name: "llm4ts", version: "1" },
+  clientCapabilities
+}
+
+export const acpNewSessionParams = (cwd: string, mcpServerUrl: string): JsonRecord => ({
+  cwd,
+  mcpServers: [{ type: "http", url: mcpServerUrl }]
+})
+
+export const acpPromptParams = (sessionId: string, text: string): JsonRecord => ({
+  sessionId,
+  prompt: [{ type: "text", text }]
+})
+
+const jsonRpcRequest = (id: number, method: string, params: JsonRecord): string =>
+  jsonText({ jsonrpc: "2.0", id, method, params })
+
+export const acpInitializeLine = (id: number): string =>
+  jsonRpcRequest(id, "initialize", acpInitializeParams)
+
+export const acpNewSessionLine = (id: number, cwd: string, mcpServerUrl: string): string =>
+  jsonRpcRequest(id, "session/new", acpNewSessionParams(cwd, mcpServerUrl))
+
+export const acpPromptLine = (id: number, sessionId: string, text: string): string =>
+  jsonRpcRequest(id, "session/prompt", acpPromptParams(sessionId, text))
+
+export const acpPermissionResponseLine = (id: JsonValue, approved: boolean): string =>
+  jsonText({
+    jsonrpc: "2.0",
+    id,
+    result: { outcome: approved ? "Approved" : "Denied" }
+  })
+
+export const acpUnsupportedFsResponseLine = (id: JsonValue): string =>
+  jsonText({
+    jsonrpc: "2.0",
+    id,
+    error: { code: -32601, message: "fs access not supported by this client" }
+  })
+
+export class AcpTextChunk {
+  readonly _tag = "TextChunk"
+  constructor(readonly text: string) {}
+}
+
+export class AcpToolCallObserved {
+  readonly _tag = "ToolCallObserved"
+  constructor(
+    readonly id: string,
+    readonly name: string,
+    readonly input: JsonValue
+  ) {}
+}
+
+export class AcpPermissionRequested {
+  readonly _tag = "PermissionRequested"
+  constructor(
+    readonly id: string,
+    readonly toolCallId: string,
+    readonly name: string
+  ) {}
+}
+
+export type AcpSessionEvent = AcpTextChunk | AcpToolCallObserved | AcpPermissionRequested
+
+export interface AcpPromptResult {
+  readonly text: string
+  readonly stopReason: string
+}
+
+export interface AcpApprovalPolicy {
+  readonly decide: (toolName: string, input: JsonValue) => Effect.Effect<boolean>
+}
+
+/**
+ * The safety decision belongs to whichever side actually executes the tool
+ * (pi, over the MCP bridge) — gemini's own permission prompt is a formality
+ * for a call this session never runs itself, so the default is to approve.
+ */
+export const alwaysApprove: AcpApprovalPolicy = {
+  decide: () => Effect.succeed(true)
+}
+
+export interface GeminiAcpSessionShape {
+  readonly events: Stream.Stream<AcpSessionEvent, LlmError>
+  readonly newSession: (cwd: string, mcpServerUrl: string) => Effect.Effect<string, LlmError>
+  readonly prompt: (sessionId: string, text: string) => Effect.Effect<AcpPromptResult, LlmError>
+  readonly cancel: Effect.Effect<void>
+}
+
+const contentTextOf = (value: JsonValue | undefined): string | undefined =>
+  jsonStringField(jsonField(value, "content"), "text")
+
+/** `content_chunk` and `agent_message_chunk` are both seen across ACP revisions for a text delta. */
+const textChunkUpdate = (update: JsonValue | undefined): string | undefined => {
+  const type = jsonStringField(update, "type")
+  return type === "content_chunk" || type === "agent_message_chunk"
+    ? contentTextOf(update)
+    : undefined
+}
+
+const toolCallUpdate = (update: JsonValue | undefined): AcpToolCallObserved | undefined => {
+  if (jsonStringField(update, "type") !== "tool_call") {
+    return undefined
+  }
+  const toolCall = jsonField(update, "toolCall")
+  const id = jsonStringField(toolCall, "id")
+  return id === undefined
+    ? undefined
+    : new AcpToolCallObserved(
+        id,
+        jsonStringField(toolCall, "name") ?? "",
+        jsonField(toolCall, "input") ?? {}
+      )
+}
+
+export const parseAcpSessionUpdate = (
+  params: JsonValue | undefined
+): AcpSessionEvent | undefined => {
+  const update = jsonField(params, "update")
+  const text = textChunkUpdate(update)
+  return text !== undefined && text.length > 0 ? new AcpTextChunk(text) : toolCallUpdate(update)
+}
+
+export const openGeminiAcpSession = Effect.fn("@llm4ts/core/providers/GeminiAcpSession.open")(
+  function* (
+    executor: ProcessExecutorShape,
+    argv: ReadonlyArray<string>,
+    cwd: string,
+    envVars: Readonly<Record<string, string>> = {},
+    approval: AcpApprovalPolicy = alwaysApprove
+  ): Effect.fn.Return<GeminiAcpSessionShape, LlmError, Scope.Scope> {
+    const [stdin, stdout] = yield* executor.runBidirectional(argv, cwd, envVars)
+    const events = yield* PubSub.unbounded<AcpSessionEvent>()
+    // Accumulated directly by the background reader below rather than via a
+    // subscription `prompt` opens on demand: a subscription opened only when
+    // `prompt` runs can race a canned/fast-replaying stdout (real or faked in
+    // tests) that the reader has already drained by then. One prompt in
+    // flight at a time (the single-active-session assumption) makes
+    // reset-then-read at each call's boundary sufficient.
+    const accumulatedText = yield* Ref.make("")
+    const nextId = yield* Ref.make(0)
+    const pending = yield* Ref.make<ReadonlyMap<number, Deferred.Deferred<JsonValue, LlmError>>>(
+      new Map()
+    )
+
+    const allocateId = Ref.updateAndGet(nextId, (current) => current + 1)
+
+    const registerPending = Effect.fn("@llm4ts/core/providers/GeminiAcpSession.registerPending")(
+      function* (id: number): Effect.fn.Return<Deferred.Deferred<JsonValue, LlmError>> {
+        const deferred = yield* Deferred.make<JsonValue, LlmError>()
+        yield* Ref.update(pending, (current) => {
+          const next = new Map(current)
+          next.set(id, deferred)
+          return next
+        })
+        return deferred
+      }
+    )
+
+    const resolvePending = Effect.fn("@llm4ts/core/providers/GeminiAcpSession.resolvePending")(
+      function* (id: number, result: JsonValue | undefined, error: JsonValue | undefined) {
+        const current = yield* Ref.get(pending)
+        const deferred = current.get(id)
+        if (deferred === undefined) {
+          return
+        }
+        yield* Ref.update(pending, (map) => {
+          const next = new Map(map)
+          next.delete(id)
+          return next
+        })
+        if (error !== undefined) {
+          yield* Deferred.fail(
+            deferred,
+            ProviderError.make({
+              message: `Gemini ACP error: ${jsonStringField(error, "message") ?? jsonText(error)}`
+            })
+          )
+          return
+        }
+        yield* Deferred.succeed(deferred, result ?? {})
+      }
+    )
+
+    const respondToPermission = Effect.fn(
+      "@llm4ts/core/providers/GeminiAcpSession.respondToPermission"
+    )(function* (requestId: JsonValue, toolName: string, input: JsonValue) {
+      const approved = yield* approval.decide(toolName, input)
+      yield* Queue.offer(stdin, acpPermissionResponseLine(requestId, approved))
+    })
+
+    const handleAgentRequest = Effect.fn(
+      "@llm4ts/core/providers/GeminiAcpSession.handleAgentRequest"
+    )(function* (id: JsonValue, method: string, params: JsonValue | undefined) {
+      switch (method) {
+        case "session/request_permission": {
+          const toolCall = jsonField(params, "toolCall")
+          const toolCallId = jsonStringField(toolCall, "id") ?? ""
+          const toolName = jsonStringField(toolCall, "name") ?? ""
+          yield* PubSub.publish(
+            events,
+            new AcpPermissionRequested(
+              typeof id === "string" ? id : jsonText(id),
+              toolCallId,
+              toolName
+            )
+          )
+          yield* respondToPermission(id, toolName, jsonField(toolCall, "input") ?? {})
+          return
+        }
+        case "fs/read_text_file":
+        case "fs/write_text_file":
+          yield* Queue.offer(stdin, acpUnsupportedFsResponseLine(id))
+          return
+        default:
+          return
+      }
+    })
+
+    const handleLine = Effect.fn("@llm4ts/core/providers/GeminiAcpSession.handleLine")(function* (
+      line: string
+    ) {
+      const json = parseJsonLine(line)
+      if (json === undefined || !isJsonRecord(json)) {
+        return
+      }
+      const id = jsonField(json, "id")
+      const method = jsonStringField(json, "method")
+
+      if (method === "session/update") {
+        const event = parseAcpSessionUpdate(jsonField(json, "params"))
+        if (event !== undefined) {
+          if (event._tag === "TextChunk") {
+            yield* Ref.update(accumulatedText, (current) => current + event.text)
+          }
+          yield* PubSub.publish(events, event)
+        }
+        return
+      }
+
+      if (method !== undefined) {
+        if (id !== undefined) {
+          yield* handleAgentRequest(id, method, jsonField(json, "params"))
+        }
+        return
+      }
+
+      if (typeof id === "number") {
+        yield* resolvePending(id, jsonField(json, "result"), jsonField(json, "error"))
+      }
+    })
+
+    yield* stdout.pipe(
+      Stream.mapEffect(handleLine),
+      Stream.runDrain,
+      Effect.catch(() => Effect.void),
+      Effect.forkScoped
+    )
+
+    const call = Effect.fn("@llm4ts/core/providers/GeminiAcpSession.call")(function* (
+      method: string,
+      params: JsonRecord
+    ): Effect.fn.Return<JsonValue, LlmError> {
+      const id = yield* allocateId
+      const deferred = yield* registerPending(id)
+      yield* Queue.offer(stdin, jsonRpcRequest(id, method, params))
+      return yield* Deferred.await(deferred)
+    })
+
+    const newSession = (cwd: string, mcpServerUrl: string): Effect.Effect<string, LlmError> =>
+      Effect.gen(function* () {
+        yield* call("initialize", acpInitializeParams)
+        const result = yield* call("session/new", acpNewSessionParams(cwd, mcpServerUrl))
+        const sessionId = jsonStringField(result, "sessionId")
+        if (sessionId === undefined) {
+          return yield* ProviderError.make({
+            message: "Gemini ACP session/new did not return a sessionId"
+          })
+        }
+        return sessionId
+      })
+
+    const prompt = (sessionId: string, text: string): Effect.Effect<AcpPromptResult, LlmError> =>
+      Effect.gen(function* () {
+        yield* Ref.set(accumulatedText, "")
+        const result = yield* call("session/prompt", acpPromptParams(sessionId, text))
+        const finalText = yield* Ref.get(accumulatedText)
+        return {
+          text: finalText,
+          stopReason: jsonStringField(result, "stopReason") ?? "Completed"
+        }
+      })
+
+    return {
+      events: Stream.fromPubSub(events),
+      newSession,
+      prompt,
+      cancel: Queue.shutdown(stdin)
+    }
+  }
+)