@fungi.computer/knapsack 0.1.0 → 0.2.0

package/dist/files.js

@@ -1,5 +1,5 @@
 import { nanoid } from "@fungi.computer/cairn";
-import { Mycelium, } from "@fungi.computer/mycelium";
+import { MAX_EXECUTION_IMAGES, Mycelium, } from "@fungi.computer/mycelium";
 import * as Effect from "effect/Effect";
 import * as Stream from "effect/Stream";
 import { patchInputSchema, patchOutputSchema } from "./files-patch.js";
@@ -7,11 +7,14 @@ export { patchInputSchema, patchOutputSchema } from "./files-patch.js";
 import { patchGrammar } from "./patch-grammar.js";
 import { diffLines, formatPatch, structuredPatch } from "diff";
 import { z } from "zod";
-import { maximumReadBytes, pathSchema, boundedTextSchema, readInputSchema, readOutputSchema, } from "./files-read.js";
-export { readInputSchema, readOutputSchema };
+import { maximumImageBytes, maximumReadBytes, pathSchema, boundedTextSchema, readInputSchema, readGuestOutputSchema, readOutputSchema, } from "./files-read.js";
+export { readGuestOutputSchema, readInputSchema, readOutputSchema };
 const maximumPatternCharacters = 512;
 const maximumResultEntries = 256;
+const defaultSearchResults = 100;
+const maximumFoundLineCharacters = 500;
 const maximumReadBytesText = String(maximumReadBytes);
+const readDescription = `Read one bounded UTF-8 file page, or a whole png, jpeg, gif or webp image returned as an image you can look at (sent at most ${String(maximumImageBytes / 1_024)} KiB; the host may shrink it and refuses an image it cannot read or fit).`;
 const maximumUnifiedPatchBytes = 65_536;
 const utf8 = new TextEncoder();
 /** Expected Files edit refusal, kept distinct from unexpected host failures. */
@@ -25,70 +28,45 @@ export class FilesEditError extends Error {
         this.name = "FilesEditError";
     }
 }
