@xandreed/core 0.13.0 → 0.14.0

package/README.md

@@ -1,5 +1,5 @@
 # @xandreed/core
 
-Efferent composable agent framework, 0.13.0. Node 24 or Bun.
+Efferent composable agent framework, 0.14.0. Node 24 or Bun.
 
 Documentation: https://github.com/xandreeddev/efferent

package/dist/conformance.functions.d.ts

@@ -0,0 +1,34 @@
+import { Effect, Option } from "effect";
+import type { Fiber } from "effect";
+import { ConformanceFailure } from "./conformance.entity.js";
+import type { ConformanceCheck } from "./conformance.entity.js";
+import { ConversationId } from "./domain/message.entity.js";
+import type { TokenUsage } from "./domain/token-usage.entity.js";
+import type { SessionHeader, SessionLogEvent } from "./session/session-log.entity.js";
+export declare const fail: (check: string, message: string) => Effect.Effect<never, ConformanceFailure, never>;
+export declare const expect: (check: string, holds: boolean, message: string) => Effect.Effect<void, ConformanceFailure>;
+/** Two usages with every count equal. */
+export declare const sameUsage: (a: TokenUsage, b: TokenUsage) => boolean;
+/** A 1x1 PNG, as base64: the image the kits attach. */
+export declare const pixelPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
+/** Each event as `kind@turn` (`kind` alone outside a turn), joined. */
+export declare const kindsOf: (events: ReadonlyArray<SessionLogEvent>) => string;
+/** Whether `fiber` completes within a few turns of the scheduler (an `idle` that should be settled). */
+export declare const settles: (fiber: Fiber.Fiber<unknown, unknown>, tries?: number) => Effect.Effect<boolean>;
+/** Read `value` until `holds`, letting other fibers run in between; the last value read. */
+export declare const eventually: <A>(value: Effect.Effect<A>, holds: (a: A) => boolean, tries?: number) => Effect.Effect<A>;
+/** A fresh id per session, so a kit can run against a shared store. */
+export declare const freshId: Effect.Effect<string & import("effect/Brand").Brand<"ConversationId">, never, never>;
+export declare const headerOf: (id: ConversationId, owner: string, parent?: Option.Option<{
+    readonly id: ConversationId;
+    readonly through: number;
+    readonly turnAtFork: number;
+}>) => SessionHeader;
+/**
+ * One check run under a fresh owner. A failure the body did not raise as a
+ * `ConformanceFailure` (a port's own error, a defect-free typed failure) is
+ * reported under `id` as unexpected, with its tag.
+ */
+export declare const check: (name: string, id: string, body: (owner: string) => Effect.Effect<void, unknown>) => ConformanceCheck;
+/** Run `effect` with the wall clock stopped at `at`. */
+export declare const atTime: (at: number) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;

package/dist/conformance.functions.js

@@ -0,0 +1,25 @@
+import { Clock, Effect, Option } from "effect";
+import { ConformanceFailure } from "./conformance.entity.js";
+import { ConversationId } from "./domain/message.entity.js";
+import { zeroUsage } from "./domain/token-usage.entity.functions.js";
+export const fail = (check, message) => Effect.fail(new ConformanceFailure({ check, message })), expect = (check, holds, message) => holds ? Effect.void : fail(check, message), sameUsage = (a, b) => Object.keys(zeroUsage).every((key) => a[key] === b[key]), pixelPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", kindsOf = (events) => events.map((event) => `${event.kind}${Option.match(event.turn, { onNone: () => "", onSome: (turn) => `@${turn}` })}`).join(), settles = (fiber, tries = 50) => fiber.pollUnsafe() !== void 0 ? Effect.succeed(!0) : tries <= 0 ? Effect.succeed(!1) : Effect.yieldNow.pipe(Effect.andThen(Effect.suspend(() => settles(fiber, tries - 1)))), eventually = (value, holds, tries = 200) => value.pipe(Effect.flatMap((now) => holds(now) || tries <= 0 ? Effect.succeed(now) : Effect.yieldNow.pipe(Effect.andThen(Effect.suspend(() => eventually(value, holds, tries - 1)))))), freshId = Effect.sync(() => ConversationId.make(crypto.randomUUID())), headerOf = (id, owner, parent = Option.none()) => ({
+  id,
+  owner,
+  origin: "user",
+  createdAt: 1767225600000,
+  meta: { title: "conformance", nested: { list: [1, "two", null] } },
+  parent
+}), check = (name, id, body) => ({
+  name,
+  run: freshId.pipe(Effect.flatMap((owner) => body(`owner-${owner}`)), Effect.catch((error) => error instanceof ConformanceFailure ? Effect.fail(error) : fail(id, `unexpected ${typeof error === "object" && error !== null && "_tag" in error ? String(error._tag) : "error"}: ${JSON.stringify(error)}`)))
+});
+const stoppedAt = (at, clock) => ({
+  currentTimeMillisUnsafe: () => at,
+  currentTimeMillis: Effect.succeed(at),
+  currentTimeNanosUnsafe: () => BigInt(at) * 1000000n,
+  currentTimeNanos: Effect.succeed(BigInt(at) * 1000000n),
+  monotonicTimeNanosUnsafe: () => clock.monotonicTimeNanosUnsafe(),
+  monotonicTimeNanos: Effect.sync(() => clock.monotonicTimeNanosUnsafe()),
+  sleep: (duration) => clock.sleep(duration)
+});
+export const atTime = (at) => (effect) => Clock.clockWith((clock) => Effect.provideService(effect, Clock.Clock, stoppedAt(at, clock)));

