@nia-teams/four-tools 0.0.0-stage → 0.1.0

package/dist/core/edit-engine.js

@@ -0,0 +1,93 @@
+const normalize = (s) => s
+    .normalize('NFKC')
+    .replace(/[\u2018\u2019\u201A\u201B]/g, "'")
+    .replace(/[\u201C\u201D\u201E\u201F]/g, '"')
+    .replace(/[\u2010-\u2015\u2212]/g, '-')
+    .replace(/[\u00A0\u202F\u2007]/g, ' ');
+/** Only grapheme boundaries map back to source offsets; expansions are indivisible. */
+function mapped(source) {
+    let text = '';
+    const starts = new Map();
+    const ends = new Map();
+    const lines = source.split(/\r\n|\n|\r/);
+    let offset = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trimEnd();
+        starts.set(text.length, offset);
+        ends.set(text.length, offset);
+        for (const segment of new Intl.Segmenter(undefined, {
+            granularity: 'grapheme',
+        }).segment(trimmed)) {
+            starts.set(text.length, offset + segment.index);
+            text += normalize(segment.segment);
+            ends.set(text.length, offset + segment.index + segment.segment.length);
+        }
+        const eol = source.slice(offset + line.length).startsWith('\r\n') ? 2 : 1;
+        if (i < lines.length - 1) {
+            text += '\n';
+            offset += line.length + eol;
+            starts.set(text.length, offset);
+            ends.set(text.length, offset);
+        }
+    }
+    return { text, starts, ends };
+}
+function occurrences(haystack, needle, overlapping = false) {
+    const found = [];
+    for (let at = 0; (at = haystack.indexOf(needle, at)) !== -1; at += overlapping ? 1 : needle.length)
+        found.push(at);
+    return found;
+}
+export function applyUniqueEdit(original, oldString, newString) {
+    if (!oldString)
+        return { ok: false, reason: 'empty_old_string' };
+    if (oldString === newString)
+        return { ok: false, reason: 'unchanged' };
+    const bom = original.startsWith('\uFEFF') ? '\uFEFF' : '';
+    const source = original.slice(bom.length);
+    const exact = occurrences(source, oldString);
+    if (exact.length > 1)
+        return { ok: false, reason: 'not_unique', count: exact.length };
+    let start, end;
+    let matchedBy = 'exact';
+    if (exact.length) {
+        start = exact[0];
+        end = start + oldString.length;
+    }
+    else {
+        const mapping = mapped(source);
+        const needle = mapped(oldString).text;
+        if (!needle)
+            return { ok: false, reason: 'not_found' };
+        const matches = occurrences(mapping.text, needle, true).filter((at) => mapping.starts.has(at) && mapping.ends.has(at + needle.length));
+        if (!matches.length)
+            return { ok: false, reason: 'not_found' };
+        if (matches.length > 1)
+            return {
+                ok: false,
+                reason: 'ambiguous_normalized',
+                count: matches.length,
+            };
+        start = mapping.starts.get(matches[0]);
+        end = mapping.ends.get(matches[0] + needle.length);
+        matchedBy = 'normalized';
+        // Prefer the first replaced newline, then the nearest surrounding newline.
+        const local = source.slice(start, end).match(/\r\n|\n/);
+        const before = [...source.slice(0, start).matchAll(/\r\n|\n/g)].at(-1);
+        const after = source.slice(end).match(/\r\n|\n/);
+        const nearby = before &&
+            (!after || start - (before.index + before[0].length) <= after.index)
+            ? before
+            : after;
+        const eol = local?.[0] ?? nearby?.[0];
+        if (eol)
+            newString = newString.replace(/\r\n|\n/g, eol);
+    }
+    return {
+        ok: true,
+        content: bom + source.slice(0, start) + newString + source.slice(end),
+        matchedBy,
+        line: source.slice(0, start).split(/\r\n|\n|\r/).length,
+    };
+}

package/dist/core/env.d.ts

