@fungi.computer/knapsack 0.0.2 → 0.2.0

package/dist/ui/wire.js

@@ -0,0 +1,136 @@
+import { defineIdFamily } from "@fungi.computer/cairn";
+import * as z from "zod";
+export const uiWireIds = defineIdFamily({
+    family: "knapsack-ui",
+    version: 1,
+    kinds: {
+        request: { prefix: "ui_request" },
+        connection: { prefix: "ui_connection" },
+        claim: { prefix: "ui_claim" },
+        attempt: { prefix: "ui_attempt" },
+    },
+});
+const identifier = z.string().min(1).max(256);
+const requestId = z
+    .string()
+    .refine((value) => uiWireIds.request.parse(value).ok);
+const json = z.json();
+const schemaDocument = z.record(z.string(), json);
+export const BrowserWireObjectSchema = z.record(z.string(), z.unknown());
+const WhistleAvailabilitySchema = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("available") }),
+    z.object({ status: z.literal("unavailable"), reason: z.string() }),
+]);
+/** The same descriptor is decoded at browser ingress and in model tool results. */
+const browserCommandRowFields = {
+    commandId: identifier,
+    sourceId: identifier,
+    title: z.string(),
+    category: z.string(),
+    description: z.string().nullable(),
+    order: z.number(),
+    keybind: z.string().nullable(),
+    availability: WhistleAvailabilitySchema,
+};
+const browserActionSchema = z.union([
+    z
+        .object({ inputSchema: schemaDocument, outputSchema: schemaDocument })
+        .strict(),
+    z.object({ inputSchema: schemaDocument }).strict(),
+    z.object({ outputSchema: schemaDocument }).strict(),
+]);
+const browserCommandRowWithActionSchema = z
+    .object({ ...browserCommandRowFields, action: browserActionSchema })
+    .strict();
+const browserCommandRowWithoutActionSchema = z
+    .object(browserCommandRowFields)
+    .strict();
+export const BrowserCommandRowSchema = z.union([
+    browserCommandRowWithActionSchema,
+    browserCommandRowWithoutActionSchema,
+]);
+const browserExecuteCommandSchema = z.object({
+    commandId: z.string().max(256),
+});
+const browserExecuteInputWireSchema = browserExecuteCommandSchema
+    .extend({ arguments: json })
+    .strict();
+const browserExecuteInputWithoutArgumentsSchema = browserExecuteCommandSchema.strict();
+export const BrowserExecuteInputSchema = z.union([
+    browserExecuteInputWireSchema,
+    browserExecuteInputWithoutArgumentsSchema,
+]);
+const BrowserRequestSchema = z.union([
+    z.object({ type: z.literal("discover") }).strict(),
+    browserExecuteInputWireSchema.extend({ type: z.literal("execute") }),
+    browserExecuteInputWithoutArgumentsSchema.extend({
+        type: z.literal("execute"),
+    }),
+]);
+const BrowserRequestEnvelopeSchema = z.object({
+    requestId,
+    request: BrowserRequestSchema,
+});
+export const BrowserRequestDeliverySchema = BrowserRequestEnvelopeSchema.extend({
+    connectionId: z
+        .string()
+        .refine((value) => uiWireIds.connection.parse(value).ok),
+});
+export const BrowserClaimSchema = z.object({
+    requestId,
+    connectionId: z
+        .string()
+        .refine((value) => uiWireIds.connection.parse(value).ok),
+    attemptId: z.string().refine((value) => uiWireIds.attempt.parse(value).ok),
+});
+export const BrowserClaimResultSchema = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("claimed"), claimId: z.string() }),
+    z.object({
+        status: z.literal("waiting"),
+        retryAfterMs: z.number().int().min(10).max(1_000),
+    }),
+    z.object({ status: z.literal("skipped") }),
+]);
+export const BrowserExecutionOutcomeSchema = z.union([
+    z.object({ status: z.literal("handled"), result: json }).strict(),
+    z.object({ status: z.literal("handled") }).strict(),
+    z.object({ status: z.literal("closed") }).strict(),
+    z.object({ status: z.literal("missing") }).strict(),
+    z.object({ status: z.literal("invalid") }).strict(),
+    z.object({ status: z.literal("unavailable"), reason: z.string() }).strict(),
+    z
+        .object({
+        status: z.literal("failed"),
+        error: z.object({
+            code: z.string(),
+            message: z.string(),
+            details: json,
+        }),
+    })
+        .strict(),
+    z
+        .object({
+        status: z.literal("failed"),
+        error: z.object({ code: z.string(), message: z.string() }).strict(),
+    })
+        .strict(),
+]);
+const BrowserWireResultSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("discover"),
+        commands: z.array(BrowserCommandRowSchema),
+    }),
+    z.object({
+        type: z.literal("execute"),
+        outcome: BrowserExecutionOutcomeSchema,
+    }),
+]);
+export const BrowserResultEnvelopeSchema = z.object({
+    requestId,
+    claimId: z.string().refine((value) => uiWireIds.claim.parse(value).ok),
+    result: BrowserWireResultSchema,
+});
+export const BrowserSettlementResultSchema = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("accepted") }),
+    z.object({ status: z.literal("ignored") }),
+]);

