@fungi.computer/knapsack 0.0.2 → 0.2.0

package/dist/files.d.ts

@@ -2,75 +2,62 @@ 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.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.ZodObject<{
-    path: z.ZodString;
-    entries: z.ZodArray<z.ZodObject<{
-        path: 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. */
-export declare const globInputSchema: z.ZodObject<{
-    path: z.ZodString;
+}, z.core.$strict>>;
+/** Match paths below a directory by glob. */
+export declare const globInputSchema: z.ZodLazy<z.ZodObject<{
+    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.ZodObject<{
-    path: z.ZodString;
-    matches: z.ZodArray<z.ZodString>;
-    truncated: z.ZodBoolean;
-}, z.core.$strict>;
-/** Bounded content-search request with optional regular-expression matching. */
-export declare const grepInputSchema: z.ZodObject<{
-    path: z.ZodString;
+}, z.core.$strict>>;
+/** Search file content, optionally restricted to matching paths. */
+export declare const grepInputSchema: z.ZodLazy<z.ZodObject<{
+    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.ZodObject<{
-    path: z.ZodString;
-    matches: z.ZodArray<z.ZodObject<{
-        path: z.ZodString;
-        line: z.ZodNumber;
-        text: z.ZodString;
-    }, z.core.$strict>>;
-    truncated: z.ZodBoolean;
-}, z.core.$strict>;
+}, z.core.$strict>>;
+/** 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>;
+    results: z.ZodArray<z.ZodLazy<z.ZodObject<{
+        path: z.ZodLazy<z.ZodString>;
+        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.ZodObject<{
-    path: z.ZodString;
+export declare const editInputSchema: z.ZodLazy<z.ZodObject<{
+    path: z.ZodLazy<z.ZodString>;
     oldText: z.ZodString;
     newText: z.ZodString;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** Structured edit refusal, including its reason and affected path. */
-export declare const filesEditFailureSchema: z.ZodObject<{
+export declare const filesEditFailureSchema: z.ZodLazy<z.ZodObject<{
     status: z.ZodLiteral<"failed">;
     error: z.ZodObject<{
         kind: z.ZodEnum<{
@@ -79,15 +66,16 @@ export declare const filesEditFailureSchema: z.ZodObject<{
             "file-too-large": "file-too-large";
             "partial-character": "partial-character";
             unchanged: "unchanged";
+            "not-text": "not-text";
             conflict: "conflict";
         }>;
-        path: z.ZodString;
+        path: z.ZodLazy<z.ZodString>;
         message: z.ZodString;
     }, z.core.$strict>;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** Successful edit metadata or a typed edit refusal. */
-export declare const editOutputSchema: z.ZodUnion<readonly [z.ZodObject<{
-    path: z.ZodString;
+export declare const editOutputSchema: z.ZodUnion<readonly [z.ZodLazy<z.ZodObject<{
+    path: z.ZodLazy<z.ZodString>;
     bytes: z.ZodNumber;
     diff: z.ZodString;
     firstChangedLine: z.ZodNullable<z.ZodNumber>;
@@ -96,7 +84,7 @@ export declare const editOutputSchema: z.ZodUnion<readonly [z.ZodObject<{
     unifiedPatchAddedLines: z.ZodNumber;
     unifiedPatchRemovedLines: z.ZodNumber;
     unifiedPatchTruncated: z.ZodBoolean;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
     status: z.ZodLiteral<"failed">;
     error: z.ZodObject<{
         kind: z.ZodEnum<{
@@ -105,12 +93,13 @@ export declare const editOutputSchema: z.ZodUnion<readonly [z.ZodObject<{
             "file-too-large": "file-too-large";
             "partial-character": "partial-character";
             unchanged: "unchanged";
+            "not-text": "not-text";
             conflict: "conflict";
         }>;
-        path: z.ZodString;
+        path: z.ZodLazy<z.ZodString>;
         message: z.ZodString;
     }, z.core.$strict>;
-}, z.core.$strict>]>;
+}, z.core.$strict>>]>;
 /** Host-owned native patch operation receiving the invocation's deadline and signal. */
 export type FilesPatch = (input: z.output<typeof patchInputSchema>, context: InvocationContext) => Promise<z.output<typeof patchOutputSchema>>;
 /** Captured host file authority; the host owns path confinement and atomic replacement. */
@@ -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;

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,78 +28,53 @@ 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.strictObject({
-    path: pathSchema,
-    name: z.string().min(1),
-    type: z.enum(["file", "directory", "symlink"]),
-    size: z.number().int().nonnegative(),
-    modifiedAt: z.number(),
-});
-/** Directory entries and an explicit truncation flag. */
-export const listOutputSchema = z.strictObject({
-    path: pathSchema,
-    entries: z.array(listEntrySchema).max(maximumResultEntries),
-    truncated: z.boolean(),
-});
-/** Bounded path-pattern search request. */
-export const globInputSchema = z.strictObject({
-    path: pathSchema,
-    pattern: z.string().min(1).max(maximumPatternCharacters),
-    limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(maximumResultEntries)
-        .default(maximumResultEntries),
-});
-/** Matching paths and an explicit truncation flag. */
-export const globOutputSchema = z.strictObject({
-    path: pathSchema,
-    matches: z.array(pathSchema).max(maximumResultEntries),
-    truncated: z.boolean(),
-});
-/** Bounded content-search request with optional regular-expression matching. */
-export const grepInputSchema = z.strictObject({
-    path: pathSchema,
-    pattern: z.string().min(1).max(maximumPatternCharacters),
+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,
+}));
+/** Match paths below a directory by glob. */
+export const globInputSchema = z.lazy(() => z.strictObject({
+    path: pathSchema.default("."),
+    pattern: searchPatternSchema,
+    limit: searchLimitSchema,
+}));
+/** Search file content, optionally restricted to matching paths. */
+export const grepInputSchema = z.lazy(() => z.strictObject({
+    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),
-});
-/** Content matches and an explicit truncation flag. */
-export const grepOutputSchema = z.strictObject({
+    limit: searchLimitSchema,
+}));
+/** 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.strictObject({
+export const editInputSchema = z.lazy(() => z.strictObject({
     path: pathSchema,
     oldText: boundedTextSchema(1),
     newText: boundedTextSchema(),
-});
-const editSuccessSchema = z.strictObject({
+}));
+const editSuccessSchema = z.lazy(() => z.strictObject({
     path: pathSchema,
     bytes: z.number().int().nonnegative(),
     diff: z.string(),
@@ -106,9 +84,9 @@ const editSuccessSchema = z.strictObject({
     unifiedPatchAddedLines: z.number().int().nonnegative(),
     unifiedPatchRemovedLines: z.number().int().nonnegative(),
     unifiedPatchTruncated: z.boolean(),
-});
+}));
 /** Structured edit refusal, including its reason and affected path. */
-export const filesEditFailureSchema = z.strictObject({
+export const filesEditFailureSchema = z.lazy(() => z.strictObject({
     status: z.literal("failed"),
     error: z.strictObject({
         kind: z.enum([
@@ -116,13 +94,14 @@ export const filesEditFailureSchema = z.strictObject({
             "ambiguous",
             "file-too-large",
             "partial-character",
+            "not-text",
             "unchanged",
             "conflict",
         ]),
         path: pathSchema,
         message: z.string(),
     }),
-});
+}));
 /** Successful edit metadata or a typed edit refusal. */
 export const editOutputSchema = z.union([
     editSuccessSchema,
@@ -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";