@@ -0,0 +1,149 @@
+export type Platform = 'linux' | 'darwin';
+export type ResolvedPath = {
+    resolvedPath: string;
+    canonicalPath: string;
+};
+export type FileStat = {
+    exists: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+    size: number;
+    mode: number;
+    mtimeMs: number;
+};
+export type ReadRangeResult = {
+    content: string;
+    startLine: number;
+    endLine: number;
+    totalLines: number;
+    truncatedByBytes: boolean;
+    isBinary?: boolean;
+    singleLineExceeded?: boolean;
+};
+export type ExecOptions = {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    maxOutputBytes?: number;
+    onOutput?: (chunk: Uint8Array, stream: 'stdout' | 'stderr') => void;
+};
+export type ExecResult = {
+    output: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    aborted: boolean;
+    truncated: boolean;
+    spillPath?: string;
+    durationMs?: number;
+};
+export type TerminalStatus = 'running' | 'exited' | 'signaled' | 'error';
+export type TerminalInfo = {
+    id: string;
+    name: string;
+    command: string;
+    cwd: string;
+    status: TerminalStatus;
+    exitCode: number | null;
+    signal: string | null;
+    startedAt: number;
+    endedAt?: number;
+    linesBuffered?: number;
+};
+export type TerminalExitEvent = {
+    id: string;
+    name: string;
+    command: string;
+    cwd: string;
+    status: Exclude<TerminalStatus, 'running'>;
+    exitCode: number | null;
+    signal: string | null;
+    durationMs: number;
+    outputPreview: string;
+    logPath?: string;
+};
+export interface ManagedTerminalBackend {
+    execWithHandoff(input: {
+        command: string;
+        cwd?: string;
+        env?: Record<string, string>;
+        handoffAfterMs: number;
+        maxOutputBytes?: number;
+        signal?: AbortSignal;
+        onAbort?: 'handoff' | 'kill';
+    }): Promise<{
+        completed: true;
+        output: string;
+        stdout?: string;
+        stderr?: string;
+        durationMs?: number;
+        exitCode: number | null;
+        signal: string | null;
+        truncated: boolean;
+        spillPath?: string;
+    } | {
+        completed: false;
+        terminal: TerminalInfo;
+        partialOutput: string;
+        handoffReason?: 'timeout' | 'abort';
+    }>;
+    create(input: {
+        command: string;
+        cwd?: string;
+        name?: string;
+        env?: Record<string, string>;
+        notifyOnExit?: boolean;
+    }): Promise<TerminalInfo>;
+    list(): Promise<TerminalInfo[]>;
+    read(input: {
+        id: string;
+        offset?: number;
+        limit?: number;
+    }): Promise<{
+        content: string;
+        lines?: string[];
+        nextOffset?: number;
+        startLine: number;
+        endLine: number;
+        totalLines: number;
+        status: TerminalStatus;
+        exitCode: number | null;
+    }>;
+    signal(input: {
+        id: string;
+        signal: 'SIGINT' | 'SIGTERM' | 'SIGKILL';
+    }): Promise<TerminalInfo>;
+    destroy(input: {
+        id: string;
+    }): Promise<void>;
+}
+export interface ExecutionEnv {
+    readonly id: string;
+    readonly platform: Platform;
+    readonly cwd: string;
+    resolvePath(inputPath: string, options?: {
+        cwd?: string;
+        mustExist?: boolean;
+    }): Promise<ResolvedPath>;
+    stat(resolvedPath: string): Promise<FileStat>;
+    readRange(resolvedPath: string, options?: {
+        offsetLine?: number;
+        limitLines?: number;
+        maxBytes?: number;
+        signal?: AbortSignal;
+    }): Promise<ReadRangeResult>;
+    readText(resolvedPath: string, options?: {
+        maxBytes?: number;
+        signal?: AbortSignal;
+    }): Promise<string>;
+    writeText(resolvedPath: string, content: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        bytesWritten: number;
+    }>;
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    terminals?: ManagedTerminalBackend;
+}

