@animalabs/agent-framework 0.23.1 → 0.24.0

package/src/modules/workspace/reconcile.ts

@@ -72,6 +72,7 @@ import {
   readPath,
   sniffImageMime,
   walkScope,
+  withinIncludes,
 } from './observe.js';
 import { EffectFailed, type Expect, chainOf, chmodContained, narrowedTo, syncDirectories, unlinkContained, writeContained } from './effects.js';
 
@@ -856,16 +857,22 @@ async function gather(store: JsStore, agreement: DiskAgreement, mount: MountRunt
   }
 
   // Which paths to decide: what disk shows, and what the store, P and intent
-  // track. The tracked ones are read synchronously, on this branch.
+  // track. The tracked ones are read synchronously, on this branch. A path
+  // the mount's include doesn't cover is outside the mount, so no pass
+  // decides it: the workspace's history may hold it from before the include,
+  // and it stays there as it is. So is one in a nested mount's directory
+  // that mount's include leaves out, such as history taken in before the
+  // mount was nested there: it's no mount's (namesNestedPlace).
   const candidates = new Set<string>();
+  const inside = (p: string): boolean => withinIncludes(mount.view, p);
   let walk: Walk | null = null;
   if (scope.kind === 'paths') {
-    for (const p of scope.paths) candidates.add(p);
+    for (const p of scope.paths) if (inside(p)) candidates.add(p);
   } else {
     const prefix = scope.dir ? scope.dir + '/' : undefined;
-    for (const e of store.treeList(mount.treeStateId, prefix)) if (inScope(e.path, scope)) candidates.add(e.path);
-    for (const [p] of agreement.paths(mount.name, scope.dir)) if (inScope(p, scope)) candidates.add(p);
-    for (const [p] of mount.intents.list(scope.dir)) if (inScope(p, scope)) candidates.add(p);
+    for (const e of store.treeList(mount.treeStateId, prefix)) if (inScope(e.path, scope) && inside(e.path)) candidates.add(e.path);
+    for (const [p] of agreement.paths(mount.name, scope.dir)) if (inScope(p, scope) && inside(p)) candidates.add(p);
+    for (const [p] of mount.intents.list(scope.dir)) if (inScope(p, scope) && inside(p)) candidates.add(p);
     if (rootUnavailable === null) {
       const resumeAfter = opts.resume ? agreement.walkResumesAfter(mount.name, scope.dir) : undefined;
       walk = await walkScope(mount.view, mount.rootReal, scope.dir, scope.recursive, opts.cap ?? mount.walkCap, {
@@ -1146,8 +1153,8 @@ export async function reconcilePass(
       // it, so it's always named. Another mount's directory met beneath the
       // scope is passed over by design even where this mount's tree holds
       // copies there: no tool of this mount syncs, pushes or clears them
-      // (listings show them, naming their holder), so naming the directory
-      // as unreached would never clear.
+      // (listings show those that mount's include covers, naming their
+      // holder), so naming the directory as unreached would never clear.
       const wholeScope = scope.kind === 'dir' && scope.dir !== '' && region.path === scope.dir;
       const unreached = hides && region.reason !== OTHER_MOUNT;
       if (region.kind === 'error' || region.kind === 'cap' || unreached || wholeScope) result.incomplete.push({ path: region.path, reason: region.reason });

package/src/modules/workspace/text.ts

@@ -0,0 +1,68 @@
+/**
+ * Lines numbered the way `cat -n` numbers them, with a long one cut, and a
+ * string's length as JSON, which a budget for a stored result counts. edit's
+ * answers use them.
+ */
+
+/** Whether the bytes open with a UTF-8 byte order mark. */
+export function hasBom(bytes: Uint8Array): boolean {
+  return bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf;
+}
+
+/** How long a line read shows before it cuts the line. */
+export const MAX_LINE_CHARS = 2000;
+
+/**
+ * Where to cut a string at or just before `at` without splitting a surrogate
+ * pair: a lone surrogate isn't text, and a model provider can refuse a
+ * request that carries one.
+ */
+export function safeCut(value: string, at: number): number {
+  if (at <= 0 || at >= value.length) return Math.max(0, Math.min(at, value.length));
+  const before = value.charCodeAt(at - 1);
+  return before >= 0xd800 && before <= 0xdbff ? at - 1 : at;
+}
+
+/**
+ * One line numbered the way `cat -n` numbers it: a six-wide number, a tab and
+ * the line. A line longer than `maxChars` is cut, saying how many characters
+ * it holds past the cut, and `readOn` adds how to read them.
+ */
+export function numberedLine(line: string, n: number, maxChars = MAX_LINE_CHARS, readOn?: (cut: number) => string): string {
+  const number = String(n).padStart(6);
+  if (line.length <= maxChars) return `${number}\t${line}`;
+  const cut = safeCut(line, maxChars);
+  return `${number}\t${line.slice(0, cut)} [… ${line.length - cut} more chars${readOn ? `; ${readOn(cut)}` : ''}]`;
+}
+
+/** Lines numbered from `start`, each as numberedLine shows it. */
+export function numbered(lines: string[], start: number, maxChars = MAX_LINE_CHARS): string {
+  return lines.map((line, i) => numberedLine(line, start + i, maxChars)).join('\n');
+}
+
+/**
+ * How many characters a string takes inside JSON's quotes, as JSON.stringify
+ * writes it: a quote, a backslash or a control character is escaped, and so
+ * is a lone surrogate.
+ */
+export function jsonLength(value: string): number {
+  let length = 0;
+  for (let i = 0; i < value.length; i++) length += jsonCharLength(value, i);
+  return length;
+}
+
+/** The JSON length of the code unit at `i`, as jsonLength counts it. */
+export function jsonCharLength(value: string, i: number): number {
+  const c = value.charCodeAt(i);
+  if (c === 0x22 || c === 0x5c) return 2;
+  if (c < 0x20) return c === 0x08 || c === 0x09 || c === 0x0a || c === 0x0c || c === 0x0d ? 2 : 6;
+  if (c >= 0xd800 && c <= 0xdbff) {
+    const next = value.charCodeAt(i + 1);
+    return next >= 0xdc00 && next <= 0xdfff ? 1 : 6;
+  }
+  if (c >= 0xdc00 && c <= 0xdfff) {
+    const before = i > 0 ? value.charCodeAt(i - 1) : 0;
+    return before >= 0xd800 && before <= 0xdbff ? 1 : 6;
+  }
+  return 1;
+}

package/src/modules/workspace/types.ts

@@ -16,6 +16,50 @@ export interface MountConfig {
   path: string;
   /** Access mode */
   mode: 'read-write' | 'read-only';
+  /**
+   * Where the mount's tools get what they read (default: 'chronicle').
+   * - 'chronicle': the workspace keeps the mount's files in its store, where
+   *   writes and edits land first, and takes in disk's changes under the
+   *   three-way rule as its listings, searches, syncs and scans reach them.
+   *   A read of a path the store doesn't hold takes in a new file there;
+   *   otherwise it reads the store's copy.
+   * - 'direct': for a checkout an agent reads, not one it changes. Every
+   *   read, listing and search is disk's own copy as it is when it runs,
+   *   and none of its files go into the store. No scan or watcher
+   *   runs, so no call waits behind one, and `sync`, `materialize` and the
+   *   watch settings have nothing to act on. Only with `mode: 'read-only'`,
+   *   and not with `watch` other than 'never', `watchDebounceMs`,
+   *   `watchRootPollMs`, a `wakeOnChange` that would wake (true, or a
+   *   non-empty list) or `autoMaterialize: true`: each of those would never
+   *   act, and the workspace refuses the mount. Its `ignore`
+   *   has a default (see there). Paths, links, its `include`, other mounts'
+   *   directories, size limits and the walk cap hold as on a 'chronicle'
+   *   mount. Its tools read beneath whatever directory is at its
+   *   root, with no check against the one a 'chronicle' run of it last
+   *   agreed with. Where that root now lies elsewhere than the last start
+   *   placed it, each call nests in it, as a start would now, every mount
+   *   configured beneath its path, where that path leads beneath its root,
+   *   and every other mount whose root, as that start placed it, lies
+   *   beneath where its root lies now, or whose configured path lies
+   *   beneath a directory that start found there. A mount configured
+   *   elsewhere whose own root has moved since, and the other mounts' own
+   *   placements, wait for the next start, so a direct root moved into
+   *   another mount's directory is still that mount's too.
+   *
+   * A mount configured 'direct' runs as 'chronicle' from a start that finds
+   * the store holding changes there that disk lacks, on the branch selected
+   * then: a draft, a workspace deletion or a conflict, as `status` counts
+   * them pending, or an intent the workspace can't read, which may hold one
+   * of those. They stay in view, and the workspace says so on stderr and
+   * through the framework's ops alerts, naming them and the ways to start it
+   * direct. It runs unwatched, and walks by the direct kind's default
+   * ignore list where its config names none; `ls` without a path, and
+   * `status`, give its `backend` as 'chronicle' and that list. A mount that
+   * ran direct and runs as 'chronicle' again takes in what disk changed
+   * meanwhile as its listings, searches and syncs reach it, as an unwatched
+   * 'chronicle' mount does after any time away.
+   */
+  backend?: 'chronicle' | 'direct';
   /**
    * Watch mode for filesystem changes:
    * - 'always': chokidar watches continuously; each event re-observes its paths
@@ -25,8 +69,8 @@ export interface MountConfig {
    *   the round goes on. Each scan walks from the mount's start, so on a
    *   mount over its `walkCap` it covers the first `walkCap` entries every
    *   time, and files past them come in as `walkCap` describes
-   * - 'never': no background reads; listings and lazy reads still observe
-   *   the paths they show
+   * - 'never': no background reads; listings still observe the paths they
+   *   show, and a read observes a path the store doesn't hold
    */
   watch?: 'always' | 'on-agent-action' | 'never';
   /** Debounce window in ms for watch: 'always' mode (default: 300) */
@@ -43,17 +87,157 @@ export interface MountConfig {
    * says, a directory with what lies beneath it: `.name.swp` and `.name.swx`
    * (the whole name), and names ending in `~` or in `.subl…tmp`, matched by
    * `^\..+\.sw[px]$`, `~$` and `\.subl.*\.tmp$`.
+   *
+   * A mount configured direct (`backend`) whose config names no list takes
+   * `node_modules`, `dist`, `.git`, `build`, `coverage`, `target`,
+   * `__pycache__` and `.venv`, each matching that name at any depth,
+   * whichever kind it runs as. A direct mount's walks of the whole mount,
+   * and of any path no pattern covers, pass over what the list covers. A
+   * listing, glob or grep whose path, or whose pattern's directory, the
+   * list covers is walked all the same, the patterns covering it set aside
+   * and the rest applying beneath it, as a sync that names a path walks it
+   * on a 'chronicle' mount.
    */
   ignore?: string[];
+  /**
+   * The files this mount holds, when it holds only some of what is under its
+   * path: the same pattern forms as `ignore`, read for files. A name or an
+   * extension glob covers a file by its own name, at any depth, and a directory
+   * glob (`dir/**`) covers what lies beneath that directory, and not a file
+   * named like it. Unlike `ignore`, a pattern that matches a directory's name
+   * covers nothing beneath it, since each file is covered by its own name:
+   * `["gate.json"]` holds every file named `gate.json`, and no other file
+   * beneath a directory of that name. A subtree is named with `dir/**`.
+   *
+   * It's the mount's boundary for content: no workspace path reads, stores,
+   * serves or writes back a file it doesn't cover, and no tool lists,
+   * matches or names one, beyond echoing a path it was given, which it may
+   * spell as disk does. A walk passes over one and counts it under
+   * `passedOver`, and passes over a link its names don't cover with the
+   * reason a mount without an include gives a link it doesn't enter, "a
+   * symlink, not walked", where the link leads to a directory, and wherever
+   * it leads on a mount that doesn't follow links. No pass decides a change
+   * the watcher reports there, and a materialize doesn't write it back even
+   * when the workspace's history holds it. A materialize that names a
+   * directory inside the mount counts each such entry beneath it under
+   * `passedOver`,
+   * with the reason and without its path, a deletion or conflict held there
+   * included; one of the whole mount takes none of them up. The file
+   * operations (read, write, edit, delete, and the module's binary and disk
+   * reads and writes) refuse a path it doesn't cover as outside the mount's
+   * include, a directory's included, and `resolveAbsolutePath` returns null
+   * for one; the mount's root is inside. Whether a name is taken isn't
+   * withheld: a refusal may show that something occupies a path the caller
+   * named. On a mount that follows links, a path is judged where it lands as
+   * well as where it's named, as disk spells it there: a covered path that
+   * reaches a file the include doesn't cover, through a link at the path or
+   * on its way, is refused as one that leaves the mount (the file operations
+   * refuse it before anything is stored), and a listing from where a link
+   * leads passes over such a file. A covered path whose landing realpath
+   * can't resolve, as for a loop or a directory this process can't search,
+   * is refused too, by every file operation, a delete included, since
+   * where it lands can't be judged.
+   *
+   * A sync, materialize, grep, glob or ls that names a path the include
+   * doesn't cover takes it as a directory, its scope, exactly where a listing
+   * names one: where disk has a directory reached from the mount's root
+   * through directories, with no link among them, or the workspace's history
+   * holds an entry beneath it that the include covers, and that a nested
+   * mount's include covers too where it lies in that mount's directory. A
+   * directory `ignore` covers is a scope too when it's named, though a
+   * listing passes over it. Each refuses any other path the include doesn't
+   * cover. A covered path is a file to a sync, materialize or grep when disk
+   * or history has a file there, and otherwise a directory; a glob takes its
+   * path as a directory. Beneath a directory, each passes over what the
+   * include doesn't cover, and a listing that isn't recursive names each
+   * directory directly beneath its path that disk has, and each that a
+   * covered entry in history implies, with only the files the include
+   * covers. A mount running direct has no history (`backend`), so there
+   * disk alone decides each of these. `ignore` still applies to what
+   * `include` covers.
+   *
+   * On a disk that folds names, the parse reads a path in disk's spelling,
+   * as the walk names what it lists, so a covered name whose file disk
+   * spells otherwise is outside the mount, and the include's refusal shows
+   * the path as given. A path that names one of the workspace's entries
+   * exactly, or does once its directories take disk's spelling, keeps the
+   * entry's spelling, as the parse gives it, and what lies past a link on
+   * the way keeps the caller's spelling, since the parse reads nothing past
+   * a link. Other answers name a path as the parse spells it, a name the
+   * include leaves out included, since how disk spells a name the caller
+   * gave is no content of that file. Where a
+   * followed path lands is judged as disk spells it there, and a path that
+   * meets no link where the parse names it.
+   * `resolveAbsolutePath`, which is synchronous, judges the include on the
+   * path as given and follows no link: on such a disk it returns the path to
+   * a covered name's file that disk spells otherwise, and null for a covered
+   * file named in another case.
+   *
+   * A path in a nested mount's directory is that mount's, whatever this
+   * include covers: every tool gives the answer that names the mount holding
+   * it and the path to use there. Through a link a mount follows, a place in
+   * that directory is named only where it's a directory, or a file that
+   * mount's own include covers with no file on its way, and is otherwise
+   * refused as leaving the mount. On a mount that doesn't follow links, a
+   * link on a path's way is refused, as on any such mount (followSymlinks).
+   * A nested mount's root is placed where disk has it at each start, and its
+   * directory is matched by spelling, so four cases fall outside this, as
+   * for any nested mount, and a fifth on a direct one: on a disk that folds
+   * names, a mount configured
+   * through a link that spells a directory otherwise than disk does isn't
+   * found nested, and this mount holds its files as its own; on such a disk,
+   * a path through a link that spells a nested mount's directory otherwise
+   * than that mount's configured path does, whether the link or the
+   * configured path is the one spelled otherwise than disk, isn't found to
+   * lead there, and this mount reads, lists, searches and writes there as
+   * its own, creating files too, though a walk from its root passes over the
+   * directory; on such a disk, a place in a nested mount's directory that a
+   * link does lead to is judged by that mount's include, and named, in the
+   * spelling the link's target gives, so a refusal can name a file disk
+   * spells outside that include, or leave a covered one unnamed; and a
+   * nested mount whose root moves while running, as `acceptRoot` takes,
+   * stays placed where it was until the next start; and where a direct
+   * mount's root is repointed between a read's parse and its open, a race
+   * left to whoever writes the disk, a mount nested in it by its
+   * directories alone, since its real root holds that root, can have the
+   * read serve a path in its directory.
+   *
+   * Text the host registers for a path (`registerGeneratedTextFile`) is
+   * served there whatever the include says, since it isn't one of the
+   * mount's files: it's matched by the path a spelling resolves to, before
+   * anything else checks the path, so every spelling that resolves to its
+   * registered path reads it, and none writes it. On a disk that folds names,
+   * a spelling in another case isn't its path, and reaches whatever file disk
+   * has there. The framework keeps its own files (`tool-results/`, `refs/`)
+   * only in a writable mount without an include, and what it kept in a mount
+   * before the mount had one is outside the mount once it has one, unless the
+   * include covers it.
+   *
+   * Left out, the mount holds everything under its path. Given, it's a list
+   * of at least one string, each a name, an `*.ext` glob or a `dir/**` glob,
+   * whose directory may be nested (`a/b/**`). The module refuses a pattern
+   * with a `/` that isn't such a glob, a `*` anywhere but a leading `*.` or
+   * that trailing `/**`, an empty, `.` or `..` segment, and, where `\` is the
+   * platform's separator, a `\`. Any other pattern is a file name, matched
+   * literally, so `[id].tsx` names the file of that name.
+   */
+  include?: string[];
   /**
    * Whether to follow symlinks (default: false). Without it, no symlink on a
    * path is followed: not one at the path itself, and not one among the
    * directories on its way beneath the mount's root, wherever it leads. A path
    * with a symlink among its directories is refused naming the link, and for
-   * a link inside the mount, its target. A mount root that is
-   * itself a symlink is still the root. With it, a symlink on a path is
-   * followed while what it reaches stays inside the mount. Either way, a
-   * listing or a sync's walk descends into no symlinked directory.
+   * a link inside the mount, its target where a tool could name it: a
+   * directory, or a file the include of the mount it lies in covers, where
+   * that mount has one. On a mount with an include, a link the include
+   * doesn't cover is outside the mount itself, and its refusal tells nothing
+   * of where it leads. A mount root that is itself a symlink is still the
+   * root. With it, a symlink on a path is followed while what it reaches
+   * stays inside the mount, which on a mount with an include means a
+   * directory or a file the include covers. Either way, a listing or a
+   * sync's walk descends
+   * into no symlinked directory beneath its scope; with it, a scope named
+   * through a link is listed from where the link leads.
    */
   followSymlinks?: boolean;
   /** Maximum file size in bytes (default: 5MB) */
@@ -148,6 +332,13 @@ export interface WorkspaceConfig {
 export interface MountState {
   /** The mount config */
   config: MountConfig;
+  /**
+   * Whether the mount runs direct (`MountConfig.backend`), as the workspace
+   * decides when initStore gives the store and again at each start: a mount
+   * configured direct runs as 'chronicle' while the store holds changes
+   * there that disk lacks.
+   */
+  direct: boolean;
   /** Tree state ID in Chronicle */
   treeStateId: string;
   /** Branch-local intent (tombstones, store origin, conflicts) for this mount's paths */
@@ -257,6 +448,20 @@ export interface EditInput {
   replaceAll?: boolean;
 }
 
+export interface EditManyInput {
+  /** The edits, each matched in its file as the call reads it, all in one mount's files. */
+  edits: Array<{
+    /** File path (mount-prefixed) */
+    path: string;
+    /** Exact text to replace */
+    oldString: string;
+    /** Text to replace it with */
+    newString: string;
+    /** How many times oldString occurs in the file (default: 1); every one is replaced. */
+    occurrences?: number;
+  }>;
+}
+
 export interface DeleteInput {
   /** File path (mount-prefixed) */
   path: string;

package/src/modules/workspace/watcher.ts

@@ -28,8 +28,9 @@ export interface WatcherEvents {
  * identical to an empty directory in the recorded state.
  */
 export interface WatcherLifecycle {
-  /** Fires when chokidar completes its initial scan: once for each attach, so
-   *  again after a re-attach. */
+  /** Fires when chokidar completes an attach's initial scan, so again after a
+   *  re-attach. An attach closed before its scan completes, by a re-attach or
+   *  a stop, never fires it: chokidar drops its listeners at the close. */
   onReady?: () => void;
   /** Fires on any chokidar-reported error (ENOENT, EACCES, platform faults). */
   onError?: (err: Error) => void;

package/src/operator-log.ts

@@ -118,35 +118,63 @@ export function capIds(ids: string[]): { ids: string[]; count: number; truncated
     : { ids, count: ids.length };
 }
 
+/**
+ * Facts every surgery marker receipt carries, whatever happened: the
+ * publication scope chosen (`none` unless the operator chose marks), how many
+ * removed addressable Discord messages the choice leaves unmarked (outside its
+ * scope or its authorized refs; whether the chosen ones are scheduled is the
+ * receipt's `status`), and how many authorized refs it did not remove (a
+ * delayed application whose anchor no longer covered them; their marks are
+ * never widened to anything else).
+ */
+export interface SurgeryMarkerFacts {
+  scope: 'none' | 'addressed' | 'all';
+  unmarked: number;
+  notRemoved: number;
+}
+
 /**
  * What a live surgery did about Discord awareness marks, reported apart from
  * the body change itself. A surgery that returns has applied its body change;
  * this says only whether marks were scheduled:
  *
- * - `none` — no marks were scheduled: the change removed no addressable
- *   Discord message, or the awareness outbox is disabled (no
- *   `discordAwarenessOutboxPath` and no `storePath`). It is not proof that
- *   no addressable Discord message was removed: the surgery's `removedRefs`
- *   (`discordRefs` in the operator log) say whether any was.
- * - `queued` — the outbox batch is durably active, and its delivery was
- *   started in the background. If starting it fails (reconciliation reading
- *   or writing the ledger), a `discord-awareness-delivery` ops alert reports
- *   the failure, the batch stays durably active, and the next sync,
- *   reconnect or start delivers it. It is not a delivery claim: per-message
- *   outcomes stay in the outbox ledger.
+ * - `none` — no marks were requested (the default), or none of the removed
+ *   messages fell within the chosen scope and authorized refs. It says
+ *   nothing about whether Discord messages were removed: `unmarked` counts
+ *   the addressable ones left unmarked, the surgery's `removedRefs` list
+ *   every one, and the operator log's `discordRefs` counts them.
+ * - `queued` — one add request per mark is recorded, and delivered when its
+ *   route is up: a pass starts at once unless the host is stopping, and a
+ *   later one (a reconnect, a tools-list change or the next start) takes
+ *   what remains. If a delivery pass fails, the requests stay recorded and
+ *   the `discord-awareness-delivery` ops alert says so. The same alert names
+ *   the marks a pass, or a start, gave up on: refused by Discord for good,
+ *   or after three unconfirmed attempts. It is not a delivery claim: what
+ *   Discord answers is kept in the awareness ledger.
  * - `not-scheduled` — the body change landed, but recording the batch as
- *   active failed, so it was retired from the ledger: none of its marks will
- *   be delivered.
- * - `unresolved` — the ledger could record neither the activation nor the
- *   retirement. `batchId` names a retained batch whose scheduling outcome is
- *   unresolved: any later reconciliation or restart that can read it may
- *   promote and deliver it, and nothing here promises otherwise.
+ *   active failed, or it was never recorded: none of its marks will be
+ *   delivered. `error` says why, and whether the batch was retired or stays
+ *   prepared for a start to retire.
  */
-export type SurgeryMarkerReceipt =
+export type SurgeryMarkerReceipt = SurgeryMarkerFacts & (
   | { status: 'none'; queued: 0 }
   | { status: 'queued'; queued: number; batchId: string }
   | { status: 'not-scheduled'; queued: 0; error: string }
-  | { status: 'unresolved'; queued: 0; batchId: string; error: string };
+);
+
+/** What a surgery would remove and which messages each marks scope covers. */
+export interface SurgeryMarksPreview {
+  messagesRemoved: number;
+  /** Removed messages that carry a Discord address at all. */
+  addressable: number;
+  emoji: string;
+  scopes: Record<'addressed' | 'all', {
+    count: number;
+    channels: Array<{ channelId: string; count: number }>;
+    /** Pass back as `marks.refs` to bind the choice to exactly these. */
+    refs: Array<{ serverId: string; channelId: string; messageId: string }>;
+  }>;
+}
 
 /** Thrown by live surgery methods when a request cannot be honored. `code`
  *  lets surfaces distinguish "agent busy — quiesce first" from bad input. */