@nuvin/agent-core 0.2.0-rc.1 → 0.2.0-rc.11

package/dist/tools/file-editing/anchored-file-operations.d.ts

@@ -0,0 +1,38 @@
+import type { NormalizedFileSnapshot } from "./file-snapshot.ts";
+export type CanonicalFileOperation = {
+    operation: "replace";
+    startLine: number;
+    endLine: number;
+    content: string;
+} | {
+    operation: "delete";
+    startLine: number;
+    endLine: number;
+} | {
+    operation: "insert";
+    position: "before" | "after";
+    line: number;
+    content: string;
+};
+export interface FileEditLineNumbers {
+    oldStartLine: number;
+    oldEndLine: number;
+    newStartLine: number;
+    newEndLine: number;
+    oldLineCount: number;
+    newLineCount: number;
+}
+export interface CanonicalFileEditBlock {
+    oldText: string;
+    newText: string;
+    lineNumbers: FileEditLineNumbers;
+}
+export interface PreparedCanonicalFileEdit {
+    afterText: string;
+    operations: readonly CanonicalFileOperation[];
+    blocks: readonly CanonicalFileEditBlock[];
+    requiredLines: readonly number[];
+    payloadDigest: string;
+}
+export declare function prepareCanonicalFileEdit(snapshot: NormalizedFileSnapshot, observedLines: ReadonlySet<number>, operations: readonly CanonicalFileOperation[]): PreparedCanonicalFileEdit;
+//# sourceMappingURL=anchored-file-operations.d.ts.map

package/dist/tools/file-editing/anchored-file-read.d.ts

@@ -0,0 +1,37 @@
+import type { NormalizedFileSnapshot } from "./file-snapshot.ts";
+export interface AnchoredReadFormatRequest {
+    displayPath: string;
+    snapshot: NormalizedFileSnapshot;
+    lineStart?: number;
+    lineEnd?: number;
+    maxBytes: number;
+}
+export interface AnchoredReadFormatResult {
+    output: string;
+    displayedLines: readonly number[];
+    lineStart?: number;
+    lineEnd?: number;
+    truncated: boolean;
+    nextLineStart?: number;
+}
+/**
+ * Format a normalized snapshot as byte-bounded `N:text` rows under a
+ * `[displayPath#TAG]` header.
+ *
+ * Bytes for the header and the deterministic truncation guidance are reserved
+ * before any numbered row is accepted, so the returned text never grows large
+ * enough for a later output-offload transformer to remove rows. Rows are never
+ * split: a row is accepted only when it and the worst-case guidance fit the
+ * budget. The displayed range follows exact FileRead's clamping/ordering.
+ * Provenance is returned separately (`displayedLines`) so the caller records
+ * exactly what the model saw after final formatting.
+ */
+export declare function formatAnchoredFileRead(request: AnchoredReadFormatRequest): AnchoredReadFormatResult;
+/**
+ * True when `text` renders within `maxColumns` terminal display columns.
+ * Width is measured with `string-width` (grapheme-aware display width), never
+ * JavaScript string length, so CJK, combining marks, and emoji sequences are
+ * counted the way a terminal renders them.
+ */
+export declare function isWithinDisplayColumns(text: string, maxColumns: number): boolean;
+//# sourceMappingURL=anchored-file-read.d.ts.map

package/dist/tools/file-editing/atomic-file-write.d.ts

@@ -0,0 +1,19 @@
+export interface AtomicFileSystem {
+    writeFile(path: string, bytes: Uint8Array, options: {
+        mode: number;
+    }): Promise<void>;
+    chmod(path: string, mode: number): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    rm(path: string, options: {
+        force: true;
+    }): Promise<void>;
+}
+/**
+ * Atomically replace `target` with `bytes`, preserving permission mode.
+ *
+ * Writes an unguessable same-directory temporary file, applies `mode & 0o7777`,
+ * renames it over the target, and unconditionally removes the temporary path
+ * in `finally` so every write/chmod/rename failure still cleans up.
+ */
+export declare function atomicReplaceFile(target: string, bytes: Uint8Array, mode: number, fileSystem?: AtomicFileSystem): Promise<void>;
+//# sourceMappingURL=atomic-file-write.d.ts.map

