@animalabs/agent-framework 0.28.0 → 0.30.0

package/dist/src/modules/workspace/index.js

@@ -4,6 +4,7 @@
  * Provides a unified workspace with mount-based filesystem access,
  * auto-sync between real filesystem and Chronicle, and manual materialization.
  */
+import { NOTICE_TAG } from '../../notice-tags.js';
 import { constants as fsConstants } from 'node:fs';
 import { open, readdir, readlink, stat, lstat, realpath } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, parse, resolve, relative, sep } from 'node:path';
@@ -12,7 +13,7 @@ import { MountWatcher } from './watcher.js';
 import { hashContent, storedBytes, DEFAULT_MAX_FILE_SIZE } from './sync.js';
 import { DiskAgreement, EvidenceUnavailable, callGate, sameRootIdentity } from './disk-agreement.js';
 import { BranchIntents } from './branch-intent.js';
-import { CHANGED, DIRECTORY, IGNORED, LEAVES_MOUNT, NONBLOCK, NOT_FOLLOWED, NOT_REGULAR, OTHER_MOUNT, OUTSIDE_INCLUDE, ROOT_REPLACED, ROOT_UNAVAILABLE, beneathRoot, checkDir, checkRoot, confirmAbsent, coversLanding, directoryAt, diskSpelling, filesystemTrustsCtime, foldsCase, inOtherMount, insideMount, leadsInto, linkOnTheWay, linkRefusal, linkWords, locateRoot, looksBinary, namesHolder, nestedAtReal, nestedGuess, nestedHolder, nestedStep, observePath, parsedSpelling, passedOverAt, pathSegments, patternRefusal, readBytes, readPrefix, restBeneath, rootAbsence, sameRoot, shownLeads, sniffImageMime, surelyAtRoot, walkScope, withinIncludes } from './observe.js';
+import { CHANGED, DIRECTORY, IGNORED, NONBLOCK, OTHER_MOUNT, OUTSIDE_INCLUDE, ROOT_REPLACED, ROOT_UNAVAILABLE, beneathRoot, checkDir, checkRoot, confirmAbsent, coversLanding, directoryAt, diskSpelling, filesystemTrustsCtime, foldsCase, inOtherMount, insideMount, leadsInto, linkOnTheWay, linkRefusal, linkWords, locateRoot, looksBinary, namesHolder, nestedAtReal, nestedGuess, nestedHolder, nestedStep, observePath, parsedSpelling, passedOverAt, pathSegments, patternRefusal, readBytes, readPrefix, restBeneath, rootAbsence, sameRoot, shownLeads, sniffImageMime, surelyAtRoot, walkScope, withinIncludes } from './observe.js';
 import { TOOL_BATCH_HOOK_TIMEOUT_MS, ensureStateRegistered } from '../../module-registry.js';
 import { DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS } from '../../tool-result-history.js';
 import { countBudget, decodeForEdit, hintBudget, planFile } from './edit-plan.js';
@@ -20,9 +21,9 @@ import { cutLine, editList, editReceipt, fitted, refusalText } from './edit-text
 import { fileText } from './text.js';
 import { DEFAULT_READ_LINE_LIMIT, characterPage, linePage } from './read-page.js';
 import { grepText, textAnswer } from './result-text.js';
-import { NOT_PUSHED_IN_OTHER_MOUNT, WALK_CAP, entryMode, pushPaths, reconcilePass, settleAdoptionBeforeMutation, } from './reconcile.js';
+import { NOT_PUSHED_IN_OTHER_MOUNT, WALK_CAP, entryMode, explained, pushPaths, reconcilePass, settleAdoptionBeforeMutation, wayOn, } from './reconcile.js';
 import { EffectFailed, unlinkContained } from './effects.js';
-import { AWAITS_REOPEN, ROOT_RECHECK, ROOT_UNCHECKED, Refusal, changesFiles, didNothing, errnoCode, errnoWayOn, errnoWords, hostFix, onlyTheHost, systemWords, unexpectedAnswer } from './answers.js';
+import { AWAITS_REOPEN, MOUNT_IT, ROOT_RECHECK, Refusal, UNFOLLOWED_STEP, changesFiles, didNothing, errnoCode, errnoWayOn, errnoWords, hostFix, onlyTheHost, systemWords, unexpectedAnswer } from './answers.js';
 import { unknownToolMessage } from '../unknown-tool.js';
 import { closestNames } from '../../closest-names.js';
 import { RecordJournal } from '../../record-journal.js';
@@ -124,6 +125,13 @@ class NotRegularFile extends WorkspaceReadError {
         super('not_found', `Not a regular file: ${path}`, stage);
     }
 }
