@xandreed/plugin-workspace 0.0.0-stage → 0.15.0

package/dist/workspace-tools.entity.d.ts

@@ -0,0 +1,552 @@
+import { Schema } from "effect";
+/**
+ * The seven workspace tools, by the names the model calls them.
+ *
+ * @public
+ */
+export declare const WorkspaceToolName: Schema.Literals<readonly ["read", "write", "edit", "ls", "find", "grep", "bash"]>;
+export type WorkspaceToolName = typeof WorkspaceToolName.Type;
+/**
+ * The tools' three skills, by the short names `always` takes: `read`
+ * (`workspace.read`: read, ls, find, grep), `edit` (`workspace.edit`: write,
+ * edit) and `shell` (`workspace.shell`: bash).
+ *
+ * @public
+ */
+export declare const WorkspaceSkillName: Schema.Literals<readonly ["read", "edit", "shell"]>;
+export type WorkspaceSkillName = typeof WorkspaceSkillName.Type;
+/**
+ * The grants the tools that change things need: `write` and `edit` need `fs.write`, `bash` needs `shell.exec`.
+ *
+ * @public
+ */
+export declare const WORKSPACE_PERMISSIONS: {
+    readonly write: "fs.write";
+    readonly exec: "shell.exec";
+};
+/**
+ * How `workspaceToolsPlugin` (and `workspaceTools`) works on the workspace,
+ * `SessionEnvironment.workspace`. Flat.
+ *
+ * - `tools`: the tools to register (all seven by default). A skill whose
+ *   tools are all left out is left out too.
+ * - `always`: the skills active from a turn's first step: `read` by default.
+ *   `edit` and `shell` here need their grants (`fs.write`, `shell.exec`), or
+ *   the turn fails with `capability.forbidden`; otherwise the model loads
+ *   them with `load_skill`, which refuses them without the grants
+ *   (`PermissionDenied`).
+ * - `confine`: refuse paths whose real location (links resolved, through the
+ *   nearest ancestor that exists) is outside the workspace and extra roots.
+ * - `workspaceAccess`: `read` refuses writes in the workspace; `write`
+ *   permits them. `roots` adds readable or writable directories, absolute
+ *   or relative to the session's workspace. The longest matching real root
+ *   decides access. These restrictions apply with `confine`; bash remains
+ *   unconfined. An extra root that cannot be resolved is skipped and logged.
+ * - `protect`: globs, relative to the root, that `write` and `edit` refuse.
+ * - `exclude`: names (or, with a `/`, paths relative to the root) `find`
+ *   and `grep` never enter below the directory they search. Both lists are
+ *   checked with `compileGlob` when the options are decoded.
+ * - `maxLines`, `maxBytes`: the most `read`, `find` and `grep` show at once,
+ *   and the tail of a command's output `bash` keeps.
+ * - `lsEntries`, `findResults`, `grepMatches`: the most entries, paths and
+ *   matching lines the model gets (a call may ask for fewer).
+ * - `grepLineChars`: the displayed line width; builtin also cuts before matching.
+ * - `grepEngine`: auto probes for rg once over this machine's pair
+ *   (`localSystemPlugin`'s FileSystem and Bash), falling back to builtin,
+ *   and selects builtin over any other pair; ripgrep requires rg over
+ *   whatever pair the host gives. `grepTimeoutMs` bounds rg commands; the synchronous builtin
+ *   engine is not time-bounded. `grepIgnoreFiles` honours ignore files in rg
+ *   only (false searches ignored files too).
+ * - `maxFileBytes`: the largest file `read`, `edit` and `grep` load, and
+ *   the most of a command's output `bash` saves.
+ * - `readImages`: `read` returns a PNG, JPEG, GIF or WebP image (by its
+ *   bytes, whatever its name) as an image the model is sent; `false`
+ *   reports it as a binary file, as any other. A host whose models read
+ *   text only (a route without image parts, such as an endpoint without
+ *   `images`, or memory with `maxMediaChars: 0`) sets `false`: the model
+ *   would get a label line in the image's place, and the session would
+ *   still store the bytes.
+ * - `imageMaxSide`: with an ImageResizer, fit images to at most this many
+ *   pixels a side (64 to 8000, default 8000). Without a resizer, read keeps
+ *   the existing provider-limit behavior.
+ * - `fuzzyEdit`: when an edit's text is not found, match it once more over
+ *   whole lines with whitespace, Unicode compatibility forms and smart
+ *   quotes normalised (the match must still be unique).
+ * - `bashTimeoutMs`, `bashMaxTimeoutMs`: a command's timeout unless the
+ *   model asks for another, and the most it may ask for.
+ * - `bashEnv`: variables every command gets. `bashInheritEnv: true` passes
+ *   the host's whole environment (provider keys included); otherwise only
+ *   the names in `bashEnvAllow` (a trailing `*` matches a prefix) pass.
+ *   `bashSessionEnv` adds `EFFERENT_SESSION_ID`, `EFFERENT_RUN_ID` and
+ *   `EFFERENT_WORKSPACE`.
+ * - `spillDir`: where a command's whole output (its first `maxFileBytes`)
+ *   is saved once it is longer than `bash` shows (relative to the root;
+ *   `null` saves nothing), keeping the newest `spillKeep` files.
+ * - `progressMs`: how long output is gathered before it is published, as
+ *   one `tool.progress` event per run of output from one stream.
+ * - `environmentSection`, `sectionOrder`: the `workspace.environment`
+ *   system-prompt section (tier `session`) and its order.
+ *
+ * @public
+ */
+export declare const WorkspaceToolsConfig: Schema.Struct<{
+    readonly tools: Schema.$Array<Schema.Literals<readonly ["read", "write", "edit", "ls", "find", "grep", "bash"]>>;
+    readonly always: Schema.$Array<Schema.Literals<readonly ["read", "edit", "shell"]>>;
+    readonly confine: Schema.Boolean;
+    readonly workspaceAccess: Schema.Literals<readonly ["read", "write"]>;
+    readonly roots: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.NonEmptyString;
+        readonly access: Schema.Literals<readonly ["read", "write"]>;
+    }>>;
+    readonly protect: Schema.$Array<Schema.String>;
+    readonly exclude: Schema.$Array<Schema.String>;
+    readonly maxLines: Schema.Int;
+    readonly maxBytes: Schema.Int;
+    readonly lsEntries: Schema.Int;
+    readonly findResults: Schema.Int;
+    readonly grepMatches: Schema.Int;
+    readonly grepLineChars: Schema.Int;
+    readonly grepEngine: Schema.Literals<readonly ["auto", "ripgrep", "builtin"]>;
+    readonly grepTimeoutMs: Schema.Int;
+    readonly grepIgnoreFiles: Schema.Boolean;
+    readonly maxFileBytes: Schema.Int;
+    readonly readImages: Schema.Boolean;
+    readonly imageMaxSide: Schema.Int;
+    readonly fuzzyEdit: Schema.Boolean;
+    readonly bashTimeoutMs: Schema.Int;
+    readonly bashMaxTimeoutMs: Schema.Int;
+    readonly bashEnv: Schema.$Record<Schema.String, Schema.String>;
+    readonly bashInheritEnv: Schema.Boolean;
+    readonly bashEnvAllow: Schema.$Array<Schema.String>;
+    readonly bashSessionEnv: Schema.Boolean;
+    readonly spillDir: Schema.NullOr<Schema.String>;
+    readonly spillKeep: Schema.Int;
+    readonly progressMs: Schema.Int;
+    readonly environmentSection: Schema.Boolean;
+    readonly sectionOrder: Schema.Int;
+}>;
+export type WorkspaceToolsConfig = typeof WorkspaceToolsConfig.Type;
+/** @public */
+export declare const workspaceToolsDefaults: WorkspaceToolsConfig;
+/**
+ * `read`: a file's lines from `offset` (1-based, default 1), at most `limit` of them (and never more than the configured window).
+ *
+ * @public
+ */
+export declare const ReadParams: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly offset: Schema.optionalKey<Schema.Int>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+export type ReadParams = typeof ReadParams.Type;
+/**
+ * What `read` found: a window of a text file's lines (`next` is the offset
+ * to continue from when lines are left; `clipped` when the first line alone
+ * was longer than the window's bytes and only its start is shown; `lossy`
+ * when the file is not valid UTF-8 and the bytes that are not show as
+ * U+FFFD, which `edit` refuses), or a binary file (a NUL byte in its first
+ * 8 KB). With `readImages`, a binary file whose bytes are a PNG, JPEG, GIF
+ * or WebP image is an `Image` (core's `mediaFromBytes`: the type its bytes
+ * are, its size and fingerprint), which the view sends the model as an
+ * image of the result; one core refuses (over `MEDIA_LIMITS.imageBytes`,
+ * over `MEDIA_LIMITS.maxPixels` a side, or a header without a size) is an
+ * `ImageRejected` note: its type, size and why. Any other binary file is
+ * `Binary`, with the media type its name suggests.
+ *
+ * @public
+ */
+export declare const ReadResult: Schema.Union<readonly [Schema.TaggedStruct<"Text", {
+    readonly path: Schema.String;
+    readonly text: Schema.String;
+    readonly firstLine: Schema.Int;
+    readonly lastLine: Schema.Int;
+    readonly totalLines: Schema.Int;
+    readonly next: Schema.NullOr<Schema.Int>;
+    readonly clipped: Schema.Boolean;
+    readonly lossy: Schema.Boolean;
+}>, Schema.TaggedStruct<"Binary", {
+    readonly path: Schema.String;
+    readonly bytes: Schema.Int;
+    readonly mediaType: Schema.NullOr<Schema.String>;
+}>, Schema.TaggedStruct<"Image", {
+    readonly path: Schema.String;
+    readonly image: Schema.Struct<{
+        readonly type: Schema.Literal<"media">;
+        readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+        readonly data: Schema.String;
+        readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+        readonly bytes: Schema.Int;
+        readonly name: Schema.optionalKey<Schema.String>;
+        readonly alt: Schema.optionalKey<Schema.String>;
+    }>;
+    /** Source dimensions and size when a resizer supplied the returned image; no original image bytes. */
+    readonly original: Schema.optionalKey<Schema.Struct<{
+        readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+        readonly bytes: Schema.Int;
+        readonly width: Schema.Int;
+        readonly height: Schema.Int;
+    }>>;
+}>, Schema.TaggedStruct<"ImageRejected", {
+    readonly path: Schema.String;
+    readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+    readonly bytes: Schema.Int;
+    readonly reason: Schema.Literals<readonly ["Empty", "InvalidBase64", "UnsupportedType", "TooLarge", "TooManyPixels", "Unreadable", "TooMany", "TooLargeTogether"]>;
+    readonly message: Schema.String;
+}>]>;
+export type ReadResult = typeof ReadResult.Type;
+/** @public */
+export declare const WriteParams: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly content: Schema.String;
+}>;
+export type WriteParams = typeof WriteParams.Type;
+/**
+ * What `write` did: how many bytes it wrote, and whether the file is new.
+ *
+ * @public
+ */
+export declare const WriteResult: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly bytes: Schema.Int;
+    readonly created: Schema.Boolean;
+}>;
+export type WriteResult = typeof WriteResult.Type;
+/**
+ * One replacement: `oldText` (exactly once in the file) becomes `newText`.
+ *
+ * @public
+ */
+export declare const TextEdit: Schema.Struct<{
+    readonly oldText: Schema.String;
+    readonly newText: Schema.String;
+}>;
+export type TextEdit = typeof TextEdit.Type;
+/** @public */
+export declare const EditParams: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly edits: Schema.NonEmptyArray<Schema.Struct<{
+        readonly oldText: Schema.String;
+        readonly newText: Schema.String;
+    }>>;
+}>;
+export type EditParams = typeof EditParams.Type;
+/**
+ * What `edit` did: how many blocks it replaced, whether any was found only
+ * after normalising, the first changed line, and the change as a unified
+ * diff (for a host's UI; the model is shown a one-line summary).
+ *
+ * @public
+ */
+export declare const EditResult: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly replaced: Schema.Int;
+    readonly normalized: Schema.Boolean;
+    readonly firstChangedLine: Schema.Int;
+    readonly diff: Schema.String;
+}>;
+export type EditResult = typeof EditResult.Type;
+/** @public */
+export declare const LsParams: Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+export type LsParams = typeof LsParams.Type;
+/** @public */
+export declare const LsEntry: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["file", "directory", "symlink", "other"]>;
+}>;
+export type LsEntry = typeof LsEntry.Type;
+/**
+ * A directory's entries by name, at most the limit of them; `total` counts them all.
+ *
+ * @public
+ */
+export declare const LsResult: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly entries: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly kind: Schema.Literals<readonly ["file", "directory", "symlink", "other"]>;
+    }>>;
+    readonly total: Schema.Int;
+}>;
+export type LsResult = typeof LsResult.Type;
+/** @public */
+export declare const FindParams: Schema.Struct<{
+    readonly pattern: Schema.String;
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+export type FindParams = typeof FindParams.Type;
+/**
+ * The files a glob matched, as paths relative to the workspace root; `truncated` when more matched.
+ *
+ * @public
+ */
+export declare const FindResult: Schema.Struct<{
+    readonly pattern: Schema.String;
+    readonly path: Schema.String;
+    readonly paths: Schema.$Array<Schema.String>;
+    readonly truncated: Schema.Boolean;
+}>;
+export type FindResult = typeof FindResult.Type;
+/** @public */
+export declare const GrepParams: Schema.Struct<{
+    readonly pattern: Schema.String;
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly glob: Schema.optionalKey<Schema.String>;
+    readonly ignoreCase: Schema.optionalKey<Schema.Boolean>;
+    readonly literal: Schema.optionalKey<Schema.Boolean>;
+    readonly context: Schema.optionalKey<Schema.Int>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+export type GrepParams = typeof GrepParams.Type;
+/**
+ * One line `grep` shows: a matching line, or (`match: false`) a line of context around one. `text` is cut to the configured width.
+ *
+ * @public
+ */
+export declare const GrepLine: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly line: Schema.Int;
+    readonly text: Schema.String;
+    readonly match: Schema.Boolean;
+}>;
+export type GrepLine = typeof GrepLine.Type;
+/**
+ * A file `grep` could not read, and why (`Permission` when access was denied); its view says why in words.
+ *
+ * @public
+ */
+export declare const GrepUnreadable: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly reason: Schema.Literals<readonly ["NotFound", "Exists", "IsDirectory", "NotDirectory", "NotEmpty", "Permission", "Invalid", "Io"]>;
+}>;
+export type GrepUnreadable = typeof GrepUnreadable.Type;
+/**
+ * What `grep` found: the matching lines (with their context) in walk order,
+ * how many lines matched and in how many files, whether it stopped at the
+ * limit, how many files it skipped (binary, larger than `maxFileBytes`, or
+ * resolving outside the workspace), and the files it could not read
+ * (`unreadable`, empty in results stored before it was recorded). `timedOut`
+ * marks an incomplete ripgrep search (false in older results). Ripgrep counts
+ * only binary skips it reports; files pruned by its walk/size limit are not counted.
+ *
+ * @public
+ */
+export declare const GrepResult: Schema.Struct<{
+    readonly pattern: Schema.String;
+    readonly path: Schema.String;
+    readonly lines: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.String;
+        readonly line: Schema.Int;
+        readonly text: Schema.String;
+        readonly match: Schema.Boolean;
+    }>>;
+    readonly matches: Schema.Int;
+    readonly files: Schema.Int;
+    readonly truncated: Schema.Boolean;
+    readonly skipped: Schema.Int;
+    readonly unreadable: Schema.withDecodingDefaultKey<Schema.$Array<Schema.Struct<{
+        readonly path: Schema.String;
+        readonly reason: Schema.Literals<readonly ["NotFound", "Exists", "IsDirectory", "NotDirectory", "NotEmpty", "Permission", "Invalid", "Io"]>;
+    }>>, never>;
+    readonly timedOut: Schema.withDecodingDefaultKey<Schema.Boolean, never>;
+}>;
+export type GrepResult = typeof GrepResult.Type;
+/**
+ * `bash`: the command, its timeout in seconds, and what to write to its standard input.
+ *
+ * @public
+ */
+export declare const BashParams: Schema.Struct<{
+    readonly command: Schema.String;
+    readonly timeout: Schema.optionalKey<Schema.Int>;
+    readonly stdin: Schema.optionalKey<Schema.String>;
+}>;
+export type BashParams = typeof BashParams.Type;
+/**
+ * How a command went: the tail of its output (stdout and stderr in the
+ * order they arrived), how it ended, and, when the output was longer than
+ * the tail, where the whole of it was saved (`fullOutput`, relative to the
+ * workspace root; null when nothing was saved). The file holds at most
+ * `maxFileBytes` of the output, its start: `fullOutputCut` when there was
+ * more, which was not saved.
+ *
+ * @public
+ */
+export declare const BashToolResult: Schema.Struct<{
+    readonly command: Schema.String;
+    readonly output: Schema.String;
+    readonly exitCode: Schema.NullOr<Schema.Int>;
+    readonly signal: Schema.NullOr<Schema.String>;
+    readonly termination: Schema.Literals<readonly ["exit", "signal", "timeout", "interrupted"]>;
+    readonly truncated: Schema.Boolean;
+    readonly totalLines: Schema.Int;
+    readonly fullOutput: Schema.NullOr<Schema.String>;
+    readonly fullOutputCut: Schema.Boolean;
+    readonly durationMs: Schema.Number;
+}>;
+export type BashToolResult = typeof BashToolResult.Type;
+/**
+ * The tools' names and schemas, for `onTool` subscriptions (a UI showing `edit` diffs, say).
+ *
+ * @public
+ */
+export declare const workspaceToolSchemas: {
+    readonly read: {
+        readonly name: "read";
+        readonly parametersSchema: Schema.Struct<{
+            readonly path: Schema.String;
+            readonly offset: Schema.optionalKey<Schema.Int>;
+            readonly limit: Schema.optionalKey<Schema.Int>;
+        }>;
+        readonly successSchema: Schema.Union<readonly [Schema.TaggedStruct<"Text", {
+            readonly path: Schema.String;
+            readonly text: Schema.String;
+            readonly firstLine: Schema.Int;
+            readonly lastLine: Schema.Int;
+            readonly totalLines: Schema.Int;
+            readonly next: Schema.NullOr<Schema.Int>;
+            readonly clipped: Schema.Boolean;
+            readonly lossy: Schema.Boolean;
+        }>, Schema.TaggedStruct<"Binary", {
+            readonly path: Schema.String;
+            readonly bytes: Schema.Int;
+            readonly mediaType: Schema.NullOr<Schema.String>;
+        }>, Schema.TaggedStruct<"Image", {
+            readonly path: Schema.String;
+            readonly image: Schema.Struct<{
+                readonly type: Schema.Literal<"media">;
+                readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                readonly data: Schema.String;
+                readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                readonly bytes: Schema.Int;
+                readonly name: Schema.optionalKey<Schema.String>;
+                readonly alt: Schema.optionalKey<Schema.String>;
+            }>;
+            /** Source dimensions and size when a resizer supplied the returned image; no original image bytes. */
+            readonly original: Schema.optionalKey<Schema.Struct<{
+                readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                readonly bytes: Schema.Int;
+                readonly width: Schema.Int;
+                readonly height: Schema.Int;
+            }>>;
+        }>, Schema.TaggedStruct<"ImageRejected", {
+            readonly path: Schema.String;
+            readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+            readonly bytes: Schema.Int;
+            readonly reason: Schema.Literals<readonly ["Empty", "InvalidBase64", "UnsupportedType", "TooLarge", "TooManyPixels", "Unreadable", "TooMany", "TooLargeTogether"]>;
+            readonly message: Schema.String;
+        }>]>;
+    };
+    readonly write: {
+        readonly name: "write";
+        readonly parametersSchema: Schema.Struct<{
+            readonly path: Schema.String;
+            readonly content: Schema.String;
+        }>;
+        readonly successSchema: Schema.Struct<{
+            readonly path: Schema.String;
+            readonly bytes: Schema.Int;
+            readonly created: Schema.Boolean;
+        }>;
+    };
+    readonly edit: {
+        readonly name: "edit";
+        readonly parametersSchema: Schema.Struct<{
+            readonly path: Schema.String;
+            readonly edits: Schema.NonEmptyArray<Schema.Struct<{
+                readonly oldText: Schema.String;
+                readonly newText: Schema.String;
+            }>>;
+        }>;
+        readonly successSchema: Schema.Struct<{
+            readonly path: Schema.String;
+            readonly replaced: Schema.Int;
+            readonly normalized: Schema.Boolean;
+            readonly firstChangedLine: Schema.Int;
+            readonly diff: Schema.String;
+        }>;
+    };
+    readonly ls: {
+        readonly name: "ls";
+        readonly parametersSchema: Schema.Struct<{
+            readonly path: Schema.optionalKey<Schema.String>;
+            readonly limit: Schema.optionalKey<Schema.Int>;
+        }>;
+        readonly successSchema: Schema.Struct<{
+            readonly path: Schema.String;
+            readonly entries: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+                readonly kind: Schema.Literals<readonly ["file", "directory", "symlink", "other"]>;
+            }>>;
+            readonly total: Schema.Int;
+        }>;
+    };
+    readonly find: {
+        readonly name: "find";
+        readonly parametersSchema: Schema.Struct<{
+            readonly pattern: Schema.String;
+            readonly path: Schema.optionalKey<Schema.String>;
+            readonly limit: Schema.optionalKey<Schema.Int>;
+        }>;
+        readonly successSchema: Schema.Struct<{
+            readonly pattern: Schema.String;
+            readonly path: Schema.String;
+            readonly paths: Schema.$Array<Schema.String>;
+            readonly truncated: Schema.Boolean;
+        }>;
+    };
+    readonly grep: {
+        readonly name: "grep";
+        readonly parametersSchema: Schema.Struct<{
+            readonly pattern: Schema.String;
+            readonly path: Schema.optionalKey<Schema.String>;
+            readonly glob: Schema.optionalKey<Schema.String>;
+            readonly ignoreCase: Schema.optionalKey<Schema.Boolean>;
+            readonly literal: Schema.optionalKey<Schema.Boolean>;
+            readonly context: Schema.optionalKey<Schema.Int>;
+            readonly limit: Schema.optionalKey<Schema.Int>;
+        }>;
+        readonly successSchema: Schema.Struct<{
+            readonly pattern: Schema.String;
+            readonly path: Schema.String;
+            readonly lines: Schema.$Array<Schema.Struct<{
+                readonly path: Schema.String;
+                readonly line: Schema.Int;
+                readonly text: Schema.String;
+                readonly match: Schema.Boolean;
+            }>>;
+            readonly matches: Schema.Int;
+            readonly files: Schema.Int;
+            readonly truncated: Schema.Boolean;
+            readonly skipped: Schema.Int;
+            readonly unreadable: Schema.withDecodingDefaultKey<Schema.$Array<Schema.Struct<{
+                readonly path: Schema.String;
+                readonly reason: Schema.Literals<readonly ["NotFound", "Exists", "IsDirectory", "NotDirectory", "NotEmpty", "Permission", "Invalid", "Io"]>;
+            }>>, never>;
+            readonly timedOut: Schema.withDecodingDefaultKey<Schema.Boolean, never>;
+        }>;
+    };
+    readonly bash: {
+        readonly name: "bash";
+        readonly parametersSchema: Schema.Struct<{
+            readonly command: Schema.String;
+            readonly timeout: Schema.optionalKey<Schema.Int>;
+            readonly stdin: Schema.optionalKey<Schema.String>;
+        }>;
+        readonly successSchema: Schema.Struct<{
+            readonly command: Schema.String;
+            readonly output: Schema.String;
+            readonly exitCode: Schema.NullOr<Schema.Int>;
+            readonly signal: Schema.NullOr<Schema.String>;
+            readonly termination: Schema.Literals<readonly ["exit", "signal", "timeout", "interrupted"]>;
+            readonly truncated: Schema.Boolean;
+            readonly totalLines: Schema.Int;
+            readonly fullOutput: Schema.NullOr<Schema.String>;
+            readonly fullOutputCut: Schema.Boolean;
+            readonly durationMs: Schema.Number;
+        }>;
+    };
+};