package/dist/core/env.js

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

package/dist/core/index.d.ts

@@ -0,0 +1,23 @@
+export * from './env.js';
+export * from './types.js';
+export * from './mutation-queue.js';
+export * from './edit-engine.js';
+export * from './tools/read.js';
+export * from './tools/write.js';
+export * from './tools/edit.js';
+export * from './tools/shell.js';
+export type { FileToolOptions } from './tools/shared.js';
+import type { ExecutionEnv } from './env.js';
+import type { FourTool, ToolHooks } from './types.js';
+import { FileMutationQueue } from './mutation-queue.js';
+import { type ReadToolOptions } from './tools/read.js';
+import { type ShellToolOptions } from './tools/shell.js';
+export interface FourToolsOptions {
+    hooks?: ToolHooks;
+    mutationQueue?: FileMutationQueue;
+    maxReadBytes?: number;
+    read?: ReadToolOptions;
+    maxEditBytes?: number;
+    shell?: ShellToolOptions;
+}
+export declare function createFourTools(env: ExecutionEnv, options?: FourToolsOptions): FourTool[];

package/dist/core/index.js

@@ -0,0 +1,33 @@
+export * from './env.js';
+export * from './types.js';
+export * from './mutation-queue.js';
+export * from './edit-engine.js';
+export * from './tools/read.js';
+export * from './tools/write.js';
+export * from './tools/edit.js';
+export * from './tools/shell.js';
+import { FileMutationQueue } from './mutation-queue.js';
+import { createReadTool } from './tools/read.js';
+import { createWriteTool } from './tools/write.js';
+import { createEditTool } from './tools/edit.js';
+import { createShellTool } from './tools/shell.js';
+export function createFourTools(env, options = {}) {
+    const queue = options.mutationQueue ?? new FileMutationQueue();
+    return [
+        createReadTool(env, {
+            hooks: options.hooks,
+            maxBytes: options.maxReadBytes,
+            ...options.read,
+        }),
+        createWriteTool(env, { queue, hooks: options.hooks }),
+        createEditTool(env, {
+            queue,
+            hooks: options.hooks,
+            maxBytes: options.maxEditBytes,
+        }),
+        createShellTool(env, {
+            ...options.shell,
+            hooks: options.shell?.hooks ?? options.hooks,
+        }),
+    ];
+}

package/dist/core/mutation-queue.d.ts