package/dist/ui-browser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Browser side of Knapsack.ui: connect the App's Whistle runtime to one Agent
+ * Session's `/browser/*` transport so the Agent can discover and run its
+ * live commands.
+ */
+export { connectBrowser, UiBrowserError, type BrowserConnection, type BrowserConnectionOptions, } from "./ui/browser.js";

package/dist/ui-browser.js

@@ -0,0 +1,6 @@
+/**
+ * Browser side of Knapsack.ui: connect the App's Whistle runtime to one Agent
+ * Session's `/browser/*` transport so the Agent can discover and run its
+ * live commands.
+ */
+export { connectBrowser, UiBrowserError, } from "./ui/browser.js";

package/dist/ui.d.ts

@@ -0,0 +1,29 @@
+import type { CapabilitySource } from "@fungi.computer/mycelium";
+/** How one Agent host connects its Sessions' open Apps to Knapsack.ui. */
+export type UiConnectionOptions = Readonly<{
+    /** Stable, secret-free capability source id, such as `"hub-ui"`. */
+    id: string;
+    /** Whether the Session is stored; only a stored Session's browser may connect. */
+    hasSession: (sessionId: string) => Promise<boolean>;
+}>;
+/**
+ * Live commands of the App open in each Agent Session's browser. The Agent
+ * reaches them through the `ui` module (`ui.discover`, `ui.execute`); the
+ * browser runs them through Whistle over the transport this connection serves.
+ */
+export type UiConnection = Readonly<{
+    /**
+     * Each Session run borrows its Session's `ui` module and releases it when
+     * the run ends. A Session-free acquisition contributes no module.
+     */
+    source: CapabilitySource;
+    /**
+     * Serve `/browser/sessions/<sessionId>/browser/{events,claims,results}`.
+     * It authenticates nobody: mount it behind the host's own authorization.
+     */
+    fetch: (request: Request) => Promise<Response>;
+    /** End every browser stream; later requests answer 410 and later borrows fail. */
+    close: () => Promise<void>;
+}>;
+/** Connect the open App's live Whistle commands to each Agent Session. */
+export declare function ui(options: UiConnectionOptions): UiConnection;

package/dist/ui.js

@@ -0,0 +1,35 @@
+import { createUiHost } from "./ui/host.js";
+import { BrowserSessions } from "./ui/sessions.js";
+/** Borrow one Session's `ui` module for the acquiring run. */
+function borrow(sessions, context) {
+    context.signal.throwIfAborted();
+    if (context.session === undefined)
+        return {
+            snapshot: { version: "no-session", modules: [] },
+            release: () => Promise.resolve(),
+        };
+    const sessionId = context.session.sessionId;
+    const lease = sessions.acquire(sessionId);
+    return {
+        snapshot: { version: `session:${sessionId}`, modules: lease.modules },
+        release: () => {
+            lease.release();
+            return Promise.resolve();
+        },
+    };
+}
+/** Connect the open App's live Whistle commands to each Agent Session. */
+export function ui(options) {
+    const sessions = new BrowserSessions(() => createUiHost(), options.hasSession);
+    return Object.freeze({
+        source: {
+            id: options.id,
+            // The executor turns a refused borrow (aborted, or closed) into a rejection.
+            acquire: (context) => new Promise((resolve) => {
+                resolve(borrow(sessions, context));
+            }),
+        },
+        fetch: (request) => sessions.fetch(request),
+        close: () => sessions.close(),
+    });
+}