-/** Bounded directory listing request. */
-export const listInputSchema = z.strictObject({
-    path: pathSchema,
-    limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(maximumResultEntries)
-        .default(maximumResultEntries),
-});
-const listEntrySchema = z.lazy(() => z.strictObject({
-    path: pathSchema,
-    name: z.string().min(1),
-    type: z.enum(["file", "directory", "symlink"]),
-    size: z.number().int().nonnegative(),
-    modifiedAt: z.number(),
+const searchLimitSchema = z
+    .number()
+    .int()
+    .min(1)
+    .max(maximumResultEntries)
+    .default(defaultSearchResults);
+const searchPatternSchema = z.string().min(1).max(maximumPatternCharacters);
+/** List one directory level. */
+export const listInputSchema = z.lazy(() => z.strictObject({
+    path: pathSchema.default("."),
+    limit: searchLimitSchema,
 }));
-/** Directory entries and an explicit truncation flag. */
-export const listOutputSchema = z.lazy(() => z.strictObject({
-    path: pathSchema,
-    entries: z.array(listEntrySchema).max(maximumResultEntries),
-    truncated: z.boolean(),
-}));
-/** Bounded path-pattern search request. */
+/** Match paths below a directory by glob. */
 export const globInputSchema = z.lazy(() => z.strictObject({
-    path: pathSchema,
-    pattern: z.string().min(1).max(maximumPatternCharacters),
-    limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(maximumResultEntries)
-        .default(maximumResultEntries),
+    path: pathSchema.default("."),
+    pattern: searchPatternSchema,
+    limit: searchLimitSchema,
 }));
-/** Matching paths and an explicit truncation flag. */
-export const globOutputSchema = z.lazy(() => z.strictObject({
-    path: pathSchema,
-    matches: z.array(pathSchema).max(maximumResultEntries),
-    truncated: z.boolean(),
-}));
-/** Bounded content-search request with optional regular-expression matching. */
+/** Search file content, optionally restricted to matching paths. */
 export const grepInputSchema = z.lazy(() => z.strictObject({
-    path: pathSchema,
-    pattern: z.string().min(1).max(maximumPatternCharacters),
+    path: pathSchema.default("."),
+    pattern: searchPatternSchema,
+    include: searchPatternSchema.optional(),
     regex: z.boolean().default(false),
     ignoreCase: z.boolean().default(false),
-    limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(maximumResultEntries)
-        .default(maximumResultEntries),
+    limit: searchLimitSchema,
 }));
-/** Content matches and an explicit truncation flag. */
-export const grepOutputSchema = z.lazy(() => z.strictObject({
+/** One found path, with the matching line when the search was by content. */
+const foundSchema = z.lazy(() => z.strictObject({
     path: pathSchema,
-    matches: z
-        .array(z.strictObject({
-        path: pathSchema,
-        line: z.number().int().positive(),
-        text: z.string(),
-    }))
-        .max(maximumResultEntries),
-    truncated: z.boolean(),
+    type: z.enum(["file", "directory", "symlink"]).exactOptional(),
+    line: z.number().int().positive().exactOptional(),
+    text: z.string().exactOptional(),
+}));
+/** Found paths or matching lines, and which cap (if any) cut the search short. */
+export const searchOutputSchema = z.lazy(() => z.strictObject({
+    path: pathSchema,
+    results: z.array(foundSchema).max(maximumResultEntries),
+    truncated: z.enum(["limit", "scan"]).nullable(),
 }));
 /** Text replacement request decoded before the captured Files port is called. */
 export const editInputSchema = z.lazy(() => z.strictObject({
@@ -116,6 +94,7 @@ export const filesEditFailureSchema = z.lazy(() => z.strictObject({
             "ambiguous",
             "file-too-large",
             "partial-character",
+            "not-text",
             "unchanged",
             "conflict",
         ]),
@@ -281,6 +260,9 @@ async function applyEdit(port, input, context) {
         offset: 0,
         limit: maximumReadBytes,
     }, context));
+    if ("image" in current) {
+        throw new FilesEditError("not-text", input.path, "file is an image, not editable text");
+    }
     if (current.truncated) {
         throw new FilesEditError("file-too-large", input.path, `File exceeds ${maximumReadBytesText} bytes; use files.patch for a small change`);
     }
@@ -357,6 +339,12 @@ function runFileOperation(invoke) {
 function runPatch(invoke, input) {
     return runFileOperation((context) => invoke(input, context));
 }
+/** Keep model parameters while omitting the decoder's schema-document marker. */
+function toolParameters(schema) {
+    const parameters = z.toJSONSchema(schema, { io: "input" });
+    delete parameters.$schema;
+    return parameters;
+}
 /** Direct presentation of the same validated Files operation. */
 function patchTool(invokePatch) {
     const tool = {
@@ -368,7 +356,7 @@ function patchTool(invokePatch) {
             name: "apply_patch",
             description: "Apply a Codex patch to the selected Files root. Example:\n*** Begin Patch\n*** Update File: path/to/file\n@@\n context line\n-old line\n+new line\n*** End Patch\nUse @@ alone or followed by an existing context line; unified-diff @@ line numbers are not supported. Add/Delete File and optional Move to are also supported. Paths stay inside the root; symlinks and parent traversal are rejected. A failure returns recovery guidance and may follow earlier file writes; inspect the result before retrying. Prefer this to shell or Python replacement.",
             // Model-facing parameters derived from the one Zod decoder `prepare` uses.
-            parameters: z.toJSONSchema(patchInputSchema),
+            parameters: toolParameters(patchInputSchema),
             constrainedSampling: {
                 type: "grammar",
                 variants: { openai_lark: patchGrammar },
@@ -397,8 +385,109 @@ function patchTool(invokePatch) {
     };
     return tool;
 }
+// One explicit scope difference, shared by both projections of each search.
+const searchScopeDescription = "Search skips .git and gitignored paths.";
+const searchDescriptions = {
+    list: `List one directory level. ${searchScopeDescription}`,
+    glob: `Find paths by glob. ${searchScopeDescription}`,
+    grep: `Search file content. ${searchScopeDescription}`,
+};
+/** Long matching lines would flood the context; the cap is applied once, here. */
+function capFoundLines(output) {
+    return {
+        ...output,
+        results: output.results.map((found) => found.text === undefined ||
+            found.text.length <= maximumFoundLineCharacters
+            ? found
+            : {
+                ...found,
+                text: `${found.text.slice(0, maximumFoundLineCharacters)}…`,
+            }),
+    };
+}
+/** Plain lines for the model: `path`, or `path:line: text`, then why it stopped early. */
+function renderFound(output) {
+    const lines = output.results.map((found) => found.line === undefined
+        ? `${found.path}${found.type === "directory" ? "/" : ""}`
+        : `${found.path}:${String(found.line)}: ${found.text ?? ""}`);
+    if (lines.length === 0 && output.truncated === null)
+        lines.push("(nothing found)");
+    if (output.truncated === "limit")
+        lines.push("[truncated: result limit reached; raise limit or narrow path]");
+    if (output.truncated === "scan")
+        lines.push("[truncated: scan limit reached before the search finished; narrow path]");
+    return lines.join("\n");
+}
+function presentSearch(result) {
+    return {
+        content: [{ type: "text", text: renderFound(result) }],
+        isError: false,
+    };
+}
+/**
+ * Guest code and MCP callers never receive base64: the image goes through the
+ * execution's image collector (the `images.view` path) and the value is a caption.
+ */
+export function presentReadForGuest(result, context) {
+    if (!("image" in result))
+        return result;
+    if (context.images === undefined)
+        throw new Error("Images can only be read inside execute or through the read tool.");
+    const { mimeType, data, bytes } = result.image;
+    const ref = context.images.push({
+        data,
+        mimeType,
+        path: result.path,
+        bytes,
+    });
+    return { path: result.path, image: { ref, mimeType, bytes } };
+}
+/**
+ * Images reach the model as an image part; text pages stay JSON text. The
+ * Files surface counts the images it shows and refuses past the run limit.
+ */
+function presentRead(admit) {
+    return (result) => {
+        if (!("image" in result))
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+                isError: false,
+            };
+        if (!admit())
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Image limit reached for this run (max ${String(MAX_EXECUTION_IMAGES)} images). Work with the images already shown.`,
+                    },
+                ],
+                isError: true,
+            };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        path: result.path,
+                        mimeType: result.image.mimeType,
+                        bytes: result.image.bytes,
+                    }),
+                },
+                {
+                    type: "image",
+                    data: result.image.data,
+                    mimeType: result.image.mimeType,
+                },
+            ],
+            isError: false,
+        };
+    };
+}
 /** Present the very same Files operation and decoder used behind execute. */
-function readOnlyTool(name, description, inputSchema, outputSchema, invoke) {
+function readOnlyTool(name, description, inputSchema, outputSchema, invoke, present = (result) => ({
+    content: [{ type: "text", text: JSON.stringify(result) }],
+    isError: false,
+})) {
     const readOnly = {
         [fileToolBrand]: true,
         module: filesModuleId,
@@ -407,7 +496,8 @@ function readOnlyTool(name, description, inputSchema, outputSchema, invoke) {
         descriptor: {
             name,
             description,
-            parameters: z.toJSONSchema(inputSchema),
+            // Input side: defaulted fields are optional for the model.
+            parameters: toolParameters(inputSchema),
         },
         executionMode: "sequential",
         prepare: (call) => Effect.try({
@@ -419,13 +509,7 @@ function readOnlyTool(name, description, inputSchema, outputSchema, invoke) {
             execute: () => Stream.fromEffect(runFileOperation(async (context) => outputSchema.parse(await invoke(value, context))).pipe(Effect.map((result) => ({
                 type: "result",
                 result: {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify(result),
-                        },
-                    ],
-                    isError: false,
+                    ...present(result),
                 },
             })))),
         }))),
@@ -441,38 +525,40 @@ export function files(input) {
     const invokePatch = patch === undefined
         ? undefined
         : async (value, context) => patchOutputSchema.parse(await patch(patchInputSchema.parse(value), context));
+    /** Images the direct `read` tool has shown in this Files surface's run. */
+    let directImages = 0;
     const operations = {
         read: Mycelium.operation({
             replay: "safe",
             access: "read",
             input: readInputSchema,
-            output: readOutputSchema,
-            description: describe("Read one bounded UTF-8 file page."),
-            execute: async (operationInput, context) => input.port.read(operationInput, context),
+            output: readGuestOutputSchema,
+            description: describe(readDescription),
+            execute: async (operationInput, context) => presentReadForGuest(await input.port.read(operationInput, context), context),
         }),
         list: Mycelium.operation({
             replay: "safe",
             access: "read",
             input: listInputSchema,
-            output: listOutputSchema,
-            description: describe("List one bounded directory level."),
-            execute: async (operationInput, context) => input.port.list(operationInput, context),
+            output: searchOutputSchema,
+            description: describe(searchDescriptions.list),
+            execute: async (operationInput, context) => capFoundLines(await input.port.list(operationInput, context)),
         }),
         glob: Mycelium.operation({
             replay: "safe",
             access: "read",
             input: globInputSchema,
-            output: globOutputSchema,
-            description: describe("Find bounded paths by pattern."),
-            execute: async (operationInput, context) => input.port.glob(operationInput, context),
+            output: searchOutputSchema,
+            description: describe(searchDescriptions.glob),
+            execute: async (operationInput, context) => capFoundLines(await input.port.glob(operationInput, context)),
         }),
         grep: Mycelium.operation({
             replay: "safe",
             access: "read",
             input: grepInputSchema,
-            output: grepOutputSchema,
-            description: describe("Search bounded file content."),
-            execute: async (operationInput, context) => input.port.grep(operationInput, context),
+            output: searchOutputSchema,
+            description: describe(searchDescriptions.grep),
+            execute: async (operationInput, context) => capFoundLines(await input.port.grep(operationInput, context)),
         }),
         edit: Mycelium.operation({
             replay: "unsafe",
@@ -496,10 +582,10 @@ export function files(input) {
     return Object.freeze({
         tools: Object.freeze([
             ...(invokePatch === undefined ? [] : [patchTool(invokePatch)]),
-            readOnlyTool("read", describe("Read one bounded UTF-8 file page."), readInputSchema, readOutputSchema, input.port.read),
-            readOnlyTool("list", describe("List one bounded directory level."), listInputSchema, listOutputSchema, input.port.list),
-            readOnlyTool("glob", describe("Find bounded paths by pattern."), globInputSchema, globOutputSchema, input.port.glob),
-            readOnlyTool("grep", describe("Search bounded file content."), grepInputSchema, grepOutputSchema, input.port.grep),
+            readOnlyTool("read", describe(readDescription), readInputSchema, readOutputSchema, input.port.read, presentRead(() => (directImages += 1) <= MAX_EXECUTION_IMAGES)),
+            readOnlyTool("list", describe(searchDescriptions.list), listInputSchema, searchOutputSchema, async (value, context) => capFoundLines(await input.port.list(value, context)), presentSearch),
+            readOnlyTool("glob", describe(searchDescriptions.glob), globInputSchema, searchOutputSchema, async (value, context) => capFoundLines(await input.port.glob(value, context)), presentSearch),
+            readOnlyTool("grep", describe(searchDescriptions.grep), grepInputSchema, searchOutputSchema, async (value, context) => capFoundLines(await input.port.grep(value, context)), presentSearch),
         ]),
         module: Mycelium.module({
             id: filesModuleId,

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { type CapabilitySource, type InvocationContext, type MyceliumJsonValue } from "@fungi.computer/mycelium";
 import { files, type FilesConnectionOptions } from "./files.js";
 import { mcpServers } from "./mcp.js";
+import { ui } from "./ui.js";
 /** Generic advertised-call interface supplied by one Computer provider. */
 export type KnapsackComputer = Readonly<{
     /** Knapsack stops waiting when `signal` aborts, whether or not the provider honours it. */
@@ -65,6 +66,9 @@ export declare const Knapsack: Readonly<{
     files: typeof files;
     /** Connect a changing list of remote MCP servers, reporting unavailable ones independently. */
     mcpServers: typeof mcpServers;
+    /** Connect the open App's live Whistle commands to each Agent Session. */
+    ui: typeof ui;
 }>;
+export type { UiConnection, UiConnectionOptions } from "./ui.js";
 export { McpServerUnavailableError, type McpServerConnection, type McpServerUnavailableReason, type McpServersConnectionOptions, } from "./mcp.js";
-export { FilesEditError, filesEditFailureSchema, type FilesEditErrorReason, type FilesConnectionOptions, type FilesPort, type FilesPatch, type FilesSurface, edit, readInputSchema, readOutputSchema, listInputSchema, listOutputSchema, globInputSchema, globOutputSchema, grepInputSchema, grepOutputSchema, editInputSchema, editOutputSchema, patchInputSchema, patchOutputSchema, type FileTool, type FileToolName, } from "./files.js";
+export { FilesEditError, filesEditFailureSchema, type FilesEditErrorReason, type FilesConnectionOptions, type FilesPort, type FilesPatch, type FilesSurface, edit, readInputSchema, readOutputSchema, listInputSchema, globInputSchema, grepInputSchema, searchOutputSchema, readGuestOutputSchema, presentReadForGuest, editInputSchema, editOutputSchema, patchInputSchema, patchOutputSchema, type FileTool, type FileToolName, } from "./files.js";

package/dist/index.js

@@ -4,6 +4,7 @@ import * as Result from "effect/Result";
 import { z } from "zod";
 import { files } from "./files.js";
 import { mcpServers } from "./mcp.js";
+import { ui } from "./ui.js";
 const maximumCapabilities = 256;
 const describeConcurrency = 8;
 const defaultDescribeTimeoutMillis = 10_000;
@@ -173,6 +174,8 @@ export const Knapsack = Object.freeze({
     files,
     /** Connect a changing list of remote MCP servers, reporting unavailable ones independently. */
     mcpServers,
+    /** Connect the open App's live Whistle commands to each Agent Session. */
+    ui,
 });
 export { McpServerUnavailableError, } from "./mcp.js";
-export { FilesEditError, filesEditFailureSchema, edit, readInputSchema, readOutputSchema, listInputSchema, listOutputSchema, globInputSchema, globOutputSchema, grepInputSchema, grepOutputSchema, editInputSchema, editOutputSchema, patchInputSchema, patchOutputSchema, } from "./files.js";
+export { FilesEditError, filesEditFailureSchema, edit, readInputSchema, readOutputSchema, listInputSchema, globInputSchema, grepInputSchema, searchOutputSchema, readGuestOutputSchema, presentReadForGuest, editInputSchema, editOutputSchema, patchInputSchema, patchOutputSchema, } from "./files.js";

package/dist/ui/browser.d.ts

@@ -0,0 +1,44 @@
+import type { WhistleRuntime } from "@fungi.computer/whistle";
+import * as Effect from "effect/Effect";
+import * as Scope from "effect/Scope";
+import { type BrowserRequestEnvelope, type BrowserResultEnvelope } from "./wire.js";
+/** Browser-side platform failure before a correlated result is accepted. */
+export declare class UiBrowserError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** One Agent Session's browser transport and the App's command runtime. */
+export type BrowserConnectionOptions = Readonly<{
+    /** Session route that serves `/browser/{events,claims,results}`. */
+    baseUrl: string;
+    /** The App shell's Whistle runtime; its agent projection is what the Agent sees. */
+    whistle: Pick<WhistleRuntime, "snapshot" | "execute">;
+    /** Host-authorized I/O; omitted for ordinary browser Fetch and EventSource. */
+    transport?: Readonly<{
+        /** Send claims and results with the host's existing admission. */
+        fetch: typeof globalThis.fetch;
+        /** Open the event stream with that same admission and a maintained SSE client. */
+        openEvents: (url: string) => EventTarget & {
+            /** Stop this connection's event stream when its owning scope closes. */
+            close(): void;
+        };
+    }>;
+}>;
+/** A live browser connection; close it when the selected Session changes. */
+export type BrowserConnection = Readonly<{
+    /** Settles when the connection ends; rejects with {@link UiBrowserError} on failure. */
+    closed: Promise<void>;
+    /** Stop serving the Agent's requests. */
+    close: () => void;
+}>;
+/**
+ * Execute one claimed browser request through Whistle's single door.
+ *
+ * Claim is the dispatch point: the browser request carries no cancellation, so
+ * Whistle supplies its own never-aborted signal, and cancellation after this
+ * function starts cannot promise to undo a side effect.
+ */
+export declare function handleBrowserRequest(options: BrowserConnectionOptions, envelope: BrowserRequestEnvelope): Effect.Effect<Omit<BrowserResultEnvelope, "claimId">, UiBrowserError>;
+/** Run one scope-owned EventSource connection and its Whistle request loop. */
+export declare function runBrowserConnection(options: BrowserConnectionOptions): Effect.Effect<void, UiBrowserError, Scope.Scope>;
+/** Start the named browser Promise facade over the Effect connection program. */
+export declare function connectBrowser(options: BrowserConnectionOptions): BrowserConnection;

package/dist/ui/browser.js

@@ -0,0 +1,171 @@
+import * as Effect from "effect/Effect";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as z from "zod";
+import { BrowserClaimResultSchema, BrowserCommandRowSchema, BrowserRequestDeliverySchema, BrowserSettlementResultSchema, } from "./wire.js";
+import { uiWireIds, BrowserExecutionOutcomeSchema } from "./wire.js";
+/** Browser-side platform failure before a correlated result is accepted. */
+export class UiBrowserError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "UiBrowserError";
+    }
+}
+const decodeRequestEvent = (input) => Effect.try(() => BrowserRequestDeliverySchema.parse(JSON.parse(z.string().parse(input))));
+const decodeClaimResult = (input) => Effect.try(() => BrowserClaimResultSchema.parse(input));
+const decodeSettlementResult = (input) => Effect.try(() => BrowserSettlementResultSchema.parse(input));
+function requestEventData(event) {
+    return event instanceof MessageEvent
+        ? Effect.try(() => z.string().parse(event.data)).pipe(Effect.mapError(() => new UiBrowserError("Browser request event is invalid")))
+        : Effect.fail(new UiBrowserError("Browser request event is invalid"));
+}
+function projectCommands(whistle) {
+    return Effect.sync(() => BrowserCommandRowSchema.array().parse(whistle.snapshot().agent.map((row) => {
+        const sourceAction = row.action;
+        // Focus scope belongs to the local command graph, not the browser wire.
+        const projected = {
+            commandId: row.commandId,
+            sourceId: row.sourceId,
+            title: row.title,
+            category: row.category,
+            description: row.description ?? null,
+            order: row.order,
+            keybind: row.keybind ?? null,
+            availability: row.availability,
+        };
+        if (sourceAction === undefined)
+            return projected;
+        const action = {};
+        if (sourceAction.inputSchema !== undefined)
+            action.inputSchema = sourceAction.inputSchema;
+        if (sourceAction.outputSchema !== undefined)
+            action.outputSchema = sourceAction.outputSchema;
+        if (action.inputSchema === undefined &&
+            action.outputSchema === undefined)
+            return projected;
+        return { ...projected, action };
+    })));
+}
+function projectOutcome(outcome) {
+    const parsed = BrowserExecutionOutcomeSchema.safeParse(outcome);
+    return {
+        type: "execute",
+        outcome: parsed.success
+            ? parsed.data
+            : {
+                status: "failed",
+                error: {
+                    code: "invalid_command_result",
+                    message: "Command result is not valid JSON data",
+                },
+            },
+    };
+}
+/**
+ * Execute one claimed browser request through Whistle's single door.
+ *
+ * Claim is the dispatch point: the browser request carries no cancellation, so
+ * Whistle supplies its own never-aborted signal, and cancellation after this
+ * function starts cannot promise to undo a side effect.
+ */
+export function handleBrowserRequest(options, envelope) {
+    if (envelope.request.type === "discover")
+        return projectCommands(options.whistle).pipe(Effect.map((commands) => ({
+            requestId: envelope.requestId,
+            result: { type: "discover", commands },
+        })));
+    const commandId = envelope.request.commandId;
+    const argumentsValue = "arguments" in envelope.request ? envelope.request.arguments : undefined;
+    return Effect.tryPromise({
+        try: () => options.whistle.execute(commandId, argumentsValue === undefined
+            ? { origin: "agent" }
+            : { origin: "agent", arguments: argumentsValue }),
+        catch: () => new UiBrowserError("Whistle execution rejected"),
+    }).pipe(Effect.map((outcome) => ({
+        requestId: envelope.requestId,
+        result: projectOutcome(outcome),
+    })));
+}
+function claimRequest(options, delivery) {
+    const attemptId = uiWireIds.attempt.generate();
+    const claimOnce = () => Effect.tryPromise({
+        try: (signal) => (options.transport?.fetch ?? globalThis.fetch)(`${options.baseUrl}/browser/claims`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                attemptId,
+                connectionId: delivery.connectionId,
+                requestId: delivery.requestId,
+            }),
+            signal,
+        }),
+        catch: () => new UiBrowserError("Browser claim request failed"),
+    }).pipe(Effect.flatMap((response) => response.ok
+        ? Effect.tryPromise({
+            try: () => response.json(),
+            catch: () => new UiBrowserError("Browser claim response is invalid"),
+        })
+        : Effect.fail(new UiBrowserError(`Browser claim was rejected with status ${String(response.status)}`))), Effect.flatMap((input) => Effect.try(() => z.record(z.string(), z.unknown()).parse(input)).pipe(Effect.flatMap(decodeClaimResult))), Effect.mapError(() => new UiBrowserError("Browser claim response is invalid")));
+    const waitForClaim = () => claimOnce().pipe(Effect.flatMap((claim) => claim.status === "waiting"
+        ? Effect.sleep(claim.retryAfterMs).pipe(Effect.andThen(Effect.suspend(waitForClaim)))
+        : Effect.succeed(claim)));
+    return Effect.suspend(waitForClaim);
+}
+function postResult(options, result) {
+    return Effect.tryPromise({
+        try: (signal) => (options.transport?.fetch ?? globalThis.fetch)(`${options.baseUrl}/browser/results`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(result),
+            signal,
+        }),
+        catch: () => new UiBrowserError("Browser result request failed"),
+    }).pipe(Effect.flatMap((response) => response.ok
+        ? Effect.tryPromise({
+            try: () => response.json(),
+            catch: () => new UiBrowserError("Browser settlement response is invalid"),
+        }).pipe(Effect.flatMap((input) => Effect.try(() => z.record(z.string(), z.unknown()).parse(input)).pipe(Effect.flatMap(decodeSettlementResult))), Effect.mapError(() => new UiBrowserError("Browser settlement response is invalid")), Effect.asVoid)
+        : Effect.fail(new UiBrowserError(`Browser result was rejected with status ${String(response.status)}`))));
+}
+function handleRequestEvent(options, event) {
+    return requestEventData(event).pipe(Effect.flatMap(decodeRequestEvent), Effect.mapError(() => new UiBrowserError("Browser request payload is invalid")), Effect.flatMap((delivery) => claimRequest(options, delivery).pipe(Effect.flatMap((claim) => claim.status !== "claimed"
+        ? Effect.void
+        : handleBrowserRequest(options, delivery).pipe(Effect.flatMap((result) => postResult(options, {
+            ...result,
+            claimId: claim.claimId,
+        })))))));
+}
+/** Run one scope-owned EventSource connection and its Whistle request loop. */
+export function runBrowserConnection(options) {
+    return Effect.acquireRelease(Effect.try({
+        try: () => {
+            const url = `${options.baseUrl}/browser/events`;
+            return options.transport === undefined
+                ? new EventSource(url)
+                : options.transport.openEvents(url);
+        },
+        catch: () => new UiBrowserError("Browser event stream could not open"),
+    }), (source) => Effect.sync(() => {
+        source.close();
+    })).pipe(Effect.flatMap((source) => Stream.fromEventListener(source, "browser-request", {
+        bufferSize: 1,
+    }).pipe(Stream.mapEffect((event) => handleRequestEvent(options, event)), Stream.runDrain)));
+}
+/** Start the named browser Promise facade over the Effect connection program. */
+export function connectBrowser(options) {
+    const cancellation = new AbortController();
+    const closed = Effect.runPromise(Effect.scoped(runBrowserConnection(options)), {
+        signal: cancellation.signal,
+    }).catch((cause) => {
+        if (!cancellation.signal.aborted)
+            throw new UiBrowserError("Browser connection failed", {
+                cause,
+            });
+    });
+    return Object.freeze({
+        closed,
+        close: () => {
+            cancellation.abort();
+        },
+    });
+}