package/dist/tools/file-editing/file-edit-tool.d.ts

@@ -0,0 +1,166 @@
+import type { FileMutationCoordinator } from "./file-mutation-coordinator.ts";
+import type { FileObservationStore } from "./file-observation-store.ts";
+import { type FileEditMode } from "./structured-file-edit-adapter.ts";
+export interface FileEditToolOptions {
+    allowedDirs?: readonly string[];
+    defaultCwd?: string;
+    name?: string;
+    mode?: FileEditMode;
+    observations?: FileObservationStore;
+    mutations?: FileMutationCoordinator;
+    outputBudgetBytes?: number;
+}
+export declare function createFileEditTool(options?: FileEditToolOptions): import("../../shared/types.ts").ToolDefinition<{
+    tag: string;
+    filePath: string;
+    operations: ({
+        content: string;
+        operation: "replace";
+        startLine: number;
+        endLine: number;
+        line?: undefined;
+        position?: undefined;
+    } | {
+        operation: "delete";
+        startLine: number;
+        endLine: number;
+        content?: undefined;
+        line?: undefined;
+        position?: undefined;
+    } | {
+        content: string;
+        line: number;
+        position: "before" | "after";
+        operation: "insert";
+        startLine?: undefined;
+        endLine?: undefined;
+    })[];
+    description?: string | undefined;
+    dryRun?: boolean | undefined;
+} | {
+    patch: string;
+    description?: string | undefined;
+    dryRun?: boolean | undefined;
+}, import("../../shared/types.ts").ToolOutputEnvelope, undefined, {
+    readonly type: "object";
+    readonly properties: {
+        readonly filePath: {
+            readonly type: "string";
+        };
+        readonly tag: {
+            readonly type: "string";
+        };
+        readonly description: {
+            readonly type: "string";
+        };
+        readonly operations: {
+            readonly type: "array";
+            readonly items: {
+                readonly anyOf: readonly [{
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly operation: {
+                            readonly type: "string";
+                            readonly enum: readonly ["replace"];
+                        };
+                        readonly startLine: {
+                            readonly type: "number";
+                        };
+                        readonly endLine: {
+                            readonly type: "number";
+                        };
+                        readonly content: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly required: readonly ["operation", "startLine", "endLine", "content"];
+                    readonly additionalProperties: false;
+                }, {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly operation: {
+                            readonly type: "string";
+                            readonly enum: readonly ["delete"];
+                        };
+                        readonly startLine: {
+                            readonly type: "number";
+                        };
+                        readonly endLine: {
+                            readonly type: "number";
+                        };
+                    };
+                    readonly required: readonly ["operation", "startLine", "endLine"];
+                    readonly additionalProperties: false;
+                }, {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly operation: {
+                            readonly type: "string";
+                            readonly enum: readonly ["insert"];
+                        };
+                        readonly position: {
+                            readonly type: "string";
+                            readonly enum: readonly ["before", "after"];
+                        };
+                        readonly line: {
+                            readonly type: "number";
+                        };
+                        readonly content: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly required: readonly ["operation", "position", "line", "content"];
+                    readonly additionalProperties: false;
+                }];
+            };
+        };
+        readonly dryRun: {
+            readonly type: "boolean";
+        };
+    };
+    readonly required: readonly ["filePath", "tag", "operations"];
+    readonly additionalProperties: false;
+} | {
+    readonly type: "object";
+    readonly properties: {
+        readonly patch: {
+            readonly type: "string";
+        };
+        readonly description: {
+            readonly type: "string";
+        };
+        readonly dryRun: {
+            readonly type: "boolean";
+        };
+    };
+    readonly required: readonly ["patch"];
+    readonly additionalProperties: false;
+}> | import("../../shared/types.ts").ToolDefinition<{
+    filePath: string;
+    oldText: string;
+    newText: string;
+    description?: string | undefined;
+    dryRun?: boolean | undefined;
+}, import("../../shared/types.ts").ToolOutputEnvelope, undefined, {
+    type: "object";
+    properties: {
+        filePath: {
+            type: "string";
+        };
+        description: {
+            type: "string";
+            description: string;
+        };
+        oldText: {
+            type: "string";
+        };
+        newText: {
+            type: "string";
+        };
+        dryRun: {
+            type: "boolean";
+        };
+    };
+    required: readonly ["filePath", "oldText", "newText"];
+}>;
+//# sourceMappingURL=file-edit-tool.d.ts.map