package/docs/api/README.md

@@ -15,3 +15,4 @@
 | [files-read](files-read.md)             | -           |
 | [index](index.md)                       | -           |
 | [patch](patch.md)                       | -           |
+| [ui-browser](ui-browser.md)             | -           |

package/docs/api/files-patch.md

@@ -13,11 +13,13 @@
 ### patchInputSchema
 
 ```ts
-const patchInputSchema: ZodObject<
-  {
-    patch: ZodString;
-  },
-  $strict
+const patchInputSchema: ZodLazy<
+  ZodObject<
+    {
+      patch: ZodString;
+    },
+    $strict
+  >
 >;
 ```
 
@@ -28,44 +30,38 @@ Browser-safe patch contracts shared by native Files tools and Computer HTTP.
 ### patchOutputSchema
 
 ```ts
-const patchOutputSchema: ZodUnion<
-  readonly [
-    ZodObject<
-      {
-        status: ZodEnum<{
-          completed: "completed";
-          failed: "failed";
-          cancelled: "cancelled";
-        }>;
-        exitCode: ZodNumber;
-        stdout: ZodString;
-        stderr: ZodString;
-        truncated: ZodBoolean;
-      },
-      $strict
-    >,
-    ZodObject<
-      {
-        status: ZodEnum<{
-          completed: "completed";
-          failed: "failed";
-          cancelled: "cancelled";
-        }>;
-        exitCode: ZodNumber;
-        stdout: ZodString;
-        stderr: ZodString;
-        truncated: ZodBoolean;
-        error: ZodObject<
-          {
-            kind: ZodLiteral<"mismatch">;
-          },
-          $strict
-        >;
-      },
-      $strict
-    >,
-  ]
->;
+const patchOutputSchema: ZodLazy<ZodUnion<readonly [ZodObject<{
+  status: ZodEnum<{
+     completed: "completed";
+     failed: "failed";
+     cancelled: "cancelled";
+  }>;
+  exitCode: ZodNumber;
+  stdout: ZodString;
+  stderr: ZodString;
+  truncated: ZodUnion<readonly [ZodLiteral<false>, ZodArray<ZodObject<{
+     stream: ZodEnum<...>;
+     keptBytes: ZodNumber;
+     totalBytes: ZodNumber;
+  }, $strict>>]>;
+}, $strict>, ZodObject<{
+  status: ZodEnum<{
+     completed: "completed";
+     failed: "failed";
+     cancelled: "cancelled";
+  }>;
+  exitCode: ZodNumber;
+  stdout: ZodString;
+  stderr: ZodString;
+  truncated: ZodUnion<readonly [ZodLiteral<false>, ZodArray<ZodObject<{
+     stream: ZodEnum<...>;
+     keptBytes: ZodNumber;
+     totalBytes: ZodNumber;
+  }, $strict>>]>;
+  error: ZodObject<{
+     kind: ZodLiteral<"mismatch">;
+  }, $strict>;
+}, $strict>]>>;
 ```
 
 Native patch completion, cancellation or failure, including an optional

package/docs/api/files-read.md

@@ -20,10 +20,31 @@ Maximum UTF-8 byte length of a Files text page.
 
 ---
 
+### maximumImageBytes
+
+```ts
+const maximumImageBytes: number;
+```
+
+Maximum byte length of an image the read tool returns; a host refuses an image
+it cannot bring within it.
+
+---
+
+### imageSniffBytes
+
+```ts
+const imageSniffBytes: 12 = 12;
+```
+
+Bytes needed at the start of a file to recognise a supported image.
+
+---
+
 ### pathSchema
 
 ```ts
-const pathSchema: ZodString;
+const pathSchema: ZodLazy<ZodString>;
 ```
 
 Nonempty file path bounded to 4,096 characters, without null bytes.
