@xandreed/plugin-workspace 0.0.0-stage → 0.14.0

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

@@ -0,0 +1,433 @@
+import { Schema } from "effect";
+/** The seven workspace tools, by the names the model calls them. */
+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).
+ */
+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`. */
+export declare const WORKSPACE_PERMISSIONS: {
+    readonly write: "fs.write";
+    readonly exec: "shell.exec";
+};
+/**
+ * How `workspaceToolsPlugin` (and `workspaceTools`) works on the workspace,
+ * `SessionEnvironment.workspace`. Flat: plugin defaults merge one level deep.
+ *
+ * - `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.
+ * - `confine`: refuse paths whose real location (links resolved, through the
+ *   nearest ancestor that exists) is outside the workspace root.
+ * - `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`: lines are cut to this many characters before `grep`
+ *   matches them, and shown cut.
+ * - `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.
+ * - `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.
+ */
+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 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 maxFileBytes: Schema.Int;
+    readonly readImages: Schema.Boolean;
+    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;
+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). */
+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.
+ */
+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>;
+    }>;
+}>, 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;
+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. */
+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`. */
+export declare const TextEdit: Schema.Struct<{
+    readonly oldText: Schema.String;
+    readonly newText: Schema.String;
+}>;
+export type TextEdit = typeof TextEdit.Type;
+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).
+ */
+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;
+export declare const LsParams: Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+export type LsParams = typeof LsParams.Type;
+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. */
+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;
+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. */
+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;
+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. */
+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;
+/**
+ * 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, and how many files it skipped (binary, larger than `maxFileBytes`,
+ * or resolving outside the workspace).
+ */
+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;
+}>;
+export type GrepResult = typeof GrepResult.Type;
+/** `bash`: the command, its timeout in seconds, and what to write to its standard input. */
+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.
+ */
+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). */
+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>;
+            }>;
+        }>, 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 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,51 @@
+import { Effect, Option } from "effect";
+import type { BashOptions, 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>>;
+/** What the model is told each tool does, with the configured limits in it. */
+export declare const toolDescriptions: (config: WorkspaceToolsConfig) => 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
+ * the media type the name suggests.
+ */
+export declare const binaryRead: (path: string, bytes: Uint8Array, readImages: boolean) => Effect.Effect<ReadResult>;
+/**
+ * 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;

package/dist/workspace-tools.entity.functions.js

@@ -0,0 +1,124 @@
+import { Effect, Match, Option, Schema } from "effect";
+import { ImageMediaType, MEDIA_LIMITS, mediaFromBytes, sniffImageType } from "@xandreed/core";
+import { renderSearchLines } from "./text-search.entity.functions.js";
+import { formatBytes, headLines, mediaTypeOf } from "./text-window.entity.functions.js";
+export const skillOfTool = {
+  read: "read",
+  ls: "read",
+  find: "read",
+  grep: "read",
+  write: "edit",
+  edit: "edit",
+  bash: "shell"
+};
+const seconds = (ms) => `${Math.round(ms / 1000)} s`, imageLimit = (config) => {
+  const bytes = Math.min(MEDIA_LIMITS.imageBytes, config.maxFileBytes);
+  return bytes < 1048576 ? `${Math.floor(bytes * 100 / 1024) / 100} KB` : `${Math.floor(bytes * 100 / 1048576) / 100} MB`;
+}, listed = (names) => names.length === 0 ? "nothing" : names.join(", ");
+export const toolDescriptions = (config) => ({
+  read: `Read a text file of the workspace${config.readImages ? ", or look at an image" : ""}. Shows at most ${config.maxLines} lines or ${formatBytes(config.maxBytes)} at a time; when more is left, the result says which offset to continue from. offset is the first line to show (1-based), limit how many lines. ${config.readImages ? `A PNG, JPEG, GIF or WebP image (up to ${imageLimit(config)} and ${MEDIA_LIMITS.maxPixels} pixels a side) is returned as an image you can see; another binary file is reported, not shown.` : "A binary file is reported, not shown."} To see a directory, use ls.`,
+  write: "Create a file, or replace all of an existing one, with content; missing directories are created. To change part of a file, use edit. Emptying a non-empty file is refused.",
+  edit: "Change part of a file by replacing exact text. Each edit's oldText must appear exactly once in the file: copy it from read (without the notice lines), with enough surrounding lines to be unique. All edits are matched against the file as it was before this call and must not overlap; newText replaces oldText (empty to delete it). Line endings and a byte-order mark are kept.",
+  ls: `List a directory (by default the workspace root): one entry per line, directories ending in /, symbolic links in @. At most ${config.lsEntries} entries.`,
+  find: `Find files whose path matches a glob pattern, relative to path (by default the workspace root): * and ? match within a name, ** any number of directories, {a,b} either; e.g. **/*.ts or src/**/test_*.py. Never looks inside ${listed(config.exclude)} or symbolic links. At most ${config.findResults} paths.`,
+  grep: `Search file contents for a regular expression (JavaScript syntax), or for plain text with literal: true. path is a file or a directory (by default the workspace root); glob limits the files searched (*.ts searches every directory). Shows path:line:text for each matching line, and context lines around each match when asked. Lines are cut to ${config.grepLineChars} characters before matching. At most ${config.grepMatches} matching lines; binary files, ${listed(config.exclude)} and symbolic links are skipped.`,
+  bash: `Run a shell command with bash -c in the workspace root. timeout is in seconds (default ${seconds(config.bashTimeoutMs)}, at most ${seconds(config.bashMaxTimeoutMs)}); stdin is written to the command's standard input. Returns the exit code and the output, stdout and stderr in the order they came. Output longer than ${config.maxLines} lines or ${formatBytes(config.maxBytes)} is cut to its end${config.spillDir === null ? "" : `, and the whole of it (up to ${formatBytes(config.maxFileBytes)}) is saved to a file you can read`}. A non-zero exit code is a result to read, not a failure. Anything the command leaves running may be stopped when it returns.`
+}), environmentText = (root, config, tools) => {
+  const has = (tool) => tools.includes(tool);
+  return [
+    "## Workspace",
+    `The workspace is ${root}. Give paths relative to it${config.confine ? "; the tools refuse paths that lead outside it." : "."}`,
+    ...has("read") ? [`read shows a file ${config.maxLines} lines or ${formatBytes(config.maxBytes)} at a time; continue with the offset it gives.`] : [],
+    ...has("find") || has("grep") ? [`find and grep never look inside ${listed(config.exclude)}.`] : [],
+    ...has("edit") ? ["edit replaces exact text: read the file first and copy the text to change from it."] : [],
+    ...has("write") || has("edit") ? [config.protect.length === 0 ? "" : `write and edit leave ${listed(config.protect)} alone.`] : [],
+    ...has("bash") ? [`bash runs commands in the workspace root with a ${seconds(config.bashTimeoutMs)} timeout.${config.spillDir === null ? "" : " When their output is cut, the whole of it is saved to a file under " + config.spillDir + " that read can open."}`] : []
+  ].filter((line) => line.length > 0).join(`
+`);
+}, bashEnvironment = (config, session) => ({
+  env: {
+    ...config.bashSessionEnv ? Option.match(session, {
+      onNone: () => ({}),
+      onSome: (run) => ({ EFFERENT_SESSION_ID: run.sessionId, EFFERENT_RUN_ID: run.runId, EFFERENT_WORKSPACE: run.workspace })
+    }) : {},
+    ...config.bashEnv
+  },
+  inheritEnv: config.bashInheritEnv ? !0 : config.bashEnvAllow
+}), binaryRead = (path, bytes, readImages) => Option.match(readImages ? sniffImageType(bytes) : Option.none(), {
+  onNone: () => Effect.succeed({ _tag: "Binary", path, bytes: bytes.length, mediaType: Option.getOrNull(mediaTypeOf(path)) }),
+  onSome: (mediaType) => mediaFromBytes(bytes, { name: path }).pipe(Effect.match({
+    onSuccess: (image) => ({ _tag: "Image", path, image }),
+    onFailure: (rejected) => ({ _tag: "ImageRejected", path, mediaType, bytes: bytes.length, reason: rejected.reason, message: rejected.message })
+  }))
+}), fileTooLargeHint = (path, readImages) => readImages && Option.exists(mediaTypeOf(path), Schema.is(ImageMediaType)) ? "to see it, make a smaller copy with bash (scaled down or recompressed) and read that" : "use grep to find lines in it, or bash (head, tail, sed -n) for parts of it", readMedia = (result) => Match.valueTags(result, {
+  Text: () => [],
+  Binary: () => [],
+  Image: (read) => [read.image],
+  ImageRejected: () => []
+});
+const rejectedHint = {
+  TooLarge: " To see it, make a smaller copy with bash (scaled down or recompressed) and read that.",
+  TooManyPixels: " To see it, make a smaller copy with bash (scaled down) and read that.",
+  Unreadable: " The file may be damaged or cut short.",
+  Empty: "",
+  InvalidBase64: "",
+  UnsupportedType: "",
+  TooMany: "",
+  TooLargeTogether: ""
+};
+export const renderRead = (result) => Match.valueTags(result, {
+  Binary: (binary) => `[${binary.path} is a binary file (${formatBytes(binary.bytes)}${binary.mediaType === null ? "" : `, ${binary.mediaType}`}); it cannot be shown as text.]`,
+  Image: (read) => `[Image ${read.path} (${read.image.mediaType}, ${formatBytes(read.image.bytes)}).]`,
+  ImageRejected: (read) => `[${read.path} is an image (${read.mediaType}, ${formatBytes(read.bytes)}) that read cannot show: ${read.message}.${rejectedHint[read.reason]}]`,
+  Text: (text) => text.totalLines === 0 ? `[${text.path} is empty.]` : [
+    text.text,
+    ...text.clipped ? [`[Line ${text.firstLine} is longer than the window; only its start is shown. Use bash (cut, head -c) to see the rest.]`] : [],
+    ...text.lossy ? [`[${text.path} is not valid UTF-8: bytes that are not show as \uFFFD. edit refuses such a file; change it with bash.]`] : [],
+    ...text.next === null ? [] : [`[Showing lines ${text.firstLine}-${text.lastLine} of ${text.totalLines}. Use offset=${text.next} to continue.]`]
+  ].join(`
+`)
+}), compactRead = (result) => Match.valueTags(result, {
+  Binary: (binary) => `(read ${binary.path}: binary, ${formatBytes(binary.bytes)})`,
+  Image: (read) => `(read ${read.path}: ${read.image.mediaType} image, ${formatBytes(read.image.bytes)})`,
+  ImageRejected: (read) => `(read ${read.path}: ${read.mediaType} image not shown, ${read.reason})`,
+  Text: (text) => `(read ${text.path}: lines ${text.firstLine}-${text.lastLine} of ${text.totalLines})`
+}), renderWrite = (result) => `${result.created ? "Created" : "Replaced"} ${result.path} (${formatBytes(result.bytes)}).`, compactWrite = (result) => `(${result.created ? "created" : "replaced"} ${result.path}: ${formatBytes(result.bytes)})`, renderEdit = (result) => `Replaced ${result.replaced} block${result.replaced === 1 ? "" : "s"} in ${result.path}; the first change is at line ${result.firstChangedLine}.${result.normalized ? " Some text matched only once whitespace and quotes were normalised: read the changed lines to check them." : ""}`, compactEdit = (result) => `(edited ${result.path}: ${result.replaced} block${result.replaced === 1 ? "" : "s"} from line ${result.firstChangedLine})`;
+const lsSuffix = { file: "", directory: "/", symlink: "@", other: "" };
+export const renderLs = (result) => result.total === 0 ? `[${result.path} is empty.]` : [
+  ...result.entries.map((entry) => `${entry.name}${lsSuffix[entry.kind]}`),
+  ...result.entries.length < result.total ? [`[Showing ${result.entries.length} of ${result.total} entries. Use find with a pattern to narrow them down.]`] : []
+].join(`
+`), compactLs = (result) => `(listed ${result.path}: ${result.total} entries)`, renderFind = (result, maxLines, maxBytes) => {
+  if (result.paths.length === 0)
+    return `No files under ${result.path} match ${result.pattern}.`;
+  const head = headLines(result.paths, maxLines, maxBytes);
+  return [
+    ...head.lines,
+    ...head.omitted > 0 ? [`[${head.omitted} more paths not shown. Narrow the pattern or the path.]`] : result.truncated ? [`[Stopped at ${result.paths.length} paths; there are more. Narrow the pattern or the path.]`] : []
+  ].join(`
+`);
+}, compactFind = (result) => `(find ${result.pattern} in ${result.path}: ${result.paths.length}${result.truncated ? "+" : ""} paths)`, renderGrep = (result, withContext, maxLines, maxBytes) => {
+  const skipped = result.skipped === 0 ? [] : [`[${result.skipped} file${result.skipped === 1 ? "" : "s"} skipped: binary, larger than the read limit, or leading outside the workspace.]`];
+  if (result.matches === 0)
+    return [`No matches for ${result.pattern} in ${result.path}.`, ...skipped].join(`
+`);
+  const head = headLines(renderSearchLines(result.lines, withContext), maxLines, maxBytes);
+  return [
+    ...head.lines,
+    ...head.omitted > 0 ? [`[${head.omitted} more lines not shown. Narrow the pattern or the path.]`] : [],
+    ...result.truncated ? [`[Stopped at ${result.matches} matching lines; there are more. Narrow the pattern or the path, or raise limit.]`] : [],
+    ...skipped
+  ].join(`
+`);
+}, compactGrep = (result) => `(grep ${result.pattern} in ${result.path}: ${result.matches}${result.truncated ? "+" : ""} matching lines in ${result.files} files)`;
+const endOf = (result) => result.termination === "timeout" ? `[The command was killed after ${result.durationMs < 1e4 ? `${(result.durationMs / 1000).toFixed(1)} s` : seconds(result.durationMs)}, at its timeout.]` : result.termination === "interrupted" ? "[The command was stopped before it finished.]" : result.termination === "signal" ? `[The command was killed by ${result.signal ?? "a signal"}.]` : `[Exit code ${result.exitCode ?? "unknown"}.]`, cutOf = (result) => {
+  const shownLines = result.output.length === 0 ? 0 : result.output.split(`
+`).length, what = shownLines < result.totalLines ? `Output cut to its last ${shownLines} of ${result.totalLines} lines.` : "Output cut: only the end of its last line is shown.", saved = result.fullOutput === null ? "" : result.fullOutputCut ? ` Only its start was saved, in ${result.fullOutput}: the output grew past the size read opens, and the rest was not kept. Read the file with offset to see that start; to see the rest, run the command again with its output filtered (grep, tail, sed -n).` : ` The whole output is in ${result.fullOutput}; read it with offset to see the rest.`;
+  return `[${what}${saved}]`;
+};
+export const renderBash = (result) => [
+  ...result.output.length === 0 ? ["(no output)"] : [result.output],
+  ...result.truncated ? [cutOf(result)] : [],
+  endOf(result)
+].join(`
+`), compactBash = (result) => `(ran ${result.command.length > 80 ? `${result.command.slice(0, 80)}\u2026` : result.command}: ${result.termination === "exit" ? `exit ${result.exitCode ?? "?"}` : result.termination}${result.fullOutput === null ? "" : `; output in ${result.fullOutput}`})`;

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

@@ -0,0 +1 @@
+export {};