@fungi.computer/knapsack 0.1.0 → 0.2.0

package/README.md

@@ -36,6 +36,15 @@ catalog or a result. Servers connect concurrently under a timeout. One that
 rejects, refuses its credential, times out or advertises an unusable list is
 dropped and reported through `onUnavailable`, while the others stay available.
 
+`Knapsack.ui({ id, hasSession })` connects the App open in an Agent Session's
+browser. Its `source` lends each Session run the `ui` module: `ui.discover`
+lists the App's live Whistle commands (its agent projection) and `ui.execute`
+runs one. The run returns the module when it ends. Its `fetch` serves
+`/browser/sessions/<sessionId>/browser/{events,claims,results}`: the browser
+claims each request before it runs it, and the host accepts only the matching
+result. The browser side is `connectBrowser({ baseUrl, whistle })` from
+`@fungi.computer/knapsack/ui/browser`.
+
 Knapsack does not own model loops, tool execution policy, Computer storage, or
 provider-specific operations.
 
@@ -43,6 +52,13 @@ provider-specific operations.
 contracts without loading tool connections or the agent runtime. Browser and
 transport consumers use this subpath.
 
+`@fungi.computer/knapsack/files-search` supplies `SearchVisibility` to Local and
+hosted Files adapters. One invocation-local policy checks canonical
+root-relative search paths (the root and every entry), excludes `.git` path
+components and respects excluded ancestors. Adapters supply bounded ignore-file
+text; maintained `ignore` owns gitignore grammar and nested negation. Exact-path
+reads do not use search visibility.
+
 ## Set up
 
 ```sh
@@ -51,8 +67,9 @@ npm install @fungi.computer/knapsack
 
 The package is an ESM public candidate, not a claim of npm publication. It
 depends on Cairn, Forage, Mule, Mycelium, the MCP SDK client, Effect, Zod and
-`diff`. Its explicit file list contains compiled JavaScript and declarations,
-the API reference, this README and the license texts. It has no install scripts.
+`diff` and `ignore`. Its explicit file list contains compiled JavaScript and
+declarations, the API reference, this README and the license texts. It has no
+install scripts.
 
 ## Quick start: validate a read request
 
@@ -89,6 +106,12 @@ replace atomically or refuse a conflict. A native patch operation is available
 only when that port supplies a patch engine. Paths are validated, not confined
 by Knapsack: the captured host port enforces its own root and authority.
 
+`Knapsack.ui` keeps one browser host per Session, opened by the browser's event
+stream for a stored Session or by a run, and dropped when neither holds it.
+Neither its `fetch` nor the browser's requests are authenticated by Knapsack:
+mount `fetch` behind the host's own admission. `close()` ends every stream;
+later requests answer 410 and later runs fail to borrow.
+
 ## API reference
 
 The [generated reference](docs/api/README.md) covers every public entry:
@@ -100,6 +123,7 @@ The [generated reference](docs/api/README.md) covers every public entry:
 | `/files-read`       | Bounded text read schemas and shared path validation.                                       |
 | `/patch`            | Read Codex patch operations for presentation; the native engine validates and applies them. |
 | `/files-read-codec` | Encode read requests and adapt a framed host transport to the Files read port.              |
+| `/ui/browser`       | Connect an App's Whistle runtime to one Agent Session's `Knapsack.ui` transport.            |
 
 ## Examples and checks
 
@@ -107,8 +131,12 @@ The [generated reference](docs/api/README.md) covers every public entry:
 provider failures and invocation context. [Files tests](test/files.test.ts)
 exercise bounded reads and edits.
 [Read codec tests](test/files-read-codec.test.ts) exercise the framed transport.
-The packed-consumer runtime and typecheck fixtures import only the five public
-entries from an isolated tarball installation.
+[Knapsack.ui tests](test/ui.test.ts) exercise run borrows and teardown; the
+[host](test/ui-host.test.ts), [event stream](test/ui-eventsource.test.ts) and
+[Session host](test/ui-sessions.test.ts) tests cover discovery, execution,
+claims, disconnects and multi-tab delivery. The packed-consumer runtime and
+typecheck fixtures import the root and Files entries from an isolated tarball
+installation.
 
 From a configured repository checkout:
 
@@ -131,6 +159,11 @@ search results contain at most 256 entries and expose truncation. Schemas reject
 invalid requests and results. `FilesEditError` distinguishes conflicts, missing
 or ambiguous matches, oversized files and partial-character edits.
 
+One Session's browser serves one outstanding request: a second gets
+`browser_busy`, a missing browser `browser_not_connected`. If the browser
+disconnects after it claimed an execution, the result is
+`browser_execution_indeterminate`, because the command may already have run.
+
 ## Contribute and license
 
 Knapsack's package license is [MIT](LICENSE). The retained Codex patch grammar

package/dist/files-patch.d.ts

@@ -13,7 +13,14 @@ export declare const patchOutputSchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObje
     exitCode: z.ZodNumber;
     stdout: z.ZodString;
     stderr: z.ZodString;
-    truncated: z.ZodBoolean;
+    truncated: z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodObject<{
+        stream: z.ZodEnum<{
+            stdout: "stdout";
+            stderr: "stderr";
+        }>;
+        keptBytes: z.ZodNumber;
+        totalBytes: z.ZodNumber;
+    }, z.core.$strict>>]>;
 }, z.core.$strict>, z.ZodObject<{
     status: z.ZodEnum<{
         completed: "completed";
@@ -23,7 +30,14 @@ export declare const patchOutputSchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodObje
     exitCode: z.ZodNumber;
     stdout: z.ZodString;
     stderr: z.ZodString;
-    truncated: z.ZodBoolean;
+    truncated: z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodArray<z.ZodObject<{
+        stream: z.ZodEnum<{
+            stdout: "stdout";
+            stderr: "stderr";
+        }>;
+        keptBytes: z.ZodNumber;
+        totalBytes: z.ZodNumber;
+    }, z.core.$strict>>]>;
     error: z.ZodObject<{
         kind: z.ZodLiteral<"mismatch">;
     }, z.core.$strict>;

package/dist/files-patch.js

@@ -6,12 +6,19 @@ export const patchInputSchema = z.lazy(() => z.strictObject({
         description: `Codex patch text, at most ${String(maximumReadBytes)} UTF-8 bytes.`,
     }),
 }));
+/** One patch output stream cut at its byte bound; absent streams were whole. */
+const patchTruncationSchema = z.strictObject({
+    stream: z.enum(["stdout", "stderr"]),
+    keptBytes: z.number().int().nonnegative(),
+    totalBytes: z.number().int().positive(),
+});
 const patchResultSchema = z.strictObject({
     status: z.enum(["completed", "failed", "cancelled"]),
     exitCode: z.number().int(),
     stdout: z.string(),
     stderr: z.string(),
-    truncated: z.boolean(),
+    /** `false` when both streams are whole, else one entry per cut stream. */
+    truncated: z.union([z.literal(false), z.array(patchTruncationSchema).min(1)]),
 });
 /** Native patch completion, cancellation or failure, including an optional mismatch. */
 export const patchOutputSchema = z.lazy(() => z.union([

package/dist/files-read.d.ts

@@ -1,6 +1,14 @@
 import * as z from "zod";
 /** Maximum UTF-8 byte length of a Files text page. */
 export declare const maximumReadBytes: number;
+/** Maximum byte length of an image the read tool returns; a host refuses an image it cannot bring within it. */
+export declare const maximumImageBytes: number;
+/** Bytes needed at the start of a file to recognise a supported image. */
+export declare const imageSniffBytes = 12;
+/** Identify png, jpeg, gif or webp by their full magic bytes; `undefined` means not a supported image. */
+export declare function sniffImageMimeType(head: Uint8Array): string | undefined;
+/** Message for an image above a host's read cap, shared by every Files host. */
+export declare function imageTooLargeMessage(path: string, size: number, limit: number): string;
 /** Nonempty file path bounded to 4,096 characters, without null bytes. */
 export declare const pathSchema: z.ZodLazy<z.ZodString>;
 /** Validate text against a minimum character length and the Files UTF-8 byte limit. */
@@ -11,15 +19,112 @@ export declare const readInputSchema: z.ZodLazy<z.ZodObject<{
     offset: z.ZodDefault<z.ZodNumber>;
     limit: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strict>>;
+/** The image types a Files read can return. */
+export declare const readImageMimeType: z.ZodEnum<{
+    "image/png": "image/png";
+    "image/jpeg": "image/jpeg";
+    "image/gif": "image/gif";
+    "image/webp": "image/webp";
+}>;
+/** Whole png, jpeg, gif or webp file, at most `maximumImageBytes`, as base64. */
+export declare const readImageOutputSchema: z.ZodLazy<z.ZodObject<{
+    path: z.ZodLazy<z.ZodString>;
+    image: z.ZodObject<{
+        mimeType: z.ZodEnum<{
+            "image/png": "image/png";
+            "image/jpeg": "image/jpeg";
+            "image/gif": "image/gif";
+            "image/webp": "image/webp";
+        }>;
+        data: z.ZodBase64;
+        bytes: z.ZodNumber;
+    }, z.core.$strict>;
+    file: z.ZodExactOptional<z.ZodLazy<z.ZodObject<{
+        computerId: z.ZodString;
+        path: z.ZodLazy<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>>;
 /** Bounded text page, continuation offset and optional hosted file identity. */
-export declare const readOutputSchema: z.ZodLazy<z.ZodObject<{
+export declare const readTextOutputSchema: z.ZodLazy<z.ZodObject<{
     path: z.ZodLazy<z.ZodString>;
     content: z.ZodString;
     offset: z.ZodNumber;
     nextOffset: z.ZodNullable<z.ZodNumber>;
     truncated: z.ZodBoolean;
-    file: z.ZodExactOptional<z.ZodObject<{
+    file: z.ZodExactOptional<z.ZodLazy<z.ZodObject<{
         computerId: z.ZodString;
         path: z.ZodLazy<z.ZodString>;
-    }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+}, z.core.$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.
+ */
+export declare const readImageCaptionSchema: z.ZodLazy<z.ZodObject<{
+    path: z.ZodLazy<z.ZodString>;
+    image: z.ZodObject<{
+        ref: z.ZodString;
+        mimeType: z.ZodEnum<{
+            "image/png": "image/png";
+            "image/jpeg": "image/jpeg";
+            "image/gif": "image/gif";
+            "image/webp": "image/webp";
+        }>;
+        bytes: z.ZodNumber;
+    }, z.core.$strict>;
 }, z.core.$strict>>;
+/** Text page or image caption returned to guest code. */
+export declare const readGuestOutputSchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodLazy<z.ZodObject<{
+    path: z.ZodLazy<z.ZodString>;
+    content: z.ZodString;
+    offset: z.ZodNumber;
+    nextOffset: z.ZodNullable<z.ZodNumber>;
+    truncated: z.ZodBoolean;
+    file: z.ZodExactOptional<z.ZodLazy<z.ZodObject<{
+        computerId: z.ZodString;
+        path: z.ZodLazy<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+    path: z.ZodLazy<z.ZodString>;
+    image: z.ZodObject<{
+        ref: z.ZodString;
+        mimeType: z.ZodEnum<{
+            "image/png": "image/png";
+            "image/jpeg": "image/jpeg";
+            "image/gif": "image/gif";
+            "image/webp": "image/webp";
+        }>;
+        bytes: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>>]>>;
+/** A bounded text page or a whole image; images are only read from offset 0. */
+export declare const readOutputSchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodLazy<z.ZodObject<{
+    path: z.ZodLazy<z.ZodString>;
+    content: z.ZodString;
+    offset: z.ZodNumber;
+    nextOffset: z.ZodNullable<z.ZodNumber>;
+    truncated: z.ZodBoolean;
+    file: z.ZodExactOptional<z.ZodLazy<z.ZodObject<{
+        computerId: z.ZodString;
+        path: z.ZodLazy<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+    path: z.ZodLazy<z.ZodString>;
+    image: z.ZodObject<{
+        mimeType: z.ZodEnum<{
+            "image/png": "image/png";
+            "image/jpeg": "image/jpeg";
+            "image/gif": "image/gif";
+            "image/webp": "image/webp";
+        }>;
+        data: z.ZodBase64;
+        bytes: z.ZodNumber;
+    }, z.core.$strict>;
+    file: z.ZodExactOptional<z.ZodLazy<z.ZodObject<{
+        computerId: z.ZodString;
+        path: z.ZodLazy<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>>]>>;
+/** Build the image read result for a recognised image's complete bytes. */
+export declare function imageReadResult(path: string, mimeType: string, bytes: Uint8Array): z.output<typeof readImageOutputSchema>;

package/dist/files-read.js

@@ -1,7 +1,37 @@
+import * as Base64 from "effect/encoding/Base64";
 import * as z from "zod";
 /** Maximum UTF-8 byte length of a Files text page. */
 export const maximumReadBytes = 128 * 1_024;
+/** Maximum byte length of an image the read tool returns; a host refuses an image it cannot bring within it. */
+export const maximumImageBytes = 512 * 1_024;
 const utf8 = new TextEncoder();
+const signatures = [
+    {
+        mimeType: "image/png",
+        bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
+    },
+    { mimeType: "image/jpeg", bytes: [0xff, 0xd8, 0xff] },
+    { mimeType: "image/gif", bytes: [0x47, 0x49, 0x46, 0x38, 0x37, 0x61] },
+    { mimeType: "image/gif", bytes: [0x47, 0x49, 0x46, 0x38, 0x39, 0x61] },
+];
+const riff = [0x52, 0x49, 0x46, 0x46];
+const webp = [0x57, 0x45, 0x42, 0x50];
+/** Bytes needed at the start of a file to recognise a supported image. */
+export const imageSniffBytes = 12;
+const hasBytesAt = (head, offset, bytes) => bytes.every((byte, index) => head[offset + index] === byte);
+/** Identify png, jpeg, gif or webp by their full magic bytes; `undefined` means not a supported image. */
+export function sniffImageMimeType(head) {
+    for (const { mimeType, bytes } of signatures)
+        if (hasBytesAt(head, 0, bytes))
+            return mimeType;
+    return hasBytesAt(head, 0, riff) && hasBytesAt(head, 8, webp)
+        ? "image/webp"
+        : undefined;
+}
+/** Message for an image above a host's read cap, shared by every Files host. */
+export function imageTooLargeMessage(path, size, limit) {
+    return `Image ${path} is ${String(size)} bytes; the read limit is ${String(limit)} bytes. Refusing to read it.`;
+}
 /** Nonempty file path bounded to 4,096 characters, without null bytes. */
 export const pathSchema = z.lazy(() => z
     .string()
@@ -26,18 +56,58 @@ export const readInputSchema = z.lazy(() => z.strictObject({
         .max(maximumReadBytes)
         .default(maximumReadBytes),
 }));
+const fileIdentitySchema = z.lazy(() => z.strictObject({
+    computerId: z.string().min(1).max(256),
+    path: pathSchema.refine((path) => path.startsWith("/"), "Computer file paths must be absolute"),
+}));
+/** The image types a Files read can return. */
+export const readImageMimeType = z.enum([
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+]);
+/** Whole png, jpeg, gif or webp file, at most `maximumImageBytes`, as base64. */
+export const readImageOutputSchema = z.lazy(() => z.strictObject({
+    path: pathSchema,
+    image: z.strictObject({
+        mimeType: readImageMimeType,
+        data: z.base64(),
+        bytes: z.number().int().min(1).max(maximumImageBytes),
+    }),
+    file: fileIdentitySchema.exactOptional(),
+}));
 /** Bounded text page, continuation offset and optional hosted file identity. */
-export const readOutputSchema = z.lazy(() => z.strictObject({
+export const readTextOutputSchema = z.lazy(() => z.strictObject({
     path: pathSchema,
     content: boundedTextSchema(),
     offset: z.number().int().min(0),
     nextOffset: z.number().int().min(0).nullable(),
     truncated: z.boolean(),
     /** Captured hosted file identity; a local Files host may have no Computer identity. */
-    file: z
-        .strictObject({
-        computerId: z.string().min(1).max(256),
-        path: pathSchema.refine((path) => path.startsWith("/"), "Computer file paths must be absolute"),
-    })
-        .exactOptional(),
+    file: fileIdentitySchema.exactOptional(),
+}));
+/**
+ * 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.
+ */
+export const readImageCaptionSchema = z.lazy(() => z.strictObject({
+    path: pathSchema,
+    image: z.strictObject({
+        ref: z.string().min(1).max(32),
+        mimeType: readImageMimeType,
+        bytes: z.number().int().min(1).max(maximumImageBytes),
+    }),
 }));
+/** Text page or image caption returned to guest code. */
+export const readGuestOutputSchema = z.lazy(() => z.union([readTextOutputSchema, readImageCaptionSchema]));
+/** A bounded text page or a whole image; images are only read from offset 0. */
+export const readOutputSchema = z.lazy(() => z.union([readTextOutputSchema, readImageOutputSchema]));
+/** Build the image read result for a recognised image's complete bytes. */
+export function imageReadResult(path, mimeType, bytes) {
+    return readImageOutputSchema.parse({
+        path,
+        image: { mimeType, data: Base64.encode(bytes), bytes: bytes.byteLength },
+    });
+}

package/dist/files-search.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Invocation-local search visibility shared by Local and hosted Files.
+ * Adapters supply bounded `.gitignore` text; `ignore` owns its grammar.
+ * All paths here are canonical, root-relative paths with `/` separators;
+ * the captured root itself is `""`. Exact reads do not use this policy.
+ */
+export declare class SearchVisibility {
+    private readonly readGitignore;
+    private readonly matchers;
+    constructor(readGitignore: (directory: string) => Promise<string | undefined>);
+    /** Check the search root and every entry with the same ancestor precedence. */
+    visible(path: string, isDirectory: boolean): Promise<boolean>;
+    private at;
+}

package/dist/files-search.js

@@ -0,0 +1,52 @@
+import ignore, {} from "ignore";
+/**
+ * Invocation-local search visibility shared by Local and hosted Files.
+ * Adapters supply bounded `.gitignore` text; `ignore` owns its grammar.
+ * All paths here are canonical, root-relative paths with `/` separators;
+ * the captured root itself is `""`. Exact reads do not use this policy.
+ */
+export class SearchVisibility {
+    readGitignore;
+    matchers = new Map();
+    constructor(readGitignore) {
+        this.readGitignore = readGitignore;
+    }
+    /** Check the search root and every entry with the same ancestor precedence. */
+    async visible(path, isDirectory) {
+        if (path === "")
+            return true;
+        const parts = path.split("/");
+        if (parts.includes(".git"))
+            return false;
+        const layers = [];
+        for (let index = 0; index < parts.length; index++) {
+            const base = parts.slice(0, index).join("/");
+            layers.push({ base, matcher: await this.at(base) });
+            const candidate = parts.slice(0, index + 1).join("/");
+            const directory = index < parts.length - 1 || isDirectory;
+            // Never reopen an excluded ancestor with a descendant's negation.
+            for (const layer of layers.toReversed()) {
+                const local = layer.base === ""
+                    ? candidate
+                    : candidate.slice(layer.base.length + 1);
+                const verdict = layer.matcher.test(directory ? `${local}/` : local);
+                if (verdict.ignored)
+                    return false;
+                if (verdict.unignored)
+                    break;
+            }
+        }
+        return true;
+    }
+    async at(directory) {
+        const cached = this.matchers.get(directory);
+        if (cached !== undefined)
+            return cached;
+        const content = await this.readGitignore(directory);
+        const matcher = ignore();
+        if (content !== undefined)
+            matcher.add(content);
+        this.matchers.set(directory, matcher);
+        return matcher;
+    }
+}

package/dist/files.d.ts

@@ -2,66 +2,53 @@ import { type Access, type InvocationContext, type LabelledTool, type ModuleRegi
 import { patchInputSchema, patchOutputSchema } from "./files-patch.js";
 export { patchInputSchema, patchOutputSchema } from "./files-patch.js";
 import { z } from "zod";
-import { readInputSchema, readOutputSchema } from "./files-read.js";
-export { readInputSchema, readOutputSchema };
+import { readInputSchema, readGuestOutputSchema, readOutputSchema } from "./files-read.js";
+export { readGuestOutputSchema, readInputSchema, readOutputSchema };
 /** Typed refusal from a bounded or conditional Files edit. */
-export type FilesEditErrorReason = "not-found" | "ambiguous" | "file-too-large" | "partial-character" | "unchanged" | "conflict";
+export type FilesEditErrorReason = "not-found" | "ambiguous" | "file-too-large" | "partial-character" | "unchanged" | "not-text" | "conflict";
 /** Expected Files edit refusal, kept distinct from unexpected host failures. */
 export declare class FilesEditError extends Error {
     readonly reason: FilesEditErrorReason;
     readonly path: string;
     constructor(reason: FilesEditErrorReason, path: string, detail: string);
 }
-/** Bounded directory listing request. */
-export declare const listInputSchema: z.ZodObject<{
-    path: z.ZodLazy<z.ZodString>;
+/** List one directory level. */
+export declare const listInputSchema: z.ZodLazy<z.ZodObject<{
+    path: z.ZodDefault<z.ZodLazy<z.ZodString>>;
     limit: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strict>;
-/** Directory entries and an explicit truncation flag. */
-export declare const listOutputSchema: z.ZodLazy<z.ZodObject<{
-    path: z.ZodLazy<z.ZodString>;
-    entries: z.ZodArray<z.ZodLazy<z.ZodObject<{
-        path: z.ZodLazy<z.ZodString>;
-        name: z.ZodString;
-        type: z.ZodEnum<{
-            file: "file";
-            directory: "directory";
-            symlink: "symlink";
-        }>;
-        size: z.ZodNumber;
-        modifiedAt: z.ZodNumber;
-    }, z.core.$strict>>>;
-    truncated: z.ZodBoolean;
 }, z.core.$strict>>;
-/** Bounded path-pattern search request. */
+/** Match paths below a directory by glob. */
 export declare const globInputSchema: z.ZodLazy<z.ZodObject<{
-    path: z.ZodLazy<z.ZodString>;
+    path: z.ZodDefault<z.ZodLazy<z.ZodString>>;
     pattern: z.ZodString;
     limit: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strict>>;
-/** Matching paths and an explicit truncation flag. */
-export declare const globOutputSchema: z.ZodLazy<z.ZodObject<{
-    path: z.ZodLazy<z.ZodString>;
-    matches: z.ZodArray<z.ZodLazy<z.ZodString>>;
-    truncated: z.ZodBoolean;
-}, z.core.$strict>>;
-/** Bounded content-search request with optional regular-expression matching. */
+/** Search file content, optionally restricted to matching paths. */
 export declare const grepInputSchema: z.ZodLazy<z.ZodObject<{
-    path: z.ZodLazy<z.ZodString>;
+    path: z.ZodDefault<z.ZodLazy<z.ZodString>>;
     pattern: z.ZodString;
+    include: z.ZodOptional<z.ZodString>;
     regex: z.ZodDefault<z.ZodBoolean>;
     ignoreCase: z.ZodDefault<z.ZodBoolean>;
     limit: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strict>>;
-/** Content matches and an explicit truncation flag. */
-export declare const grepOutputSchema: z.ZodLazy<z.ZodObject<{
+/** Found paths or matching lines, and which cap (if any) cut the search short. */
+export declare const searchOutputSchema: z.ZodLazy<z.ZodObject<{
     path: z.ZodLazy<z.ZodString>;
-    matches: z.ZodArray<z.ZodObject<{
+    results: z.ZodArray<z.ZodLazy<z.ZodObject<{
         path: z.ZodLazy<z.ZodString>;
-        line: z.ZodNumber;
-        text: z.ZodString;
-    }, z.core.$strict>>;
-    truncated: z.ZodBoolean;
+        type: z.ZodExactOptional<z.ZodEnum<{
+            file: "file";
+            directory: "directory";
+            symlink: "symlink";
+        }>>;
+        line: z.ZodExactOptional<z.ZodNumber>;
+        text: z.ZodExactOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    truncated: z.ZodNullable<z.ZodEnum<{
+        limit: "limit";
+        scan: "scan";
+    }>>;
 }, z.core.$strict>>;
 /** Text replacement request decoded before the captured Files port is called. */
 export declare const editInputSchema: z.ZodLazy<z.ZodObject<{
@@ -79,6 +66,7 @@ export declare const filesEditFailureSchema: z.ZodLazy<z.ZodObject<{
             "file-too-large": "file-too-large";
             "partial-character": "partial-character";
             unchanged: "unchanged";
+            "not-text": "not-text";
             conflict: "conflict";
         }>;
         path: z.ZodLazy<z.ZodString>;
@@ -105,6 +93,7 @@ export declare const editOutputSchema: z.ZodUnion<readonly [z.ZodLazy<z.ZodObjec
             "file-too-large": "file-too-large";
             "partial-character": "partial-character";
             unchanged: "unchanged";
+            "not-text": "not-text";
             conflict: "conflict";
         }>;
         path: z.ZodLazy<z.ZodString>;
@@ -119,12 +108,12 @@ export type FilesPort = Readonly<{
     patch?: FilesPatch;
     /** Read a bounded text page. */
     read: (input: z.output<typeof readInputSchema>, context: InvocationContext) => Promise<z.output<typeof readOutputSchema>>;
-    /** List bounded directory entries. */
-    list: (input: z.output<typeof listInputSchema>, context: InvocationContext) => Promise<z.output<typeof listOutputSchema>>;
-    /** Match bounded paths under the admitted root. */
-    glob: (input: z.output<typeof globInputSchema>, context: InvocationContext) => Promise<z.output<typeof globOutputSchema>>;
-    /** Search bounded file content under the admitted root. */
-    grep: (input: z.output<typeof grepInputSchema>, context: InvocationContext) => Promise<z.output<typeof grepOutputSchema>>;
+    /** List one directory level under the admitted root. */
+    list: (input: z.output<typeof listInputSchema>, context: InvocationContext) => Promise<z.output<typeof searchOutputSchema>>;
+    /** Match paths below the admitted root by glob. */
+    glob: (input: z.output<typeof globInputSchema>, context: InvocationContext) => Promise<z.output<typeof searchOutputSchema>>;
+    /** Search file content under the admitted root; the host owns the walk. */
+    grep: (input: z.output<typeof grepInputSchema>, context: InvocationContext) => Promise<z.output<typeof searchOutputSchema>>;
     /** Replace atomically only if the stored content still matches the baseline. */
     replace: (input: Readonly<{
         path: string;
@@ -135,7 +124,7 @@ export type FilesPort = Readonly<{
         bytes: number;
     }>>;
 }>;
-/** Closed set of direct, model-visible Files tools; widening one is an ADR. */
+/** Closed set of direct, model-visible Files tools; changing it is an ADR. */
 export type FileToolName = "read" | "list" | "glob" | "grep" | "apply_patch";
 declare const fileToolBrand: unique symbol;
 /**
@@ -166,5 +155,10 @@ export type FilesConnectionOptions = Readonly<{
 }>;
 /** Apply the same edit behavior as the Files edit operation directly through a captured FilesPort. */
 export declare function edit(port: FilesPort, input: z.output<typeof editInputSchema>, context: InvocationContext): Promise<z.output<typeof editOutputSchema>>;
+/**
+ * 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 declare function presentReadForGuest(result: z.output<typeof readOutputSchema>, context: InvocationContext): z.output<typeof readGuestOutputSchema>;
 /** Build both patch presentations around one injected Files operation. */
 export declare function files(input: FilesConnectionOptions): FilesSurface;