package/dist/tools/file-editing/file-mutation-coordinator.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Runtime-wide per-canonical-path async lock.
+ *
+ * One queued tail per canonical path; a new caller chains behind the live
+ * tail and becomes the new tail. The map entry is removed only when that
+ * exact tail settles, so a stale settled tail never blocks later callers and
+ * a rejected task cannot poison the queue.
+ */
+export declare class FileMutationCoordinator {
+    private readonly tails;
+    runExclusive<T>(canonicalPath: string, signal: AbortSignal, task: () => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=file-mutation-coordinator.d.ts.map

package/dist/tools/file-editing/file-mutation.d.ts

@@ -0,0 +1,15 @@
+export interface ExactTextReplacement {
+    before: string;
+    after: string;
+    lineNumbers: {
+        oldStartLine: number;
+        oldEndLine: number;
+        newStartLine: number;
+        newEndLine: number;
+        oldLineCount: number;
+        newLineCount: number;
+    };
+}
+export declare function sha256Bytes(value: string | Uint8Array): string;
+export declare function replaceFirstExact(before: string, oldText: string, newText: string): ExactTextReplacement | undefined;
+//# sourceMappingURL=file-mutation.d.ts.map

package/dist/tools/{file-new-tool.d.ts → file-editing/file-new-tool.d.ts}

@@ -1,12 +1,15 @@
+import type { FileObservationStore } from "./file-observation-store.ts";
 export interface FileNewToolOptions {
     allowedDirs?: readonly string[];
     defaultCwd?: string;
     name?: string;
+    observations?: FileObservationStore;
+    anchored?: boolean;
 }
-export declare function createFileNewTool(options?: FileNewToolOptions): import("../shared/types.ts").ToolDefinition<{
+export declare function createFileNewTool(options?: FileNewToolOptions): import("../../shared/types.ts").ToolDefinition<{
     content: string;
     filePath: string;
-}, import("../shared/types.ts").ToolOutputEnvelope, undefined, {
+}, import("../../shared/types.ts").ToolOutputEnvelope, undefined, {
     type: "object";
     properties: {
         filePath: {

package/dist/tools/file-editing/file-observation-store.d.ts

@@ -0,0 +1,40 @@
+import type { NormalizedFileSnapshot } from "./file-snapshot.ts";
+export declare const FILE_OBSERVATION_LIMITS: {
+    readonly maxPaths: 30;
+    readonly maxVersionsPerPath: 4;
+    readonly maxSnapshotBytes: number;
+};
+export interface ObservedFileSnapshot {
+    snapshot: NormalizedFileSnapshot;
+    observedLines: ReadonlySet<number>;
+}
+export interface FileObservationStoreOptions {
+    limits?: {
+        maxPaths: number;
+        maxVersionsPerPath: number;
+        maxSnapshotBytes: number;
+    };
+    tagForDigest?: (digest: string) => string;
+}
+export declare class FileObservationStore {
+    private readonly limits;
+    private readonly tagForDigest?;
+    private sessionId;
+    private versionsByPath;
+    private recency;
+    private totalBytes;
+    private bytesByDigest;
+    private noChangeCounters;
+    constructor(options?: FileObservationStoreOptions);
+    bindSession(sessionId: string): void;
+    record(snapshot: NormalizedFileSnapshot, observedLines: readonly number[]): ObservedFileSnapshot;
+    resolve(canonicalPath: string, tag: string): ObservedFileSnapshot;
+    recordNoChange(canonicalPath: string, payloadDigest: string): number;
+    resetNoChange(canonicalPath: string): void;
+    clear(): void;
+    private touchPath;
+    private evictLeastRecentlyUsedPath;
+    private acquireBytes;
+    private releaseBytes;
+}
+//# sourceMappingURL=file-observation-store.d.ts.map

package/dist/tools/{file-read-tool.d.ts → file-editing/file-read-tool.d.ts}

@@ -1,13 +1,19 @@
+import type { ToolOutputEnvelope } from "../../shared/types.ts";
+import type { FileObservationStore } from "./file-observation-store.ts";
+import type { FileEditMode } from "./structured-file-edit-adapter.ts";
 export interface FileReadToolOptions {
     allowedDirs?: readonly string[];
     defaultCwd?: string;
     name?: string;
+    mode?: FileEditMode;
+    observations?: FileObservationStore;
+    outputBudgetBytes?: number;
 }
-export declare function createFileReadTool(options?: FileReadToolOptions): import("../shared/types.ts").ToolDefinition<{
+export declare function createFileReadTool(options?: FileReadToolOptions): import("../../shared/types.ts").ToolDefinition<{
     path: string;
     lineStart?: number | undefined;
     lineEnd?: number | undefined;
-}, import("../shared/types.ts").ToolOutputEnvelope, undefined, {
+}, ToolOutputEnvelope, undefined, {
     type: "object";
     properties: {
         path: {

package/dist/tools/file-editing/file-snapshot.d.ts

@@ -0,0 +1,16 @@
+export type FileEol = "lf" | "crlf";
+export interface NormalizedFileSnapshot {
+    canonicalPath: string;
+    text: string;
+    lines: readonly string[];
+    finalNewline: boolean;
+    bom: boolean;
+    eol: FileEol;
+    digest: string;
+    tag: string;
+    utf8Bytes: number;
+    recordedAt: number;
+}
+export declare function createNormalizedFileSnapshot(canonicalPath: string, bytes: Uint8Array, recordedAt?: number): NormalizedFileSnapshot;
+export declare function serializeNormalizedFile(text: string, style: Pick<NormalizedFileSnapshot, "bom" | "eol">): Buffer;
+//# sourceMappingURL=file-snapshot.d.ts.map

package/dist/tools/file-editing/hashline-file-edit-adapter.d.ts

@@ -0,0 +1,19 @@
+import { type CanonicalAnchoredEditRequest } from "./structured-file-edit-adapter.ts";
+export declare const hashlineFileEditInputSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly patch: {
+            readonly type: "string";
+        };
+        readonly description: {
+            readonly type: "string";
+        };
+        readonly dryRun: {
+            readonly type: "boolean";
+        };
+    };
+    readonly required: readonly ["patch"];
+    readonly additionalProperties: false;
+};
+export declare function parseHashlineFileEditInput(input: unknown): CanonicalAnchoredEditRequest;
+//# sourceMappingURL=hashline-file-edit-adapter.d.ts.map

package/dist/tools/file-editing/structured-file-edit-adapter.d.ts

@@ -0,0 +1,94 @@
+import type { CanonicalFileOperation } from "./anchored-file-operations.ts";
+export type FileEditMode = "exact" | "anchored-json" | "hashline";
+export type AnchoredFileEditMode = Exclude<FileEditMode, "exact">;
+export interface CanonicalAnchoredEditRequest {
+    filePath: string;
+    tag: string;
+    description?: string;
+    operations: readonly CanonicalFileOperation[];
+    dryRun: boolean;
+}
+export declare const MAX_ANCHORED_OPERATIONS = 100;
+export declare const MAX_ANCHORED_CONTENT_BYTES: number;
+export declare const structuredFileEditInputSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly filePath: {
+            readonly type: "string";
+        };
+        readonly tag: {
+            readonly type: "string";
+        };
+        readonly description: {
+            readonly type: "string";
+        };
+        readonly operations: {
+            readonly type: "array";
+            readonly items: {
+                readonly anyOf: readonly [{
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly operation: {
+                            readonly type: "string";
+                            readonly enum: readonly ["replace"];
+                        };
+                        readonly startLine: {
+                            readonly type: "number";
+                        };
+                        readonly endLine: {
+                            readonly type: "number";
+                        };
+                        readonly content: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly required: readonly ["operation", "startLine", "endLine", "content"];
+                    readonly additionalProperties: false;
+                }, {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly operation: {
+                            readonly type: "string";
+                            readonly enum: readonly ["delete"];
+                        };
+                        readonly startLine: {
+                            readonly type: "number";
+                        };
+                        readonly endLine: {
+                            readonly type: "number";
+                        };
+                    };
+                    readonly required: readonly ["operation", "startLine", "endLine"];
+                    readonly additionalProperties: false;
+                }, {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly operation: {
+                            readonly type: "string";
+                            readonly enum: readonly ["insert"];
+                        };
+                        readonly position: {
+                            readonly type: "string";
+                            readonly enum: readonly ["before", "after"];
+                        };
+                        readonly line: {
+                            readonly type: "number";
+                        };
+                        readonly content: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly required: readonly ["operation", "position", "line", "content"];
+                    readonly additionalProperties: false;
+                }];
+            };
+        };
+        readonly dryRun: {
+            readonly type: "boolean";
+        };
+    };
+    readonly required: readonly ["filePath", "tag", "operations"];
+    readonly additionalProperties: false;
+};
+export declare function parseStructuredFileEditInput(input: unknown): CanonicalAnchoredEditRequest;
+//# sourceMappingURL=structured-file-edit-adapter.d.ts.map

package/dist/tools/file-editing/workspace-paths.d.ts

@@ -0,0 +1,20 @@
+export declare function resolveWorkspacePath(rootDir: string, inputPath: string): string;
+export declare function resolveAllowedPath(rootDir: string, allowedDirs: readonly string[], inputPath: string): string;
+export interface CanonicalAllowedFile {
+    authoredPath: string;
+    lexicalPath: string;
+    canonicalPath: string;
+}
+/**
+ * Anchored-only canonical authorization.
+ *
+ * The exact lexical `resolveAllowedPath()` check always runs first and is
+ * authoritative for rejection. The target and every currently live allowed
+ * root are then re-resolved with `realpath()` on each call; roots that no
+ * longer exist are discarded. The canonical target must sit inside one
+ * canonical root and `stat()` must show a regular file.
+ */
+export declare function resolveCanonicalAllowedFile(rootDir: string, allowedDirs: readonly string[], inputPath: string): Promise<CanonicalAllowedFile>;
+export declare function assertWorkspaceFile(filePath: string): Promise<void>;
+export declare function isProbablyBinary(buffer: Buffer): boolean;
+//# sourceMappingURL=workspace-paths.d.ts.map

package/dist/tools/index.d.ts

@@ -1,31 +1,45 @@
 export * from "../lsp/index.ts";
-export * from "./ask-user-tool.ts";
-export * from "./background-process-registry.ts";
-export * from "./bash-output-tool.ts";
-export * from "./bash-tool.ts";
-export * from "./command-tool.ts";
-export * from "./file-edit-tool.ts";
-export * from "./file-new-tool.ts";
-export * from "./file-read-tool.ts";
-export * from "./glob-tool.ts";
-export * from "./grep-tool.ts";
-export * from "./internal-tool-runtime.ts";
-export * from "./kill-shell-tool.ts";
-export * from "./ls-tool.ts";
-export * from "./lsp-tool.ts";
-export * from "./mcp-oauth-provider.ts";
-export * from "./mcp-server-manager.ts";
-export * from "./mcp-tool-adapter.ts";
-export * from "./mock-tool-runtime.ts";
-export * from "./ripgrep.ts";
-export * from "./runtime-manager-tools.ts";
-export * from "./skill-tool.ts";
-export * from "./todo-write-tool.ts";
-export * from "./tool-output-offload.ts";
-export * from "./tools.ts";
-export * from "./update-topic-tool.ts";
-export * from "./view-file-tool.ts";
-export * from "./web-fetch-tool.ts";
-export * from "./web-search-tool.ts";
-export * from "./workspace-paths.ts";
+export * from "./core/internal-tool-runtime.ts";
+export * from "./core/mock-tool-runtime.ts";
+export * from "./core/runtime-manager-tools.ts";
+export * from "./core/tool-output-offload.ts";
+export * from "./core/tools.ts";
+export { type AnchoredFileEditEnvironment, type AnchoredFileEditStructuredResult, type CanonicalFileEditPreview, executeAnchoredFileEdit, MAX_ANCHORED_PREVIEW_BYTES, prepareAnchoredFileEditApproval, } from "./file-editing/anchored-file-edit.ts";
+export * from "./file-editing/anchored-file-errors.ts";
+export * from "./file-editing/anchored-file-operations.ts";
+export * from "./file-editing/anchored-file-read.ts";
+export * from "./file-editing/file-edit-tool.ts";
+export * from "./file-editing/file-mutation.ts";
+export * from "./file-editing/file-mutation-coordinator.ts";
+export * from "./file-editing/file-new-tool.ts";
+export * from "./file-editing/file-observation-store.ts";
+export * from "./file-editing/file-read-tool.ts";
+export * from "./file-editing/file-snapshot.ts";
+export { hashlineFileEditInputSchema } from "./file-editing/hashline-file-edit-adapter.ts";
+export { type AnchoredFileEditMode, type CanonicalAnchoredEditRequest, type FileEditMode, MAX_ANCHORED_CONTENT_BYTES, MAX_ANCHORED_OPERATIONS, structuredFileEditInputSchema, } from "./file-editing/structured-file-edit-adapter.ts";
+export * from "./file-editing/workspace-paths.ts";
+export * from "./mcp/mcp-connection-generation.ts";
+export * from "./mcp/mcp-oauth-provider.ts";
+export * from "./mcp/mcp-safe-error.ts";
+export { extractOwnedMcpSafeError } from "./mcp/mcp-safe-error-provenance.ts";
+export * from "./mcp/mcp-server-manager.ts";
+export * from "./mcp/mcp-tool-adapter.ts";
+export * from "./search/glob-tool.ts";
+export * from "./search/grep-engine.ts";
+export * from "./search/grep-tool.ts";
+export * from "./search/ls-tool.ts";
+export * from "./search/ripgrep.ts";
+export * from "./search/view-file-tool.ts";
+export * from "./session/ask-user-tool.ts";
+export * from "./session/lsp-tool.ts";
+export * from "./session/skill-tool.ts";
+export * from "./session/todo-write-tool.ts";
+export * from "./session/update-topic-tool.ts";
+export * from "./shell/background-process-registry.ts";
+export * from "./shell/bash-output-tool.ts";
+export * from "./shell/bash-tool.ts";
+export * from "./shell/command-tool.ts";
+export * from "./shell/kill-shell-tool.ts";
+export * from "./web/web-fetch-tool.ts";
+export * from "./web/web-search-tool.ts";
 //# sourceMappingURL=index.d.ts.map