@@ -33,13 +54,15 @@ Nonempty file path bounded to 4,096 characters, without null bytes.
 ### readInputSchema
 
 ```ts
-const readInputSchema: ZodObject<
-  {
-    path: ZodString;
-    offset: ZodDefault<ZodNumber>;
-    limit: ZodDefault<ZodNumber>;
-  },
-  $strict
+const readInputSchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodLazy<ZodString>;
+      offset: ZodDefault<ZodNumber>;
+      limit: ZodDefault<ZodNumber>;
+    },
+    $strict
+  >
 >;
 ```
 
@@ -47,34 +70,214 @@ Canonical bounded Files read request and result, shared with display consumers.
 
 ---
 
-### readOutputSchema
+### readImageMimeType
+
+```ts
+const readImageMimeType: ZodEnum<{
+  image/png: "image/png";
+  image/jpeg: "image/jpeg";
+  image/gif: "image/gif";
+  image/webp: "image/webp";
+}>;
+```
+
+The image types a Files read can return.
+
+---
+
+### readImageOutputSchema
+
+```ts
+const readImageOutputSchema: ZodLazy<ZodObject<{
+  path: ZodLazy<ZodString>;
+  image: ZodObject<{
+     mimeType: ZodEnum<{
+        image/png: "image/png";
+        image/jpeg: "image/jpeg";
+        image/gif: "image/gif";
+        image/webp: "image/webp";
+     }>;
+     data: ZodBase64;
+     bytes: ZodNumber;
+  }, $strict>;
+  file: ZodExactOptional<ZodLazy<ZodObject<{
+     computerId: ZodString;
+     path: ZodLazy<ZodString>;
+  }, $strict>>>;
+}, $strict>>;
+```
+
+Whole png, jpeg, gif or webp file, at most `maximumImageBytes`, as base64.
+
+---
+
+### readTextOutputSchema
 
 ```ts
-const readOutputSchema: ZodObject<
-  {
-    path: ZodString;
-    content: ZodString;
-    offset: ZodNumber;
-    nextOffset: ZodNullable<ZodNumber>;
-    truncated: ZodBoolean;
-    file: ZodExactOptional<
-      ZodObject<
-        {
-          computerId: ZodString;
-          path: ZodString;
-        },
-        $strict
-      >
-    >;
-  },
-  $strict
+const readTextOutputSchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodLazy<ZodString>;
+      content: ZodString;
+      offset: ZodNumber;
+      nextOffset: ZodNullable<ZodNumber>;
+      truncated: ZodBoolean;
+      file: ZodExactOptional<
+        ZodLazy<
+          ZodObject<
+            {
+              computerId: ZodString;
+              path: ZodLazy<ZodString>;
+            },
+            $strict
+          >
+        >
+      >;
+    },
+    $strict
+  >
 >;
 ```
 
 Bounded text page, continuation offset and optional hosted file identity.
 