@@ -0,0 +1,6 @@
+export declare class FileMutationQueue {
+    private readonly tails;
+    run<T>(envId: string, canonicalPath: string, mutate: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+}
+/** Independent factory calls also share file serialization by default. */
+export declare const defaultMutationQueue: FileMutationQueue;

package/dist/core/mutation-queue.js

@@ -0,0 +1,24 @@
+export class FileMutationQueue {
+    tails = new Map();
+    async run(envId, canonicalPath, mutate, signal) {
+        const key = `${envId}\0${canonicalPath}`;
+        const previous = this.tails.get(key) ?? Promise.resolve();
+        let release;
+        const tail = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.tails.set(key, tail);
+        await previous;
+        try {
+            signal?.throwIfAborted();
+            return await mutate();
+        }
+        finally {
+            release();
+            if (this.tails.get(key) === tail)
+                this.tails.delete(key);
+        }
+    }
+}
+/** Independent factory calls also share file serialization by default. */
+export const defaultMutationQueue = new FileMutationQueue();

package/dist/core/tools/edit.d.ts

@@ -0,0 +1,4 @@
+import type { ExecutionEnv } from '../env.js';
+import type { FourTool } from '../types.js';
+import { type FileToolOptions } from './shared.js';
+export declare function createEditTool(env: ExecutionEnv, options?: FileToolOptions): FourTool;

package/dist/core/tools/edit.js

@@ -0,0 +1,43 @@
+import { toolContracts } from '../contracts.js';
+import { applyUniqueEdit } from '../edit-engine.js';
+import { defaultMutationQueue } from '../mutation-queue.js';
+import { aliases, safe, text } from './shared.js';
+export function createEditTool(env, options = {}) {
+    return safe({
+        name: 'edit',
+        ...structuredClone(toolContracts.edit),
+        concurrency: 'parallel',
+        async execute(raw, ctx = {}) {
+            ctx.signal?.throwIfAborted();
+            const input = aliases(raw), displayPath = text(input, 'path'), oldString = text(input, 'old_string'), newString = text(input, 'new_string');
+            const path = await env.resolvePath(displayPath, { mustExist: true });
+            return (options.queue ?? defaultMutationQueue).run(env.id, path.canonicalPath, async () => {
+                const original = await env.readText(path.resolvedPath, {
+                    maxBytes: options.maxBytes,
+                    signal: ctx.signal,
+                });
+                const result = applyUniqueEdit(original, oldString, newString);
+                if (!result.ok) {
+                    if (result.count)
+                        return `ERROR: old_string found ${result.count} times, must be unique\n`;
+                    if (result.reason === 'not_found')
+                        return 'ERROR: old_string not found in file\n';
+                    return `ERROR: ${result.reason}`;
+                }
+                await env.writeText(path.resolvedPath, result.content, {
+                    signal: ctx.signal,
+                });
+                const message = 'OK: replacement applied';
+                const guidance = await options.hooks?.afterMutate?.({
+                    path: path.resolvedPath,
+                    canonicalPath: path.canonicalPath,
+                    operation: 'edit',
+                    charCount: [...result.content].length,
+                    content: result.content,
+                    context: ctx,
+                });
+                return guidance ? { content: message, guidance } : message;
+            }, ctx.signal);
+        },
+    });
+}

package/dist/core/tools/read.d.ts

@@ -0,0 +1,10 @@
+import type { ExecutionEnv } from '../env.js';
+import type { FourTool } from '../types.js';
+import { type FileToolOptions } from './shared.js';
+export interface ReadToolOptions extends Omit<FileToolOptions, 'maxBytes'> {
+    maxBytes?: number | false;
+    maxLines?: number | false;
+    /** Delegate output budgeting to the runtime instead of truncating in the tool. */
+    truncate?: boolean;
+}
+export declare function createReadTool(env: ExecutionEnv, options?: ReadToolOptions): FourTool;

package/dist/core/tools/read.js

@@ -0,0 +1,45 @@
+import { toolContracts } from '../contracts.js';
+import { aliases, number, safe, text } from './shared.js';
+export function createReadTool(env, options = {}) {
+    return safe({
+        name: 'read',
+        ...structuredClone(toolContracts.read),
+        concurrency: 'parallel',
+        async execute(input, ctx = {}) {
+            ctx.signal?.throwIfAborted();
+            const path = await env.resolvePath(text(aliases(input), 'path'), {
+                mustExist: true,
+            });
+            const maxLines = options.truncate === false || options.maxLines === false
+                ? Number.MAX_SAFE_INTEGER
+                : number(options.maxLines, 2000);
+            const maxBytes = options.truncate === false || options.maxBytes === false
+                ? Number.MAX_SAFE_INTEGER
+                : number(options.maxBytes, 50 * 1024);
+            const requested = number(input.limit, Number.MAX_SAFE_INTEGER);
+            const result = await env.readRange(path.resolvedPath, {
+                offsetLine: number(input.offset, 1),
+                limitLines: Math.min(requested, maxLines),
+                maxBytes,
+                signal: ctx.signal,
+            });
+            if (result.isBinary)
+                return 'Error reading file: Binary file cannot be displayed as text';
+            const capped = result.truncatedByBytes ||
+                (requested > maxLines && result.endLine < result.totalLines);
+            const content = result.content +
+                (capped
+                    ? `\n\n[Showing lines ${result.startLine}-${result.endLine} of ${result.totalLines}. Use offset=${result.endLine + 1} to continue.]`
+                    : '');
+            const guidance = await options.hooks?.afterRead?.({
+                path: path.resolvedPath,
+                canonicalPath: path.canonicalPath,
+                content: input.offset === undefined && input.limit === undefined && !capped
+                    ? result.content
+                    : undefined,
+                context: ctx,
+            });
+            return guidance ? { content, guidance } : content;
+        },
+    });
+}

package/dist/core/tools/shared.d.ts

@@ -0,0 +1,20 @@
+import type { FourTool, FourToolContext, FourToolResult, ToolHooks } from '../types.js';
+import type { FileMutationQueue } from '../mutation-queue.js';
+export interface FileToolOptions {
+    maxBytes?: number;
+    hooks?: ToolHooks;
+    queue?: FileMutationQueue;
+}
+export declare const schema: (properties: Record<string, unknown>, required?: string[]) => {
+    type: string;
+    additionalProperties: boolean;
+    properties: Record<string, unknown>;
+    required: string[];
+};
+export declare function aliases(input: Record<string, unknown>): Record<string, unknown>;
+export declare function text(input: Record<string, unknown>, key: string): string;
+export declare function number(value: unknown, fallback: number, minimum?: number): number;
+export type ToolImplementation = Omit<FourTool, 'execute'> & {
+    execute(input: Record<string, unknown>, ctx?: FourToolContext): Promise<FourToolResult>;
+};
+export declare function safe(tool: ToolImplementation): FourTool;

package/dist/core/tools/shared.js

@@ -0,0 +1,51 @@
+export const schema = (properties, required = []) => ({ type: 'object', additionalProperties: false, properties, required });
+export function aliases(input) {
+    return {
+        ...input,
+        path: input.path ?? input.file_path ?? input.filepath,
+        old_string: input.old_string ?? input.old_str ?? input.oldText ?? input.oldString,
+        new_string: input.new_string ?? input.new_str ?? input.newText ?? input.newString,
+    };
+}
+export function text(input, key) {
+    if (typeof input[key] !== 'string')
+        throw new Error(`${key} must be a string`);
+    return input[key];
+}
+export function number(value, fallback, minimum = 1) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        throw new Error('Expected a finite number');
+    return Math.max(minimum, Math.trunc(value));
+}
+export function safe(tool) {
+    async function execute(input, ctx = {}) {
+        try {
+            // Match optional-field cleaning in the native host, while accepting file aliases.
+            const clean = Object.fromEntries(Object.entries(input).filter(([, value]) => value !== null && value !== undefined));
+            const result = await tool.execute(clean, ctx);
+            if (typeof result !== 'string' &&
+                typeof ctx.workspaceId === 'string' &&
+                typeof ctx.teamId === 'string' &&
+                typeof ctx.model === 'string') {
+                if (result.guidance?.length)
+                    ctx.aiPostContext = [
+                        ...(ctx.aiPostContext ?? []),
+                        ...result.guidance,
+                    ];
+                return result.content;
+            }
+            return result;
+        }
+        catch (error) {
+            const prefix = tool.name === 'read'
+                ? 'Error reading file:'
+                : tool.name === 'write'
+                    ? 'Error writing file:'
+                    : 'ERROR:';
+            return (prefix + ' ' + (error instanceof Error ? error.message : String(error)));
+        }
+    }
+    return { ...tool, execute };
+}

package/dist/core/tools/shell.d.ts

@@ -0,0 +1,10 @@
+import type { ExecutionEnv } from '../env.js';
+import type { FourTool, ToolHooks } from '../types.js';
+export interface ShellToolOptions {
+    name?: string;
+    allowBackground?: boolean;
+    maxOutputBytes?: number;
+    hooks?: ToolHooks;
+}
+export declare function signalExitCode(exitCode: number | null, signal: string | null): number;
+export declare function createShellTool(env: ExecutionEnv, options?: ShellToolOptions): FourTool;