package/dist/workspace-tools.entity.functions.d.ts

@@ -0,0 +1,126 @@
+import { Effect, Option, Schema } from "effect";
+import { ImageResizeError } from "@xandreed/core";
+import type { BashOptions, ImageFitTarget, ImageInput, Media } from "@xandreed/core";
+import type { BashToolResult, EditResult, FindResult, GrepResult, LsResult, ReadResult, WorkspaceSkillName, WorkspaceToolName, WorkspaceToolsConfig, WriteResult } from "./workspace-tools.entity.js";
+/** The skill each tool belongs to, by its short name. */
+export declare const skillOfTool: Readonly<Record<WorkspaceToolName, WorkspaceSkillName>>;
+/**
+ * The parameters `read`, `ls`, `find` and `grep` take under `config`: their
+ * `limit` goes up to the configured cap (`maxLines`, `lsEntries`,
+ * `findResults`, `grepMatches`), so the model is shown the real maximum and
+ * a larger one is refused rather than quietly lowered.
+ */
+export declare const toolParameters: (config: WorkspaceToolsConfig) => {
+    read: Schema.Struct<{
+        readonly limit: Schema.optionalKey<Schema.Int>;
+        readonly path: Schema.String;
+        readonly offset: Schema.optionalKey<Schema.Int>;
+    }>;
+    ls: Schema.Struct<{
+        readonly limit: Schema.optionalKey<Schema.Int>;
+        readonly path: Schema.optionalKey<Schema.String>;
+    }>;
+    find: Schema.Struct<{
+        readonly limit: Schema.optionalKey<Schema.Int>;
+        readonly pattern: Schema.String;
+        readonly path: Schema.optionalKey<Schema.String>;
+    }>;
+    grep: Schema.Struct<{
+        readonly limit: Schema.optionalKey<Schema.Int>;
+        readonly pattern: Schema.String;
+        readonly path: Schema.optionalKey<Schema.String>;
+        readonly glob: Schema.optionalKey<Schema.String>;
+        readonly ignoreCase: Schema.optionalKey<Schema.Boolean>;
+        readonly literal: Schema.optionalKey<Schema.Boolean>;
+        readonly context: Schema.optionalKey<Schema.Int>;
+    }>;
+};
+/** What the model is told each tool does, with the configured limits in it. */
+export declare const toolDescriptions: (config: WorkspaceToolsConfig, resizesImages?: boolean) => Readonly<Record<WorkspaceToolName, string>>;
+/** The text of the `workspace.environment` section: where the workspace is and how the enabled tools behave there. */
+export declare const environmentText: (root: string, config: WorkspaceToolsConfig, tools: ReadonlyArray<WorkspaceToolName>) => string;
+/**
+ * The environment of a command the bash tool runs: the configured
+ * variables, the session's when `bashSessionEnv` is set, and the parent
+ * environment through the allowlist (or all of it with `bashInheritEnv`).
+ */
+export declare const bashEnvironment: (config: WorkspaceToolsConfig, session: Option.Option<{
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly workspace: string;
+}>) => Pick<BashOptions, "env" | "inheritEnv">;
+/**
+ * What `read` returns for a binary file (a NUL byte in its first 8 KB).
+ * With `readImages`, bytes that are a PNG, JPEG, GIF or WebP image (sniffed,
+ * whatever the name says) become an `Image` through `mediaFromBytes`, named
+ * by the path; an image it refuses (over `MEDIA_LIMITS.imageBytes`, over
+ * `MEDIA_LIMITS.maxPixels` a side, or a header without a size) is an
+ * `ImageRejected` note, without the bytes. Anything else is `Binary`, with
+ * `nameType`: the media type the name suggests, as the result carries it
+ * (`null` for none; the adapter reads it with `mediaTypeOf`).
+ */
+type FitImage = (image: ImageInput, target: ImageFitTarget) => Effect.Effect<Uint8Array, ImageResizeError>;
+export declare const binaryRead: (path: string, bytes: Uint8Array<ArrayBufferLike>, readImages: boolean, nameType: string | null, fit?: Option.Option<FitImage> | undefined, maxSide?: number | undefined) => Effect.Effect<{
+    readonly _tag: "Text";
+    readonly path: string;
+    readonly text: string;
+    readonly firstLine: number;
+    readonly lastLine: number;
+    readonly totalLines: number;
+    readonly next: number | null;
+    readonly clipped: boolean;
+    readonly lossy: boolean;
+} | {
+    readonly _tag: "Binary";
+    readonly path: string;
+    readonly bytes: number;
+    readonly mediaType: string | null;
+} | {
+    readonly _tag: "Image";
+    readonly path: string;
+    readonly image: {
+        readonly type: "media";
+        readonly mediaType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+        readonly data: string;
+        readonly fingerprint: string & import("effect/Brand").Brand<"MediaFingerprint">;
+        readonly bytes: number;
+        readonly name?: string;
+        readonly alt?: string;
+    };
+    readonly original?: {
+        readonly mediaType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+        readonly bytes: number;
+        readonly width: number;
+        readonly height: number;
+    };
+} | {
+    readonly _tag: "ImageRejected";
+    readonly path: string;
+    readonly mediaType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+    readonly bytes: number;
+    readonly reason: "Empty" | "InvalidBase64" | "UnsupportedType" | "TooLarge" | "TooManyPixels" | "Unreadable" | "TooMany" | "TooLargeTogether";
+    readonly message: string;
+}, never, never>;
+/**
+ * What the model can do about a file over `maxFileBytes`, which `read`
+ * refuses unread: with `readImages`, a file named as a PNG, JPEG, GIF or
+ * WebP image is told to read a smaller copy; any other to read parts of it.
+ */
+export declare const fileTooLargeHint: (path: string, readImages: boolean) => string;
+/** The images `read`'s view sends with its result: an `Image`'s, once. */
+export declare const readMedia: (result: ReadResult) => ReadonlyArray<Media>;
+export declare const renderRead: (result: ReadResult) => string;
+export declare const compactRead: (result: ReadResult) => string;
+export declare const renderWrite: (result: WriteResult) => string;
+export declare const compactWrite: (result: WriteResult) => string;
+export declare const renderEdit: (result: EditResult) => string;
+export declare const compactEdit: (result: EditResult) => string;
+export declare const renderLs: (result: LsResult) => string;
+export declare const compactLs: (result: LsResult) => string;
+export declare const renderFind: (result: FindResult, maxLines: number, maxBytes: number) => string;
+export declare const compactFind: (result: FindResult) => string;
+export declare const renderGrep: (result: GrepResult, withContext: boolean, maxLines: number, maxBytes: number) => string;
+export declare const compactGrep: (result: GrepResult) => string;
+export declare const renderBash: (result: BashToolResult) => string;
+export declare const compactBash: (result: BashToolResult) => string;
+export {};