package/dist/domain/bash.entity.d.ts

@@ -0,0 +1,82 @@
+import { Schema } from "effect";
+/**
+ * The parent environment a command inherits by default: these names, and
+ * every name a trailing `*` prefixes. Provider keys and other host secrets
+ * stay out unless a host passes them in `env` or widens `inheritEnv`.
+ */
+export declare const BASH_ENV_ALLOWLIST: ReadonlyArray<string>;
+/**
+ * How a command runs. `cwd` is an absolute directory that must exist.
+ * `env` is set over what is inherited; `inheritEnv` says what is inherited
+ * from the parent environment: `true` everything, `false` nothing, or an
+ * allowlist of names where a trailing `*` matches a prefix (default
+ * `BASH_ENV_ALLOWLIST`). `stdin` (text, written as UTF-8, or bytes) is
+ * written to the command's standard input, which is then closed (without it, the command reads end-of-file at
+ * once). After `timeoutMs` the command's whole process group is killed.
+ */
+export declare const BashOptions: Schema.Struct<{
+    readonly cwd: Schema.String;
+    readonly env: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly inheritEnv: Schema.optionalKey<Schema.Union<readonly [Schema.Boolean, Schema.$Array<Schema.String>]>>;
+    readonly stdin: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Uint8Array]>>;
+    readonly timeoutMs: Schema.optionalKey<Schema.Int>;
+}>;
+export type BashOptions = typeof BashOptions.Type;
+/**
+ * How a command ended: it exited (`exit`), a signal killed it (`signal`),
+ * it ran past `timeoutMs` and was killed (`timeout`), or its caller stopped
+ * the stream before it ended and it was killed (`interrupted`, which only
+ * `collectBashResult` can see).
+ */
+export declare const BashTermination: Schema.Literals<readonly ["exit", "signal", "timeout", "interrupted"]>;
+export type BashTermination = typeof BashTermination.Type;
+/**
+ * Why a command could not run: the shell could not be spawned
+ * (`SpawnFailed`), `cwd` does not exist or is not a directory
+ * (`CwdMissing`), or the shell is not installed (`ShellMissing`). A command
+ * that runs and fails is a result, never a `BashError`.
+ */
+export declare const BashErrorReason: Schema.Literals<readonly ["SpawnFailed", "CwdMissing", "ShellMissing"]>;
+export type BashErrorReason = typeof BashErrorReason.Type;
+declare const BashError_base: Schema.Class<BashError, Schema.TaggedStruct<"BashError", {
+    readonly reason: Schema.Literals<readonly ["SpawnFailed", "CwdMissing", "ShellMissing"]>;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class BashError extends BashError_base {
+}
+/** Output as it arrives, decoded as UTF-8 per stream (a character split between reads arrives whole). */
+export declare const BashChunk: Schema.TaggedStruct<"BashChunk", {
+    readonly stream: Schema.Literals<readonly ["stdout", "stderr"]>;
+    readonly text: Schema.String;
+}>;
+export type BashChunk = typeof BashChunk.Type;
+/** The end of a command: its exit code when it exited, the signal when one killed it, how long it ran. */
+export declare const BashExit: Schema.TaggedStruct<"BashExit", {
+    readonly termination: Schema.Literals<readonly ["exit", "signal", "timeout", "interrupted"]>;
+    readonly exitCode: Schema.OptionFromNullOr<Schema.Int>;
+    readonly signal: Schema.OptionFromNullOr<Schema.String>;
+    readonly durationMs: Schema.Number;
+}>;
+export type BashExit = typeof BashExit.Type;
+/** What `Bash.stream` emits: chunks as they come, then exactly one `BashExit`, last. */
+export declare const BashEvent: Schema.Union<readonly [Schema.TaggedStruct<"BashChunk", {
+    readonly stream: Schema.Literals<readonly ["stdout", "stderr"]>;
+    readonly text: Schema.String;
+}>, Schema.TaggedStruct<"BashExit", {
+    readonly termination: Schema.Literals<readonly ["exit", "signal", "timeout", "interrupted"]>;
+    readonly exitCode: Schema.OptionFromNullOr<Schema.Int>;
+    readonly signal: Schema.OptionFromNullOr<Schema.String>;
+    readonly durationMs: Schema.Number;
+}>]>;
+export type BashEvent = typeof BashEvent.Type;
+/** A whole command's output and end (`Bash.exec`). A non-zero exit is a result like any other. */
+export declare const BashResult: Schema.Struct<{
+    readonly stdout: Schema.String;
+    readonly stderr: Schema.String;
+    readonly exitCode: Schema.OptionFromNullOr<Schema.Int>;
+    readonly signal: Schema.OptionFromNullOr<Schema.String>;
+    readonly termination: Schema.Literals<readonly ["exit", "signal", "timeout", "interrupted"]>;
+    readonly durationMs: Schema.Number;
+}>;
+export type BashResult = typeof BashResult.Type;
+export {};

package/dist/domain/bash.entity.functions.d.ts

@@ -0,0 +1,17 @@
+import { Effect, Stream } from "effect";
+import type { BashError, BashEvent, BashOptions, BashResult } from "./bash.entity.js";
+/**
+ * The environment a command gets: the parent's variables `inheritEnv`
+ * admits (all, none, or an allowlist where a trailing `*` matches a prefix;
+ * `BASH_ENV_ALLOWLIST` by default), then `env` over them. Unset parent
+ * variables are skipped. Every `Bash` adapter builds the environment with
+ * this, so the allowlist means the same everywhere.
+ */
+export declare const resolveBashEnv: (parent: Readonly<Record<string, string | undefined>>, options: Pick<BashOptions, "env" | "inheritEnv">) => Readonly<Record<string, string>>;
+/**
+ * A command's events folded into its result: `Bash.exec` is this over
+ * `Bash.stream`. A stream that ends without its `BashExit` (its consumer
+ * cut it short, e.g. with `Stream.interruptWhen`, and the adapter killed
+ * the command) gives `termination: "interrupted"` with the output so far.
+ */
+export declare const collectBashResult: <R>(events: Stream.Stream<BashEvent, BashError, R>) => Effect.Effect<BashResult, BashError, R>;

package/dist/domain/bash.entity.functions.js

@@ -0,0 +1,26 @@
+import { Clock, Effect, Option, Stream } from "effect";
+import { BASH_ENV_ALLOWLIST } from "./bash.entity.js";
+export const resolveBashEnv = (parent, options) => {
+  const inherit = options.inheritEnv ?? BASH_ENV_ALLOWLIST, admitted = (name) => typeof inherit === "boolean" ? inherit : inherit.some((entry) => entry.endsWith("*") ? name.startsWith(entry.slice(0, -1)) : name === entry), inherited = Object.entries(parent).flatMap(([name, value]) => value !== void 0 && admitted(name) ? [[name, value]] : []);
+  return { ...Object.fromEntries(inherited), ...options.env };
+}, collectBashResult = (events) => Effect.gen(function* () {
+  const started = yield* Clock.currentTimeMillis, collected = yield* Stream.runFold(events, () => ({ stdout: "", stderr: "", exit: Option.none() }), (state, event) => event._tag === "BashExit" ? { ...state, exit: Option.some(event) } : event.stream === "stdout" ? { ...state, stdout: state.stdout + event.text } : { ...state, stderr: state.stderr + event.text }), ended = yield* Clock.currentTimeMillis;
+  return Option.match(collected.exit, {
+    onNone: () => ({
+      stdout: collected.stdout,
+      stderr: collected.stderr,
+      exitCode: Option.none(),
+      signal: Option.none(),
+      termination: "interrupted",
+      durationMs: ended - started
+    }),
+    onSome: (exit) => ({
+      stdout: collected.stdout,
+      stderr: collected.stderr,
+      exitCode: exit.exitCode,
+      signal: exit.signal,
+      termination: exit.termination,
+      durationMs: exit.durationMs
+    })
+  });
+});

package/dist/domain/bash.entity.functions.test.d.ts

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

package/dist/domain/bash.entity.js

@@ -0,0 +1,30 @@
+import { Schema } from "effect";
+export const BASH_ENV_ALLOWLIST = ["PATH", "HOME", "USER", "LOGNAME", "LANG", "LC_*", "TERM", "SHELL", "TMPDIR", "TZ"], BashOptions = Schema.Struct({
+  cwd: Schema.String,
+  env: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+  inheritEnv: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Array(Schema.String)])),
+  stdin: Schema.optionalKey(Schema.Union([Schema.String, Schema.Uint8Array])),
+  timeoutMs: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)))
+}), BashTermination = Schema.Literals(["exit", "signal", "timeout", "interrupted"]), BashErrorReason = Schema.Literals(["SpawnFailed", "CwdMissing", "ShellMissing"]);
+
+export class BashError extends Schema.TaggedError()("BashError", {
+  reason: BashErrorReason,
+  message: Schema.String
+}) {
+}
+export const BashChunk = Schema.TaggedStruct("BashChunk", {
+  stream: Schema.Literals(["stdout", "stderr"]),
+  text: Schema.String
+}), BashExit = Schema.TaggedStruct("BashExit", {
+  termination: BashTermination,
+  exitCode: Schema.OptionFromNullOr(Schema.Int),
+  signal: Schema.OptionFromNullOr(Schema.String),
+  durationMs: Schema.Number
+}), BashEvent = Schema.Union([BashChunk, BashExit]), BashResult = Schema.Struct({
+  stdout: Schema.String,
+  stderr: Schema.String,
+  exitCode: Schema.OptionFromNullOr(Schema.Int),
+  signal: Schema.OptionFromNullOr(Schema.String),
+  termination: BashTermination,
+  durationMs: Schema.Number
+});