+---
+
+### readImageCaptionSchema
+
+```ts
+const readImageCaptionSchema: ZodLazy<ZodObject<{
+  path: ZodLazy<ZodString>;
+  image: ZodObject<{
+     ref: ZodString;
+     mimeType: ZodEnum<{
+        image/png: "image/png";
+        image/jpeg: "image/jpeg";
+        image/gif: "image/gif";
+        image/webp: "image/webp";
+     }>;
+     bytes: ZodNumber;
+  }, $strict>;
+}, $strict>>;
+```
+
+What guest code and MCP callers see: an image never travels as base64 in the
+value. It is pushed through the execution's image collector and the value is
+only this caption.
+
+---
+
+### readGuestOutputSchema
+
+```ts
+const readGuestOutputSchema: ZodLazy<ZodUnion<readonly [ZodLazy<ZodObject<{
+  path: ZodLazy<ZodString>;
+  content: ZodString;
+  offset: ZodNumber;
+  nextOffset: ZodNullable<ZodNumber>;
+  truncated: ZodBoolean;
+  file: ZodExactOptional<ZodLazy<ZodObject<{
+     computerId: ZodString;
+     path: ZodLazy<...>;
+  }, $strict>>>;
+}, $strict>>, ZodLazy<ZodObject<{
+  path: ZodLazy<ZodString>;
+  image: ZodObject<{
+     ref: ZodString;
+     mimeType: ZodEnum<{
+        image/png: "image/png";
+        image/jpeg: "image/jpeg";
+        image/gif: "image/gif";
+        image/webp: "image/webp";
+     }>;
+     bytes: ZodNumber;
+  }, $strict>;
+}, $strict>>]>>;
+```
+
+Text page or image caption returned to guest code.
+
+---
+
+### readOutputSchema
+
+```ts
+const readOutputSchema: ZodLazy<ZodUnion<readonly [ZodLazy<ZodObject<{
+  path: ZodLazy<ZodString>;
+  content: ZodString;
+  offset: ZodNumber;
+  nextOffset: ZodNullable<ZodNumber>;
+  truncated: ZodBoolean;
+  file: ZodExactOptional<ZodLazy<ZodObject<{
+     computerId: ZodString;
+     path: ZodLazy<...>;
+  }, $strict>>>;
+}, $strict>>, ZodLazy<ZodObject<{
+  path: ZodLazy<ZodString>;
+  image: ZodObject<{
+     mimeType: ZodEnum<{
+        image/png: "image/png";
+        image/jpeg: "image/jpeg";
+        image/gif: "image/gif";
+        image/webp: "image/webp";
+     }>;
+     data: ZodBase64;
+     bytes: ZodNumber;
+  }, $strict>;
+  file: ZodExactOptional<ZodLazy<ZodObject<{
+     computerId: ZodString;
+     path: ZodLazy<...>;
+  }, $strict>>>;
+}, $strict>>]>>;
+```
+
+A bounded text page or a whole image; images are only read from offset 0.
+
 ## Functions
 
+### sniffImageMimeType()
+
+```ts
+function sniffImageMimeType(head): string | undefined;
+```
+
+Identify png, jpeg, gif or webp by their full magic bytes; `undefined` means not
+a supported image.
+
+#### Parameters
+
+| Parameter | Type         |
+| --------- | ------------ |
+| `head`    | `Uint8Array` |
+
+#### Returns
+
+`string` \| `undefined`
+
+---
+
+### imageTooLargeMessage()
+
+```ts
+function imageTooLargeMessage(path, size, limit): string;
+```
+
+Message for an image above a host's read cap, shared by every Files host.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+| `size`    | `number` |
+| `limit`   | `number` |
+
+#### Returns
+
+`string`
+
+---
+
 ### boundedTextSchema()
 
 ```ts
@@ -92,3 +295,36 @@ Validate text against a minimum character length and the Files UTF-8 byte limit.
 #### Returns
 
 `ZodString`
+
+---
+
+### imageReadResult()
+
+```ts
+function imageReadResult(path, mimeType, bytes): object;
+```
+
+Build the image read result for a recognised image's complete bytes.
+
+#### Parameters
+
+| Parameter  | Type         |
+| ---------- | ------------ |
+| `path`     | `string`     |
+| `mimeType` | `string`     |
+| `bytes`    | `Uint8Array` |
+
+#### Returns
+
+`object`
+
+| Name              | Type                                                               | Default value       |
+| ----------------- | ------------------------------------------------------------------ | ------------------- |
+| `path`            | `string`                                                           | `pathSchema`        |
+| `image`           | `object`                                                           | -                   |
+| `image.mimeType`  | `"image/png"` \| `"image/jpeg"` \| `"image/gif"` \| `"image/webp"` | `readImageMimeType` |
+| `image.data`      | `string`                                                           | -                   |
+| `image.bytes`     | `number`                                                           | -                   |
+| `file?`           | `object`                                                           | -                   |
+| `file.computerId` | `string`                                                           | -                   |
+| `file.path`       | `string`                                                           | -                   |