@abot-ai/runtime 1.3.1 → 1.5.0

package/plugins/filesystem/plugin.json

@@ -31,7 +31,7 @@
               "outputPreview": { "path": "output", "kind": "preview" }
             }
           },
-          "skills": [],
+          "skills": ["dev_view_skill"],
           "operations": {
             "inspect_target": {
               "summary": "Inspect one bounded directory sample or bounded file window when unresolved work requires current content. Choose either a locator or numeric lines; locator takes precedence. Truncation metadata distinguishes a complete result from a bounded scan.",

package/plugins/filesystem/skills/dev_view_skill/SKILL.md

@@ -0,0 +1,7 @@
+# Dev View Skill
+
+- `path` identifies one file or directory. For a file, choose numeric `start_line` / `end_line` for a bounded window, or `locator` for one exact literal substring in the bounded scan.
+- A locator is not a keyword or regular-expression search: it must identify one occurrence. It takes precedence over numeric lines. When no unique observed substring is known, use numeric lines without a locator.
+- `context_lines` supplies surrounding lines for a locator. Numeric windows are capped at 240 lines; scan and output truncation are reported separately.
+- `ambiguous_text_locator` is a failed selection. Its bounded candidates contain observed match lines and `nextControls` for numeric reads. Choose a candidate only when it fits the requested operation, and omit `locator` when using its numeric controls. No candidate has been selected or read successfully by that failure.
+- Candidate-list truncation and scan truncation are independent. Missing candidates or unscanned content are unknown; a locator-not-found result supplies no file content.

package/plugins/filesystem/source/atomic-write.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { link, open, rename, rm } from "node:fs/promises";
+import { link, open, rename, rm, type FileHandle } from "node:fs/promises";
 import { posix } from "node:path";
 
 import type { ResolvedRuntimeToolPath } from "../../../src/plugin-sdk/index.js";
@@ -10,7 +10,8 @@ import {
   type MutationTargetVersion,
 } from "./bounded-io.js";
 import { fail, isNodeErrorCode, rethrowFilesystemError } from "./errors.js";
-import { openMutationParent } from "./mutation-parent.js";
+import { closeMutationParent, openMutationParent } from "./mutation-parent.js";
+import { notifyCommittedFileOutput } from "./file-output-presentation.js";
 import { writeWithDirectoryAuthority } from "./directory-authority-write.js";
 
 export async function atomicWriteText(
@@ -18,6 +19,7 @@ export async function atomicWriteText(
     target: ResolvedRuntimeToolPath;
     content: string;
     expectedVersion: MutationTargetVersion;
+    onCommitted?: (root: FileHandle) => void;
   }>,
 ): Promise<void> {
   assertMutationContentSize(input.content);
@@ -70,13 +72,14 @@ export async function atomicWriteText(
       temporaryCreated = !removed;
     }
     await syncDirectoryBestEffort(parent.handle);
+    notifyCommittedFileOutput(parent.rootHandle, input.onCommitted);
   } catch (error: unknown) {
     rethrowFilesystemError(error, "write", input.target.logicalPath);
   } finally {
     if (temporaryCreated) {
       await rm(temporaryPath, { force: true }).catch(() => undefined);
     }
-    await parent.handle.close().catch(() => undefined);
+    await closeMutationParent(parent);
   }
 }
 

package/plugins/filesystem/source/dev-view.ts

@@ -146,7 +146,8 @@ async function viewFile(
   const lines = completeScannedLines(source.text, source.truncated);
   const availableLineCount = Math.max(lines.length, 1);
   const selection = selectWindow({
-    text: source.text,
+    path: input.target.logicalPath,
+    source,
     lines,
     startLine: input.startLine,
     endLine: input.endLine,

package/plugins/filesystem/source/directory-authority-write.ts

@@ -1,3 +1,4 @@
+import type { FileHandle } from "node:fs/promises";
 import type { ResolvedRuntimeToolPath } from "../../../src/plugin-sdk/index.js";
 import {
   DirectoryAuthorityError,
@@ -6,6 +7,7 @@ import {
 import type { MutationTargetVersion } from "./bounded-io.js";
 import { fail, rethrowFilesystemError } from "./errors.js";
 import { openMutationRoot } from "./mutation-parent.js";
+import { notifyCommittedFileOutput } from "./file-output-presentation.js";
 import {
   commitDirectoryWrite,
   type DirectoryWriteInput,
@@ -16,6 +18,7 @@ export async function writeWithDirectoryAuthority(
     target: ResolvedRuntimeToolPath;
     content: string;
     expectedVersion: MutationTargetVersion;
+    onCommitted?: (root: FileHandle) => void;
   }>,
 ): Promise<void> {
   const root = await openMutationRoot(input.target);
@@ -41,6 +44,7 @@ export async function writeWithDirectoryAuthority(
       },
       task: commitDirectoryWrite,
     });
+    notifyCommittedFileOutput(root, input.onCommitted);
   } catch (error) {
     if (error instanceof DirectoryAuthorityError) {
       if (error.code.startsWith("filesystem_")) {

package/plugins/filesystem/source/edit-file.ts

@@ -14,6 +14,7 @@ import {
 import { buildMutationGrounding } from "./draft/grounding.js";
 import { prepareFileDraft } from "./draft/prepare.js";
 import { fail } from "./errors.js";
+import { reportCommittedFileOutput } from "./file-output-presentation.js";
 import type { FilesystemMutationCoordinator } from "./mutation-coordinator.js";
 import type { FilesystemPathService } from "./path-service.js";
 
@@ -139,6 +140,8 @@ export function createEditFileHandler(
         target,
         content: prepared.content,
         expectedVersion: snapshot.version,
+        onCommitted: (root) =>
+          reportCommittedFileOutput(context, target, "updated", root),
       });
       return result;
     });

package/plugins/filesystem/source/file-output-presentation.ts

@@ -0,0 +1,42 @@
+import { fstatSync } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import type {
+  ResolvedRuntimeToolPath,
+  ToolExecutionContext,
+} from "../../../src/plugin-sdk/index.js";
+
+/** A presentation failure must never change an already committed mutation. */
+export function reportCommittedFileOutput(
+  context: ToolExecutionContext | undefined,
+  target: ResolvedRuntimeToolPath,
+  operation: "created" | "updated",
+  root: FileHandle,
+): void {
+  if (!context?.reportFileOutput) return;
+  try {
+    const identity = fstatSync(root.fd, { bigint: true });
+    context.reportFileOutput({
+      target,
+      operation,
+      rootIdentity: {
+        device: String(identity.dev),
+        inode: String(identity.ino),
+        birthtimeNs: String(identity.birthtimeNs),
+      },
+    });
+  } catch {
+    // The host may omit the optional card; the filesystem result stays true.
+  }
+}
+
+/** Called before releasing the mutation root; observers cannot undo a commit. */
+export function notifyCommittedFileOutput(
+  root: FileHandle,
+  onCommitted?: (root: FileHandle) => void,
+): void {
+  try {
+    onCommitted?.(root);
+  } catch {
+    // The committed tool result is independent of optional presentation.
+  }
+}

package/plugins/filesystem/source/mutation-parent.ts

@@ -8,6 +8,7 @@ import { fail, isNodeErrorCode, rethrowFilesystemError } from "./errors.js";
 
 export type MutationParent = Readonly<{
   handle: FileHandle;
+  rootHandle: FileHandle;
   procPath: string;
   targetName: string;
 }>;
@@ -138,32 +139,40 @@ export async function openMutationParent(
     );
   }
 
-  let current = await openDirectory(
+  const rootHandle = await openDirectory(
     target.rootPath,
     target.rootPath,
     target.logicalPath,
   );
+  let current = rootHandle;
   try {
     for (const segment of segments) {
-      const next = await openChildDirectory(
-        current,
-        segment,
-        target.logicalPath,
-      );
-      await current.close();
-      current = next;
+      const previous = current;
+      current = await openChildDirectory(previous, segment, target.logicalPath);
+      if (previous !== rootHandle) {
+        await previous.close().catch(() => undefined);
+      }
     }
     return Object.freeze({
       handle: current,
+      rootHandle,
       procPath: `/proc/self/fd/${current.fd}`,
       targetName,
     });
   } catch (error: unknown) {
-    await current.close().catch(() => undefined);
+    await closeMutationParent({ handle: current, rootHandle });
     throw error;
   }
 }
 
+export async function closeMutationParent(
+  parent: Pick<MutationParent, "handle" | "rootHandle">,
+): Promise<void> {
+  for (const handle of new Set([parent.handle, parent.rootHandle])) {
+    await handle.close().catch(() => undefined);
+  }
+}
+
 function usesIsolatedDirectoryAuthority(): boolean {
   return process.platform === "darwin";
 }

package/plugins/filesystem/source/view-locator.ts

@@ -0,0 +1,141 @@
+import type { BoundedText } from "./bounded-io.js";
+import { fail } from "./errors.js";
+
+const LOCATOR_CANDIDATE_LIMIT = 8;
+
+type LocatorWindowInput = Readonly<{
+  path: string;
+  source: BoundedText;
+  lineCount: number;
+  locator: string;
+  contextLines: number;
+  maxWindowLines: number;
+}>;
+
+type LocatorCandidate = Readonly<{
+  matchStartLine: number;
+  matchEndLine: number;
+  rangeTruncated: boolean;
+  nextControls: Readonly<{
+    path: string;
+    start_line: number;
+    end_line: number;
+  }>;
+}>;
+
+export function selectViewLocatorWindow(input: LocatorWindowInput): Readonly<{
+  startLine: number;
+  endLine: number;
+  rangeTruncated: boolean;
+}> | null {
+  const offsets = collectLocatorOffsets(input.source.text, input.locator);
+  const first = offsets[0];
+  if (first === undefined) return null;
+  if (hasAmbiguousLocatorMatches(offsets)) {
+    rejectAmbiguousLocator(input, offsets);
+  }
+  const candidate = createLocatorCandidate(input, first);
+  return {
+    startLine: candidate.nextControls.start_line,
+    endLine: candidate.nextControls.end_line,
+    rangeTruncated: candidate.rangeTruncated,
+  };
+}
+
+function collectLocatorOffsets(text: string, locator: string): number[] {
+  const offsets: number[] = [];
+  let start = 0;
+  for (let count = 0; count <= LOCATOR_CANDIDATE_LIMIT; count += 1) {
+    const offset = text.indexOf(locator, start);
+    if (offset < 0) break;
+    offsets.push(offset);
+    start = offset + 1;
+  }
+  return offsets;
+}
+
+function hasAmbiguousLocatorMatches(offsets: readonly number[]): boolean {
+  return offsets.length > 1;
+}
+
+function createLocatorCandidate(
+  input: LocatorWindowInput,
+  offset: number,
+): LocatorCandidate {
+  const matchStartLine = lineAtOffset(input.source.text, offset);
+  const matchEndLine = lineAtOffset(
+    input.source.text,
+    offset + Math.max(input.locator.length - 1, 0),
+  );
+  const startLine = Math.max(1, matchStartLine - input.contextLines);
+  const requestedEndLine = Math.min(
+    input.lineCount,
+    matchEndLine + input.contextLines,
+  );
+  const endLine = Math.min(
+    requestedEndLine,
+    startLine + input.maxWindowLines - 1,
+  );
+  return {
+    matchStartLine,
+    matchEndLine,
+    rangeTruncated: requestedEndLine > endLine,
+    nextControls: {
+      path: input.path,
+      start_line: startLine,
+      end_line: endLine,
+    },
+  };
+}
+
+function rejectAmbiguousLocator(
+  input: LocatorWindowInput,
+  offsets: readonly number[],
+): never {
+  const candidates = offsets
+    .slice(0, LOCATOR_CANDIDATE_LIMIT)
+    .map((offset) => createLocatorCandidate(input, offset));
+  const candidatesTruncated = offsets.length > LOCATOR_CANDIDATE_LIMIT;
+  const truncation = {
+    candidateLimit: LOCATOR_CANDIDATE_LIMIT,
+    candidatesTruncated,
+    scanTruncated: input.source.truncated,
+    omittedBytes: input.source.omittedBytes,
+  };
+  fail(
+    "ambiguous_text_locator",
+    [
+      "Locator matched multiple locations; no file window was selected.",
+      "Choose a unique literal locator or select one candidate's numeric controls with locator omitted.",
+      `Path: ${input.path}`,
+      ...candidates.map(
+        ({ matchStartLine, matchEndLine, nextControls }) =>
+          `Match lines ${matchStartLine}-${matchEndLine}: start_line=${nextControls.start_line}, end_line=${nextControls.end_line}`,
+      ),
+      `Candidate list truncated: ${candidatesTruncated}`,
+      `Scan truncated: ${input.source.truncated}; bytes scanned: ${input.source.bytesRead}/${input.source.byteCount}`,
+    ].join("\n"),
+    {
+      path: input.path,
+      candidates,
+      observedMatchCountLowerBound: offsets.length,
+      truncation,
+      eventMeta: {
+        path: input.path,
+        mode: "file",
+        locatorAmbiguous: true,
+        candidateCount: candidates.length,
+        candidatesTruncated,
+        scanTruncated: input.source.truncated,
+      },
+    },
+  );
+}
+
+function lineAtOffset(content: string, offset: number): number {
+  let line = 1;
+  for (let index = 0; index < offset; index += 1) {
+    if (content.charCodeAt(index) === 10) line += 1;
+  }
+  return line;
+}

package/plugins/filesystem/source/view-window.ts

@@ -1,4 +1,5 @@
-import { fail } from "./errors.js";
+import type { BoundedText } from "./bounded-io.js";
+import { selectViewLocatorWindow } from "./view-locator.js";
 
 export const MAX_VIEW_LINES = 240;
 export const DEFAULT_CONTEXT_LINES = 8;
@@ -19,7 +20,8 @@ export function completeScannedLines(
 
 export function selectWindow(
   input: Readonly<{
-    text: string;
+    path: string;
+    source: BoundedText;
     lines: readonly string[];
     startLine?: number;
     endLine?: number;
@@ -32,21 +34,14 @@ export function selectWindow(
     input.endLine ??
     (input.startLine ? input.startLine + MAX_VIEW_LINES - 1 : MAX_VIEW_LINES);
   if (input.locator) {
-    const first = input.text.indexOf(input.locator);
-    if (first < 0) return null;
-    if (input.text.indexOf(input.locator, first + input.locator.length) >= 0) {
-      fail(
-        "ambiguous_text_locator",
-        "Locator matched multiple locations. Use a more specific locator or numeric range.",
-      );
-    }
-    const locatorStart = lineAtOffset(input.text, first);
-    const locatorEnd = lineAtOffset(
-      input.text,
-      first + Math.max(input.locator.length - 1, 0),
-    );
-    startLine = Math.max(1, locatorStart - input.contextLines);
-    endLine = Math.min(input.lines.length, locatorEnd + input.contextLines);
+    return selectViewLocatorWindow({
+      path: input.path,
+      source: input.source,
+      lineCount: input.lines.length,
+      locator: input.locator,
+      contextLines: input.contextLines,
+      maxWindowLines: MAX_VIEW_LINES,
+    });
   }
   if (endLine < startLine) [startLine, endLine] = [endLine, startLine];
   const rangeTruncated = endLine - startLine + 1 > MAX_VIEW_LINES;
@@ -85,11 +80,3 @@ export function parseTrailingRange(value: string): Readonly<{
     endLine: Number.parseInt(match[3] ?? match[2]!, 10),
   });
 }
-
-function lineAtOffset(content: string, offset: number): number {
-  let line = 1;
-  for (let index = 0; index < offset; index += 1) {
-    if (content.charCodeAt(index) === 10) line += 1;
-  }
-  return line;
-}

package/plugins/filesystem/source/write-file.ts

@@ -14,6 +14,7 @@ import {
 import { buildMutationGrounding } from "./draft/grounding.js";
 import { prepareFileDraft } from "./draft/prepare.js";
 import { fail } from "./errors.js";
+import { reportCommittedFileOutput } from "./file-output-presentation.js";
 import type { FilesystemMutationCoordinator } from "./mutation-coordinator.js";
 import type { FilesystemPathService } from "./path-service.js";
 
@@ -113,6 +114,13 @@ export function createWriteFileHandler(
         target,
         content: prepared.content,
         expectedVersion: snapshot.version,
+        onCommitted: (root) =>
+          reportCommittedFileOutput(
+            context,
+            target,
+            previousContent === null ? "created" : "updated",
+            root,
+          ),
       });
       return result;
     });