package/dist/domain/file-system.entity.d.ts

@@ -0,0 +1,91 @@
+import { Schema } from "effect";
+/**
+ * Why a file-system call failed, the same on every backend:
+ * - `NotFound`: the path, or a directory on the way to it, does not exist;
+ * - `Exists`: something is already there (a non-recursive `mkdir`);
+ * - `IsDirectory`: a file operation met a directory;
+ * - `NotDirectory`: a directory operation met a file, or a path runs through one;
+ * - `NotEmpty`: a non-recursive `remove` of a directory with entries;
+ * - `Permission`: the backend refused access;
+ * - `Invalid`: the call itself is malformed (a relative path, a bad range or pattern, a symlink loop);
+ * - `Io`: anything else the backend reports.
+ */
+export declare const FsReason: Schema.Literals<readonly ["NotFound", "Exists", "IsDirectory", "NotDirectory", "NotEmpty", "Permission", "Invalid", "Io"]>;
+export type FsReason = typeof FsReason.Type;
+declare const FsError_base: Schema.Class<FsError, Schema.TaggedStruct<"FsError", {
+    readonly path: Schema.String;
+    readonly reason: Schema.Literals<readonly ["NotFound", "Exists", "IsDirectory", "NotDirectory", "NotEmpty", "Permission", "Invalid", "Io"]>;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** A failed file-system call: the path it was given, why, and the backend's message. */
+export declare class FsError extends FsError_base {
+}
+/** What a path holds. `symlink` is reported only where links are not followed (`list`, `stat` with `followSymlinks: false`). */
+export declare const FileKind: Schema.Literals<readonly ["file", "directory", "symlink", "other"]>;
+export type FileKind = typeof FileKind.Type;
+/** What `stat` reports. `path` is the path asked for; `mode` holds the permission bits where the backend has them. */
+export declare const FileInfo: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly kind: Schema.Literals<readonly ["file", "directory", "symlink", "other"]>;
+    readonly size: Schema.Number;
+    readonly mtimeMs: Schema.Number;
+    readonly mode: Schema.OptionFromOptionalKey<Schema.Int>;
+}>;
+export type FileInfo = typeof FileInfo.Type;
+/** One entry of a directory listing; links are not followed. */
+export declare const DirEntry: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["file", "directory", "symlink", "other"]>;
+}>;
+export type DirEntry = typeof DirEntry.Type;
+/** The bytes `readBytes` returns: from `offset` (default 0), at most `length` of them (default: to the end). */
+export declare const ReadRange: Schema.Struct<{
+    readonly offset: Schema.optionalKey<Schema.Int>;
+    readonly length: Schema.optionalKey<Schema.Int>;
+}>;
+export type ReadRange = typeof ReadRange.Type;
+/** `write` and `append`: with `createParents`, missing directories on the way are created first. */
+export declare const WriteOptions: Schema.Struct<{
+    readonly createParents: Schema.optionalKey<Schema.Boolean>;
+}>;
+export type WriteOptions = typeof WriteOptions.Type;
+/** `stat` follows symbolic links unless `followSymlinks` is false. */
+export declare const StatOptions: Schema.Struct<{
+    readonly followSymlinks: Schema.optionalKey<Schema.Boolean>;
+}>;
+export type StatOptions = typeof StatOptions.Type;
+/** `mkdir` and `remove`: `recursive` creates missing parents, or removes a directory with what it holds. */
+export declare const RecursiveOptions: Schema.Struct<{
+    readonly recursive: Schema.optionalKey<Schema.Boolean>;
+}>;
+export type RecursiveOptions = typeof RecursiveOptions.Type;
+/**
+ * How a glob walks. `cwd` is the absolute directory the pattern is relative
+ * to. `exclude` prunes entries anywhere in the walk: a pattern without a `/`
+ * is matched against each entry's name (`node_modules`, `*.log`), one with a
+ * `/` against its path relative to `cwd`; an excluded directory is not
+ * entered. Entries whose name starts with a dot are matched and entered only
+ * with `dot`, or where the pattern names them with a literal dot
+ * (`.github/**`). `onlyFiles` keeps regular files (not directories, links or
+ * other entries). The walk stops once it has found one more than `limit`
+ * paths, and reports `truncated`.
+ */
+export declare const GlobOptions: Schema.Struct<{
+    readonly cwd: Schema.String;
+    readonly exclude: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly dot: Schema.optionalKey<Schema.Boolean>;
+    readonly onlyFiles: Schema.optionalKey<Schema.Boolean>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+export type GlobOptions = typeof GlobOptions.Type;
+/**
+ * What `glob` found: POSIX paths relative to its `cwd`, depth-first with each
+ * directory's entries by name (so a directory comes before what it holds),
+ * at most `limit` of them; `truncated` when more matched.
+ */
+export declare const GlobResult: Schema.Struct<{
+    readonly paths: Schema.$Array<Schema.String>;
+    readonly truncated: Schema.Boolean;
+}>;
+export type GlobResult = typeof GlobResult.Type;
+export {};

package/dist/domain/file-system.entity.functions.d.ts

@@ -0,0 +1,18 @@
+import { Effect } from "effect";
+import { FsError } from "./file-system.entity.js";
+import type { DirEntry, GlobOptions, GlobResult } from "./file-system.entity.js";
+/**
+ * A glob as a walk over a directory listing, the one semantics every
+ * `FileSystem` backend shares (`fs.glob` differs between runtimes: it
+ * cannot list dot entries on Node and follows links on Bun). The walk is
+ * depth-first with each directory's entries sorted by name, so the paths
+ * come out in that order and a `limit` always keeps the same ones. It never
+ * enters a symbolic link, prunes `exclude`d entries before entering them,
+ * enters only directories that can hold a match, and stops at `limit + 1`
+ * matches to report `truncated`. A directory below `cwd` that cannot be
+ * listed (no permission, removed meanwhile) is skipped; `cwd` itself must
+ * list. The pattern is relative: an absolute one or one with a `..`
+ * segment fails with `Invalid`, as does a pattern (or an `exclude`) that
+ * `compileGlob` refuses.
+ */
+export declare const walkGlob: (list: (dir: string) => Effect.Effect<ReadonlyArray<DirEntry>, FsError>, pattern: string, options: GlobOptions) => Effect.Effect<GlobResult, FsError>;

package/dist/domain/file-system.entity.functions.js

@@ -0,0 +1,30 @@
+import { Chunk, Effect } from "effect";
+import { compileGlob } from "../util/glob.js";
+import { FsError } from "./file-system.entity.js";
+const byName = (left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0, under = (cwd, relative) => relative === "" ? cwd : cwd.endsWith("/") ? `${cwd}${relative}` : `${cwd}/${relative}`;
+export const walkGlob = (list, pattern, options) => Effect.suspend(() => {
+  const { cwd } = options;
+  if (!cwd.startsWith("/"))
+    return Effect.fail(new FsError({ path: cwd, reason: "Invalid", message: "a glob's cwd must be an absolute path" }));
+  if (pattern.startsWith("/") || pattern.split("/").includes(".."))
+    return Effect.fail(new FsError({ path: pattern, reason: "Invalid", message: "a glob pattern is relative to its cwd and stays below it (no leading / or .. segment)" }));
+  const dot = options.dot ?? !1, onlyFiles = options.onlyFiles ?? !1, limit = options.limit ?? Number.POSITIVE_INFINITY, full = (found) => Chunk.size(found) > limit, compiled = (glob, dotted) => Effect.mapError(Effect.fromResult(compileGlob(glob, { dot: dotted })), (reason) => new FsError({ path: glob, reason: "Invalid", message: `not a usable glob pattern: ${reason}` }));
+  return Effect.all({
+    matcher: compiled(pattern, dot),
+    exclusions: Effect.forEach(options.exclude ?? [], (exclude) => compiled(exclude, !0).pipe(Effect.map((matcher) => ({ byPath: exclude.includes("/"), matches: matcher.matches }))))
+  }).pipe(Effect.flatMap(({ matcher, exclusions }) => {
+    const excluded = (name, path) => exclusions.some((exclusion) => exclusion.matches(exclusion.byPath ? path : name)), visit = (relative, found) => list(under(cwd, relative)).pipe(Effect.catchIf((error) => relative !== "" && (error.reason === "Permission" || error.reason === "NotFound"), () => Effect.succeed([])), Effect.flatMap((entries) => Effect.reduce(entries.toSorted(byName), () => found, (sofar, entry) => {
+      if (full(sofar))
+        return Effect.succeed(sofar);
+      const path = relative === "" ? entry.name : `${relative}/${entry.name}`;
+      if (excluded(entry.name, path))
+        return Effect.succeed(sofar);
+      const next = matcher.matches(path) && (!onlyFiles || entry.kind === "file") ? Chunk.append(sofar, path) : sofar;
+      return entry.kind === "directory" && !full(next) && matcher.descends(path) ? visit(path, next) : Effect.succeed(next);
+    })));
+    return visit("", Chunk.empty());
+  }), Effect.map((found) => ({
+    paths: Chunk.toReadonlyArray(Chunk.take(found, limit)),
+    truncated: full(found)
+  })));
+});

package/dist/domain/file-system.entity.js

@@ -0,0 +1,37 @@
+import { Schema } from "effect";
+export const FsReason = Schema.Literals(["NotFound", "Exists", "IsDirectory", "NotDirectory", "NotEmpty", "Permission", "Invalid", "Io"]);
+
+export class FsError extends Schema.TaggedError()("FsError", {
+  path: Schema.String,
+  reason: FsReason,
+  message: Schema.String
+}) {
+}
+export const FileKind = Schema.Literals(["file", "directory", "symlink", "other"]), FileInfo = Schema.Struct({
+  path: Schema.String,
+  kind: FileKind,
+  size: Schema.Number,
+  mtimeMs: Schema.Number,
+  mode: Schema.OptionFromOptionalKey(Schema.Int)
+}), DirEntry = Schema.Struct({
+  name: Schema.String,
+  kind: FileKind
+}), ReadRange = Schema.Struct({
+  offset: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
+  length: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)))
+}), WriteOptions = Schema.Struct({
+  createParents: Schema.optionalKey(Schema.Boolean)
+}), StatOptions = Schema.Struct({
+  followSymlinks: Schema.optionalKey(Schema.Boolean)
+}), RecursiveOptions = Schema.Struct({
+  recursive: Schema.optionalKey(Schema.Boolean)
+}), GlobOptions = Schema.Struct({
+  cwd: Schema.String,
+  exclude: Schema.optionalKey(Schema.Array(Schema.String)),
+  dot: Schema.optionalKey(Schema.Boolean),
+  onlyFiles: Schema.optionalKey(Schema.Boolean),
+  limit: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)))
+}), GlobResult = Schema.Struct({
+  paths: Schema.Array(Schema.String),
+  truncated: Schema.Boolean
+});