+class LinkOnTheWay extends WorkspaceReadError {
+    reason;
+    constructor(code, message, reason, errno) {
+        super(code, message, 'readlink', errno);
+        this.reason = reason;
+    }
+}
 class RootUnavailable extends WorkspaceReadError {
     mount;
     reason;
@@ -139,10 +147,10 @@ class RootUnavailable extends WorkspaceReadError {
  * Why a pass decided nothing, or null where it decided its paths. A pass gives
  * up deciding, and reports no path, when the selected branch kept changing
  * while it gathered, or when a sync's branch was no longer selected; it then
- * carries no branchId, and the region it leaves incomplete says why.
+ * carries no branchId, and says why in `undecided`.
  */
 function undecidedOf(pass) {
-    return pass.branchId === undefined ? (pass.incomplete[0]?.reason ?? 'the pass decided nothing') : null;
+    return pass.branchId === undefined ? (pass.undecided ?? 'the pass decided nothing') : null;
 }
 function errnoOf(err) {
     return typeof err === 'object' && err !== null && 'code' in err && typeof err.code === 'string'
@@ -194,15 +202,16 @@ function matchesPartialPrefix(buffer, prefix) {
  */
 async function linkReadError(mount, found, mountPrefixedPath, relativePath, nested, rootReal) {
     if (!('link' in found)) {
-        return new WorkspaceReadError('not_found', `Unable to read file: ${mountPrefixedPath}: ${linkWords(mount.config.name, found, null)}`, 'readlink', found.code);
+        const reason = linkWords(mount.config.name, found, null);
+        return new LinkOnTheWay('not_found', `Unable to read file: ${mountPrefixedPath}: ${reason}`, reason, found.code);
     }
     const leads = await shownLeads(rootReal, rootReal, found, mount.config.include);
-    const reason = `${mountPrefixedPath}: ${linkWords(mount.config.name, found, leads, nested, mount.config.include)}`;
+    const reason = linkWords(mount.config.name, found, leads, nested, mount.config.include);
     const holder = leads?.kind === 'inside' ? nestedHolder(leads.target, nested) : undefined;
     const code = leads?.kind === 'outside' ? 'escape'
         : leads?.kind === 'inside' && holder && namesHolder(leads, nested) ? 'other_mount'
             : relativePath === found.link ? 'symlink' : 'parent_symlink';
-    return new WorkspaceReadError(code, reason, 'readlink');
+    return new LinkOnTheWay(code, `${mountPrefixedPath}: ${reason}`, reason);
 }
 /**
  * `to` beneath `from`, mount-relative and `/`-separated, whatever the
@@ -1996,14 +2005,14 @@ export class WorkspaceModule {
             return { requestInference: true };
         let text;
         if (paths.length === 1) {
-            text = `[workspace event · ${op} · ${paths[0]}]`;
+            text = `[${NOTICE_TAG.workspaceEvent} · ${op} · ${paths[0]}]`;
         }
         else {
             const list = paths.map(p => `- ${p}`).join('\n');
-            text = `[workspace event · ${op} · ${paths.length} files in ${mountName}/]\n${list}`;
+            text = `[${NOTICE_TAG.workspaceEvent} · ${op} · ${paths.length} files in ${mountName}/]\n${list}`;
         }
         if (conflicts && conflicts.length > 0) {
-            text += `\n[conflicts with disk: ${conflicts.join(', ')}; reading each shows how to settle it]`;
+            text += `\n[${NOTICE_TAG.conflictsWithDisk}: ${conflicts.join(', ')}; reading each shows how to settle it]`;
         }
         return {
             requestInference: true,
@@ -2830,6 +2839,16 @@ export class WorkspaceModule {
         const names = [...this.mounts.keys()];
         return names.length === 0 ? 'this workspace has no mounts' : `the mounts are ${listed(names.map((name) => JSON.stringify(name)))}`;
     }
+    emptyPathField(mount, bare) {
+        const empty = '"path" is "", which names no file or directory.';
+        if (mount === undefined)
+            return `${empty} Leaving "path" out ${bare}.`;
+        if (mount === '')
+            return `${empty} "mount" is "" too; leaving both out ${bare}.`;
+        if (this.mounts.has(mount))
+            return `${empty} Leaving "path" out covers mount ${JSON.stringify(mount)}.`;
+        return `${empty} "mount" is ${JSON.stringify(mount)}, which is no mount's name; ${this.mountList()}. Leaving both out ${bare}.`;
+    }
     noSuchMountField(given, bare) {
         const [close] = closestNames(given, [...this.mounts.keys()], 1);
         return `"mount" is ${JSON.stringify(given)}, which is no mount's name; ${this.mountList()}.`
@@ -3568,7 +3587,7 @@ export class WorkspaceModule {
                 return `${shown} is in conflict: the workspace deleted it and disk changed it since. ` +
                     'Sync this path to take the disk version.';
             case 'unverified':
-                return uncheckedFile(shown, report.note);
+                return uncheckedFile(shown, report.note, report.noteCause ?? {});
             default:
                 return missing ?? `there's no file at ${shown}. ls or glob lists the files that exist.`;
         }
@@ -3736,9 +3755,9 @@ export class WorkspaceModule {
         const rootReal = await realpath(root).catch(() => root);
         const view = this.viewOf(mount, this.agreementOrThrow().rootIdentityForRead(mount.config.name));
         const proof = await confirmAbsent(view, rootReal, relativePath);
-        if (typeof proof !== 'string')
+        if (!('reason' in proof))
             return 'none';
-        return { unreadable: proof === CHANGED ? containedRefusal(err, path) : proof };
+        return { unreadable: proof.reason === CHANGED ? containedRefusal(err, path) : proof.reason };
     }
     async restoreEach(mount, versions, each) {
         const byHash = new Map();
@@ -4700,7 +4719,7 @@ export class WorkspaceModule {
                 // whether the file is gone, so it's taken as the agent's write too.
                 if (error instanceof EffectFailed && error.touched) {
                     this.recordDirectWrite(mount, agentName, since);
-                    return { success: false, isError: true, error: `The delete of ${path} failed after it reached the file, so the file may be gone: ${directReason(error)}. ls shows whether it is.` };
+                    return { success: false, isError: true, error: `The delete of ${JSON.stringify(path)} failed after it reached the file, so the file may be gone: ${directReason(error)}. ls shows whether it is.` };
                 }
                 return { success: false, isError: true, error: directDidNothing('delete', path, error) };
             }
@@ -5059,7 +5078,8 @@ export class WorkspaceModule {
             .filter((region) => region.kind === 'error' || region.kind === 'cap' || (region.kind === 'ignored' && region.path === dir && dir !== ''))
             .map((region) => ({
             path: region.path,
-            reason: region.reason === OTHER_MOUNT ? this.otherMountNote(mount.config.name, region.path, 'list', moved) : region.reason,
+            reason: region.reason === OTHER_MOUNT ? this.otherMountNote(mount.config.name, region.path, 'list', moved)
+                : explained(region.reason, region.errno !== undefined ? { errno: region.errno } : {}, 'list'),
         }));
         return {
             view,
@@ -5669,7 +5689,10 @@ export class WorkspaceModule {
         const pendingDeletions = [];
         const modesKept = [];
         let explicit = null;
-        if (input.path) {
+        if (input.path !== undefined) {
+            if (input.path === '') {
+                return { success: false, error: didNothing('materialize', this.emptyPathField(input.mount, "covers every mount that takes writes and doesn't already write them straight to disk")), isError: true };
+            }
             const parsed = await this.parsePath(input.path);
             explicit = parsed;
             // A path outside the mount's include that's no scope (refusesAsOutside)
@@ -5683,7 +5706,7 @@ export class WorkspaceModule {
         if (explicit) {
             mountsToMaterialize = [{ name: explicit.mount.config.name, mount: explicit.mount }];
         }
-        else if (input.mount) {
+        else if (input.mount !== undefined) {
             const m = this.mounts.get(input.mount);
             if (!m) {
                 return { success: false, error: didNothing('materialize', this.noSuchMountField(input.mount, "covers every mount that takes writes and doesn't already write them straight to disk")), isError: true };
@@ -5885,7 +5908,9 @@ export class WorkspaceModule {
         }
         // A path names its own mount; otherwise the given mount, or every mount.
         let targets;
-        if (input.path) {
+        if (input.path !== undefined) {
+            if (input.path === '')
+                return { success: false, error: didNothing('sync', this.emptyPathField(input.mount, 'covers every mount')), isError: true };
             const { mount, relativePath, moved, root } = await this.parsePath(input.path);
             // A path outside the mount's include that's no scope (refusesAsOutside)
             // is refused; beneath a directory, the walk passes over what the include
@@ -5895,7 +5920,7 @@ export class WorkspaceModule {
             }
             targets = [{ name: mount.config.name, mount, relativePath }];
         }
-        else if (input.mount) {
+        else if (input.mount !== undefined) {
             const m = this.mounts.get(input.mount);
             if (!m) {
                 return { success: false, error: didNothing('sync', this.noSuchMountField(input.mount, 'covers every mount')), isError: true };
@@ -5976,7 +6001,7 @@ export class WorkspaceModule {
             // refused" don't look identical from the outside.
             for (const r of pass.reports.values()) {
                 if (r.state === 'unverified') {
-                    allSkipped.push({ mount: name, path: r.path, reason: `disk could not be checked: ${r.note ?? 'not observed'}` });
+                    allSkipped.push({ mount: name, path: r.path, reason: `disk could not be checked: ${explained(r.note ?? 'not observed', r.noteCause ?? {}, 'sync')}` });
                 }
                 else if (r.state === 'disk-only') {
                     allSkipped.push({ mount: name, path: r.path, reason: 'disk-only: binary or over the size limit, never stored' });
@@ -6406,7 +6431,17 @@ function directReason(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function directWayOn(error) {
-    return error instanceof FileChanged ? 'Calling again reads it afresh.' : error instanceof WriteRefused ? error.wayOn : null;
+    if (error instanceof FileChanged)
+        return 'Calling again reads it afresh.';
+    if (error instanceof WriteRefused)
+        return error.wayOn;
+    if (error instanceof EffectFailed) {
+        if (error.detail.errno !== undefined)
+            return errnoWayOn(error.detail.errno);
+        if (error.detail.again === true)
+            return 'Calling again checks it afresh.';
+    }
+    return null;
 }
 function directDidNothing(tool, path, error) {
     const on = directWayOn(error);
@@ -6439,17 +6474,12 @@ function containedRefusal(err, path) {
 function deletedOnDisk(path) {
     return `there's no file at ${JSON.stringify(path)} any more: disk's copy was deleted since the workspace last agreed with it, and the workspace took that in first. ls or glob lists the files that exist.`;
 }
-function uncheckedFile(shown, note) {
+function uncheckedFile(shown, note, cause) {
     if (note === DIRECTORY)
         return `${shown} is a directory, not a file; ls ${shown} lists what's in it.`;
-    const on = note === ROOT_UNAVAILABLE ? ROOT_UNCHECKED
-        : note === ROOT_REPLACED ? null
-            : note === NOT_FOLLOWED ? "Calling again won't change that; if you know the file it leads to, name that file by its own path."
-                : note === LEAVES_MOUNT ? "Calling again won't change that; if a mount holds the file it leads to, name it by its path there."
-                    : note === NOT_REGULAR ? onlyTheHost('put a regular file there')
-                        : note === CHANGED ? 'Calling again checks it afresh.'
-                            : 'Calling again checks disk again; if the same reason comes back, whoever runs this host can fix it on disk.';
-    return `${shown} isn't in the workspace, and disk couldn't be checked: ${sentence(note ?? 'not observed')}${on !== null ? ` ${on}` : ''}`;
+    const on = note === ROOT_REPLACED || cause.ownStep === true ? null
+        : (note === undefined ? null : wayOn(note, cause, 'read')) ?? 'calling again checks disk again; if the same reason comes back, whoever runs this host can fix it on disk';
+    return `${shown} isn't in the workspace, and disk couldn't be checked: ${sentence(note ?? 'not observed')}${on !== null ? ` ${on[0].toUpperCase()}${sentence(on.slice(1))}` : ''}`;
 }
 function namesRoot(path, mount) {
     return `${JSON.stringify(path)} names the root of mount "${mount}", which isn't a file; ls "${mount}" lists the files in it.`;
@@ -6485,17 +6515,17 @@ function readRefusal(err, path) {
         }
         return `${shown} can't be read: ${sentence(err.reason)}`;
     }
-    if (err.stage === 'readlink')
-        return sentence(err.message);
+    if (err instanceof LinkOnTheWay)
+        return `${shown} can't be reached: ${sentence(err.reason)}`;
     switch (err.code) {
         case 'directory':
             return `${shown} is a directory, not a file; ls ${shown} lists what's in it.`;
         case 'symlink':
             return `${shown} is a symlink, and its mount doesn't follow symlinks, so the workspace's tools don't go through it. `
-                + 'Calling again won\'t change that; if you know the file it leads to, name that file by its own path.';
+                + `Calling again won't change that; ${UNFOLLOWED_STEP}.`;
         case 'escape':
             return `${shown} leads through a symlink to a place outside its mount, so the workspace's tools don't reach it. `
-                + 'Calling again won\'t change that; if a mount holds that file, name it by its path there.';
+                + `Calling again won't change that; ${MOUNT_IT}.`;
         case 'changed':
             return `${shown} changed on disk while it was being read. Calling again reads it afresh.`;
         case 'not_found':
@@ -6557,7 +6587,7 @@ function remedyOfLost(lost) {
  */
 function headMoveText(mounts) {
     const one = mounts.length === 1;
-    return `[workspace] Writes to ${listed(mounts.map((name) => `\`${name}\``))} from turns the history no longer holds are still on disk. `
+    return `[${NOTICE_TAG.workspace}] Writes to ${listed(mounts.map((name) => `\`${name}\``))} from turns the history no longer holds are still on disk. `
         + `If ${one ? "it's a git checkout" : "they're git checkouts"}, \`git status\` and \`git diff\` show them; `
         + 'a `git checkout` of a file drops every unstaged change in it, including the ones the history still holds.';
 }