package/dist/domain/loop-event.entity.d.ts

@@ -70,6 +70,15 @@ export type LoopEvent = {
     /** The schema-encoded result — the persisted, provider-visible form. */
     readonly encoded?: unknown;
 }
+/** A streamed call failed before its first part: this step, and every
+ *  later step of the run, is answered by `generateText` instead. Once per
+ *  run at most; `message` is the stream's error as text, cut to 300
+ *  characters. */
+ | {
+    readonly type: "stream_fallback";
+    readonly turnIndex: number;
+    readonly message: string;
+}
 /** The mid-run fold: the buffer outgrew the healthy context range and the
  *  older turns were replaced by a handoff summary — `kept` verbatim
  *  messages survive after it. A load-side rewrite; nothing is deleted. */

package/dist/domain/media.entity.d.ts

@@ -0,0 +1,79 @@
+import { Schema } from "effect";
+/**
+ * Images a model can be shown: a user's attachments (and, later, what a tool
+ * returns). An image is stored inline in the session log, as base64, once;
+ * these limits keep one image, one message and one request inside what the
+ * providers accept and what a session store must hold.
+ */
+export declare const MEDIA_LIMITS: {
+    /** Decoded bytes of one image: 3.75 MiB, 5 242 880 base64 characters (Anthropic's per-image limit). */
+    readonly imageBytes: 3932160;
+    /** Pixels on either side of one image. */
+    readonly maxPixels: 8000;
+    /** Attachments on one user message. */
+    readonly attachments: 8;
+    /** Images one request sends as images (the rest are label lines). */
+    readonly requestImages: 8;
+    /** Base64 characters of the images one request sends, and of one message's attachments together. */
+    readonly requestChars: 20000000;
+    /** Images one tool result may carry. */
+    readonly toolResultImages: 4;
+};
+/** The image types every provider route that takes images accepts. */
+export declare const ImageMediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+export type ImageMediaType = typeof ImageMediaType.Type;
+/**
+ * A content hash of an image's decoded bytes (an FNV-1a lane and a
+ * multiply-xorshift lane, 32 bits each, then the length, in hex). It names an
+ * image in slots and fingerprints; it is not cryptographic.
+ */
+export declare const MediaFingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+export type MediaFingerprint = typeof MediaFingerprint.Type;
+/**
+ * One image, inline: padded base64 `data` (no `data:` prefix) of `bytes`
+ * decoded bytes, of the `mediaType` its bytes are. Build one with
+ * `mediaFromBytes` or `mediaFromBase64`, which check the bytes and set the
+ * type, size and fingerprint from them.
+ */
+export declare const Media: 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;
+    /** A file name the user or tool gave it, shown in its label. */
+    readonly name: Schema.optionalKey<Schema.String>;
+    /** A description of the image, shown in its label. */
+    readonly alt: Schema.optionalKey<Schema.String>;
+}>;
+export type Media = typeof Media.Type;
+/** Where an image sits inside a JSON value (a tool's encoded result): its path and what it must be. */
+export declare const MediaSlot: Schema.Struct<{
+    readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Int]>>;
+    readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+    readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+    readonly bytes: Schema.Int;
+}>;
+export type MediaSlot = typeof MediaSlot.Type;
+/**
+ * Why an image was refused: no bytes (`Empty`), data that is not base64
+ * (`InvalidBase64`), bytes that are none of the image types
+ * (`UnsupportedType`), more than `MEDIA_LIMITS.imageBytes` (`TooLarge`), a
+ * side over `MEDIA_LIMITS.maxPixels` (`TooManyPixels`), a header whose size
+ * cannot be read (`Unreadable`), or attachments over
+ * `MEDIA_LIMITS.requestChars` together (`TooLargeTogether`). `TooMany` is
+ * defensive: a `UserMessage` with more than `MEDIA_LIMITS.attachments` fails
+ * its schema when it is constructed or decoded, so only a value that skipped
+ * that check reaches a begin with too many.
+ */
+export declare const AttachmentRejectedReason: Schema.Literals<readonly ["Empty", "InvalidBase64", "UnsupportedType", "TooLarge", "TooManyPixels", "Unreadable", "TooMany", "TooLargeTogether"]>;
+export type AttachmentRejectedReason = typeof AttachmentRejectedReason.Type;
+declare const AttachmentRejected_base: Schema.Class<AttachmentRejected, Schema.TaggedStruct<"AttachmentRejected", {
+    readonly reason: Schema.Literals<readonly ["Empty", "InvalidBase64", "UnsupportedType", "TooLarge", "TooManyPixels", "Unreadable", "TooMany", "TooLargeTogether"]>;
+    readonly index: Schema.optionalKey<Schema.Int>;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** An image a user message or a tool result cannot carry; `index` is the attachment's position, when it is one image's fault. */
+export declare class AttachmentRejected extends AttachmentRejected_base {
+}
+export {};

package/dist/domain/media.entity.functions.d.ts

@@ -0,0 +1,76 @@
+import { Effect, Option } from "effect";
+import { AttachmentRejected, ImageMediaType, MediaFingerprint } from "./media.entity.js";
+import type { Media, MediaSlot } from "./media.entity.js";
+/** What one image is counted as in a token estimate: its base64 is never counted as text. */
+export declare const IMAGE_TOKEN_ESTIMATE = 1600;
+/** The base64 characters `bytes` decoded bytes take, padded. */
+export declare const base64Length: (bytes: number) => number;
+/** An image's size in pixels, read from its header. */
+export interface ImageSize {
+    readonly width: number;
+    readonly height: number;
+}
+/** What a caller may say about an image besides its bytes. */
+export interface MediaDescription {
+    readonly name?: string;
+    readonly alt?: string;
+}
+/** The image type the bytes are, from their magic numbers: PNG, JPEG, GIF or WebP. */
+export declare const sniffImageType: (bytes: Uint8Array) => Option.Option<ImageMediaType>;
+/** An image's size in pixels from its header (PNG IHDR, GIF screen, WebP VP8/VP8L/VP8X, JPEG frame); none when the header is not readable. */
+export declare const imageSizeOf: (bytes: Uint8Array, mediaType: ImageMediaType) => Option.Option<ImageSize>;
+/** FNV-1a and a multiply-xorshift lane over the bytes, then their length: a content hash, not a cryptographic one. */
+export declare const mediaFingerprintOf: (bytes: Uint8Array) => MediaFingerprint;
+/**
+ * An image from its bytes. The type is the one the bytes are (sniffed), the
+ * size and fingerprint are computed, and the header must give a size of at
+ * most `MEDIA_LIMITS.maxPixels` a side. Fails with `AttachmentRejected`.
+ */
+export declare const mediaFromBytes: (bytes: Uint8Array, description?: MediaDescription) => Effect.Effect<Media, AttachmentRejected>;
+/**
+ * An image from base64, as `mediaFromBytes` checks it. A `data:` URL prefix
+ * and whitespace (wrapped lines) are removed first; the stored `data` is the
+ * canonical padded base64 of the bytes.
+ */
+export declare const mediaFromBase64: (data: string, description?: MediaDescription) => Effect.Effect<Media, AttachmentRejected>;
+/** An image checked again from its own data: type, size and fingerprint as its bytes give them; its name and alt kept. */
+export declare const normalizeMedia: (media: Media) => Effect.Effect<Media, AttachmentRejected>;
+/**
+ * The one line that stands for an image a request or a transcript does not
+ * carry: `[image omitted: image/png, 182 KB, shot.png: a chart]`.
+ */
+export declare const mediaLabel: (media: Pick<Media, "mediaType" | "bytes" | "name" | "alt">) => string;
+/** A cheap structural check that a value is a `Media` (no base64 or fingerprint validation). */
+export declare const isMediaValue: (value: unknown) => value is Media;
+/** Every image inside a JSON value, in key-sorted order, with its path. */
+export declare const mediaSlotsOf: (value: unknown) => ReadonlyArray<MediaSlot>;
+/**
+ * The image a slot names inside a JSON value, when the value there is an
+ * image with the slot's fingerprint, type and size. Compares the stored
+ * fields only: an image's content is checked once, when it is written.
+ */
+export declare const mediaAt: (value: unknown, slot: MediaSlot) => Option.Option<Media>;
+/** A tool result's images as memory records them: the slots it sends, and a label line for each image it does not. */
+export interface ToolResultMedia {
+    readonly slots: ReadonlyArray<MediaSlot>;
+    readonly labels: ReadonlyArray<string>;
+}
+/**
+ * A tool result's images checked once, when memory writes the result (a
+ * provider refuses a request with a bad image, and every later request
+ * would carry it). In slot order, each slot must name an image of the
+ * encoded value, its data base64 of an image whose type, size and
+ * fingerprint are the ones it states (`normalizeMedia` gives them back
+ * unchanged); an image that fails is an `[image unavailable: <why>]` line.
+ * An image a slot already named is sent once. At most
+ * `MEDIA_LIMITS.toolResultImages` images are sent, within
+ * `MEDIA_LIMITS.requestChars` base64 characters together; one over that is
+ * its `mediaLabel` line.
+ */
+export declare const toolResultMedia: (encoded: unknown, slots: ReadonlyArray<MediaSlot>) => Effect.Effect<ToolResultMedia>;
+/**
+ * A JSON value with every image's `data` replaced by its fingerprint: what
+ * text search, fingerprints, estimates and traces see of an image. Parts
+ * without an image are returned as they are (the same objects).
+ */
+export declare const elideMediaData: (value: unknown) => unknown;