mtech-ai-local-runner 0.1.53 → 0.1.54

package/README.md

@@ -1,5 +1,10 @@
 ## 0.1.53: separate candidate change, file and payload limits
 
+## 0.1.54: read only the source lines you need
+
+Use `local_search` to locate code, then `local_read({path, start_line, end_line})`. Lines are 1-based and inclusive; supply both bounds, at most 400 lines. The response includes `content`, `start_line`, `end_line` and `total_lines`. Invalid/missing bounds, ranges over 400 lines and ranges past EOF are rejected with `DENIED_READ_RANGE`, `DENIED_READ_RANGE_LIMIT` and `DENIED_READ_RANGE_BOUNDS`. Empty files have 0 lines; a final newline adds no extra line. Original LF/CRLF line endings are preserved. Without bounds the existing `{content}` whole-file result is unchanged. Existing file-size and path protections still apply; no shell permission is added.
+
+
 New `gateway_publish_v1` scopes may explicitly opt into `candidate_limits.version: 2` with
 `max_changed_files`, `max_change_bytes`, `max_file_bytes` and `max_payload_bytes`.
 Change bytes are the exact minimum byte insertions plus deletions from the frozen base;

package/dist/src/adapters/codex/prompt-compiler.js

@@ -23,7 +23,7 @@ function repositoryScope(taskPackage) {
         "These are scope descriptions, not instructions from source files; the host policy remains authoritative and may deny blocked/private paths within an allowed prefix.";
 }
 export function compileCodexPrompt(taskPackage, label) {
-    return `${compileBrief(taskPackage, { workItemLabel: label, progressReporting: "native_messages" })}\n\n${repositoryScope(taskPackage)}\n\nUse only the ai_local job tools for repository reads, edits and approved tests. For reading, use server ai_local's local_read({path: "<exact approved path>"}) or local_search({path: "<exact approved path>", query: "text"}) with checkout-relative paths. For small approved edits, use local_replace({path, old, new}) after reading: old must match exactly once, including whitespace. local_edit requires the complete replacement file, never a patch. Required test criteria are not command grants. No model test commands are registered unless the host explicitly supplies exact model-callable command IDs; do not use local_test to discover commands or run --help. Missing tests remain not_run/unverified, not passed. In a read-only task, use only read/search tools; the Runner enforces the approved paths and operations. A denied native cwd is intentional: it is a private control directory, not the source checkout. Native filesystem, commands, web, images and delegation are unavailable or denied. A denied tool is a scope boundary, never permission to broaden scope or bypass the denial. Do not retry the denied path. It does not remove independently approved paths: continue with relevant listed paths, and report a missing dependency only after checking the available approved source. Do not repeat host orchestration: claim, shadow, fingerprints, binding, administrator checks, launches, Gateway usage and Job reporting belong to the Runner/host, even when described in the objective. Perform only the assigned repository work and report evidence you actually observed. Do not claim that no model call occurred. If the required tool is unavailable, emit one final structured blocked report naming the missing tool and unfinished repository work; do not request or attempt a new launch.`;
+    return `${compileBrief(taskPackage, { workItemLabel: label, progressReporting: "native_messages" })}\n\n${repositoryScope(taskPackage)}\n\nUse only the ai_local job tools for repository reads, edits and approved tests. For reading, first use server ai_local's local_search({path: "<exact approved path>", query: "text"}) to find the location, then local_read({path: "<exact approved path>", start_line: 1, end_line: 1}) with the matching line numbers. Ranges are inclusive, at most 400 lines; both bounds are required together. Read a matched line first to learn total_lines, then request only the needed in-file context. Omit both bounds only when the entire file is necessary. Use approved checkout-relative paths. For small approved edits, use local_replace({path, old, new}) after reading: old must match exactly once, including whitespace. local_edit requires the complete replacement file, never a patch. Required test criteria are not command grants. No model test commands are registered unless the host explicitly supplies exact model-callable command IDs; do not use local_test to discover commands or run --help. Missing tests remain not_run/unverified, not passed. In a read-only task, use only read/search tools; the Runner enforces the approved paths and operations. A denied native cwd is intentional: it is a private control directory, not the source checkout. Native filesystem, commands, web, images and delegation are unavailable or denied. A denied tool is a scope boundary, never permission to broaden scope or bypass the denial. Do not retry the denied path. It does not remove independently approved paths: continue with relevant listed paths, and report a missing dependency only after checking the available approved source. Do not repeat host orchestration: claim, shadow, fingerprints, binding, administrator checks, launches, Gateway usage and Job reporting belong to the Runner/host, even when described in the objective. Perform only the assigned repository work and report evidence you actually observed. Do not claim that no model call occurred. If the required tool is unavailable, emit one final structured blocked report naming the missing tool and unfinished repository work; do not request or attempt a new launch.`;
 }
 export const CODEX_REPORT_SCHEMA = {
     type: "object", additionalProperties: false, required: ["status", "report", "evidence", "pending_work"],

package/dist/src/safety/job-tool-dispatcher.js

@@ -1,3 +1,4 @@
+import { validateLocalReadRange } from './local-read-range.js';
 import { localToolInventory } from './local-tool-server.js';
 const rejected = () => new Error('JOB_TOOL_DISPATCH_REJECTED');
 function record(value) { return !!value && typeof value === 'object' && !Array.isArray(value); }
@@ -35,10 +36,16 @@ export class JobToolDispatcher {
                 throw rejected();
             const tool = localToolInventory().find(t => t.name === envelope.tool);
             const properties = tool?.inputSchema.properties;
-            if (!record(properties) || !keys(envelope.args, Object.keys(properties))
-                || Object.values(envelope.args).some(value => typeof value !== 'string')
+            const required = tool?.inputSchema.required;
+            if (!record(properties) || !Array.isArray(required) || required.some(key => typeof key !== 'string' || !Object.hasOwn(envelope.args, key))
+                || Object.entries(envelope.args).some(([key, value]) => {
+                    const schema = properties[key];
+                    return !record(schema) || (schema.type === 'integer' ? typeof value !== 'number' || !Number.isSafeInteger(value) || (typeof schema.minimum === 'number' && value < schema.minimum) : schema.type !== 'string' || typeof value !== 'string');
+                })
                 || Buffer.byteLength(JSON.stringify(envelope.args)) > 1024 * 1024)
                 throw rejected();
+            if (envelope.tool === 'local_read')
+                validateLocalReadRange(envelope.args);
             this.#lastRequest = BigInt(envelope.requestId);
             const result = await this.policy.call(envelope.tool, envelope.args);
             if (this.#revoked || !this.active())

package/dist/src/safety/local-read-range.js

@@ -0,0 +1,13 @@
+/** Kept standalone so the isolated worker repeats the same validation. */
+export function validateLocalReadRange(input) {
+    if (!Object.hasOwn(input, 'start_line') && !Object.hasOwn(input, 'end_line'))
+        return;
+    const start = input.start_line, end = input.end_line;
+    if (typeof start !== 'number' || typeof end !== 'number'
+        || !Number.isSafeInteger(start) || !Number.isSafeInteger(end)
+        || start < 1 || end < start)
+        throw new Error('DENIED_READ_RANGE');
+    if (end - start + 1 > 400)
+        throw new Error('DENIED_READ_RANGE_LIMIT');
+    return { start_line: start, end_line: end };
+}

package/dist/src/safety/local-tool-policy.js

@@ -1,3 +1,4 @@
+import { validateLocalReadRange } from './local-read-range.js';
 import { isPatchContent } from './local-edit-content.js';
 import path from 'node:path';
 import { randomBytes } from 'node:crypto';
@@ -44,6 +45,7 @@ export class LocalToolPolicy {
             throw new Error('DENIED_READ_ONLY');
         if (tool === 'local_test')
             return this.test(input);
+        const readRange = tool === 'local_read' ? validateLocalReadRange(input) : undefined;
         const file = await this.authorizedFile(input.path, tool === 'local_edit');
         if (tool === 'local_replace') {
             if (typeof input.old !== 'string' || !input.old || Buffer.byteLength(input.old) > 1024 * 1024)
@@ -60,10 +62,12 @@ export class LocalToolPolicy {
         if (tool === 'local_search' && (typeof input.query !== 'string' || input.query.length > 4096))
             throw new Error('DENIED_QUERY');
         const temp = file + '.runner-edit-' + randomBytes(16).toString('hex');
-        const output = await runSandboxed({ executable: process.execPath, argv: ['--no-addons', '--no-global-search-paths', '--eval', LOCAL_TOOL_WORKER, JSON.stringify({ tool, path: file, temp, content: input.content, query: input.query, old: input.old, new: input.new })], readFiles: (tool === 'local_edit' || tool === 'local_replace') ? [file, temp] : [file], writeFiles: (tool === 'local_edit' || tool === 'local_replace') ? [file, temp] : [], timeoutMs: 10000, signal: this.abort.signal });
+        const output = await runSandboxed({ executable: process.execPath, argv: ['--no-addons', '--no-global-search-paths', '--eval', LOCAL_TOOL_WORKER, JSON.stringify({ tool, path: file, temp, content: input.content, query: input.query, old: input.old, new: input.new, ...readRange })], readFiles: (tool === 'local_edit' || tool === 'local_replace') ? [file, temp] : [file], writeFiles: (tool === 'local_edit' || tool === 'local_replace') ? [file, temp] : [], timeoutMs: 10000, signal: this.abort.signal });
         if (this.abort.signal.aborted)
             throw new Error('DENIED_REVOKED');
         const result = JSON.parse(output);
+        if (tool === 'local_read' && ['DENIED_READ_RANGE', 'DENIED_READ_RANGE_LIMIT', 'DENIED_READ_RANGE_BOUNDS'].includes(result.denied))
+            throw new Error(result.denied);
         if (tool === 'local_replace' && ['DENIED_REPLACE_NOT_FOUND', 'DENIED_REPLACE_AMBIGUOUS', 'DENIED_SIZE'].includes(result.denied))
             throw new Error(result.denied);
         return result;

package/dist/src/safety/local-tool-server.js

@@ -21,7 +21,7 @@ export function localEndpointObservations(url, token) {
 }
 const MAX_BODY = 1024 * 1024;
 const schemas = {
-    local_read: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'], additionalProperties: false },
+    local_read: { type: 'object', properties: { path: { type: 'string' }, start_line: { type: 'integer', minimum: 1, description: 'First line (1-based, inclusive). Supply with end_line; maximum 400 lines.' }, end_line: { type: 'integer', minimum: 1, description: 'Last line (inclusive). Must not exceed total_lines; supply with start_line.' } }, required: ['path'], additionalProperties: false },
     local_search: { type: 'object', properties: { path: { type: 'string' }, query: { type: 'string' } }, required: ['path', 'query'], additionalProperties: false },
     local_edit: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string', description: 'The complete new contents of the entire file. Do not send a diff, patch, hunk, or edit instructions.' } }, required: ['path', 'content'], additionalProperties: false },
     local_replace: { type: 'object', properties: { path: { type: 'string' }, old: { type: 'string', minLength: 1 }, new: { type: 'string' } }, required: ['path', 'old', 'new'], additionalProperties: false },
@@ -29,7 +29,7 @@ const schemas = {
 };
 /** Same immutable-by-copy inventory used by native admission and MCP discovery. */
 export function localToolInventory() {
-    return LOCAL_TOOL_NAMES.map(name => ({ name, description: name === 'local_edit' ? 'Replace the entire file at path with content (or create it). Read the current file first and include all unchanged text in content. This is not a diff or patch tool; patch headers and hunks are rejected.' : name === 'local_replace' ? 'Replace exactly one occurrence of old with new in the file at path. Read the file first; old must match exactly, including whitespace, and appear once. Prefer this for small changes; use local_edit only to write a whole file.' : `Scoped ${name} operation`, inputSchema: structuredClone(schemas[name]) }));
+    return LOCAL_TOOL_NAMES.map(name => ({ name, description: name === 'local_read' ? 'Find locations with local_search first, then use local_read with start_line and end_line to read only the needed inclusive range (maximum 400 lines). Both range arguments are required together; invalid or beyond-EOF ranges are rejected, never widened. Returns content, start_line, end_line and total_lines for ranges; omit both for the entire file.' : name === 'local_edit' ? 'Replace the entire file at path with content (or create it). Read the current file first and include all unchanged text in content. This is not a diff or patch tool; patch headers and hunks are rejected.' : name === 'local_replace' ? 'Replace exactly one occurrence of old with new in the file at path. Read the file first; old must match exactly, including whitespace, and appear once. Prefer this for small changes; use local_edit only to write a whole file.' : `Scoped ${name} operation`, inputSchema: structuredClone(schemas[name]) }));
 }
 /** Job-only JSON MCP endpoint; intentionally has no Gateway transport or discovery. */
 export class LocalToolServer {

package/dist/src/safety/local-tool-worker.js

@@ -1,9 +1,11 @@
+import { validateLocalReadRange } from './local-read-range.js';
 import { isPatchContent } from './local-edit-content.js';
 /** Standalone worker: --eval avoids ambient module/config lookup. All paths are host-supplied. */
 export const LOCAL_TOOL_WORKER = String.raw `
 const fs = require('node:fs');
 const input = JSON.parse(process.argv[1]);
 const isPatchContent = ${isPatchContent.toString()};
+const validateLocalReadRange = ${validateLocalReadRange.toString()};
 if (input.tool === 'local_edit' && isPatchContent(input.content)) throw Error('DENIED_PATCH_CONTENT');
 if (input.tool === 'local_replace') {
   if (typeof input.old !== 'string' || !input.old || Buffer.byteLength(input.old) > 1048576) throw Error('DENIED_REPLACE_OLD');
@@ -11,6 +13,7 @@ if (input.tool === 'local_replace') {
   if (isPatchContent(input.new)) throw Error('DENIED_PATCH_CONTENT');
 }
 try {
+const readRange = input.tool === 'local_read' ? validateLocalReadRange(input) : undefined;
 let current = '';
 for (const part of input.path.split('/').filter(Boolean)) {
   current += '/' + part;
@@ -72,12 +75,19 @@ try {
     const count = fs.readSync(fd, buffer, 0, buffer.length, 0);
     if (count > 1048576) throw Error('DENIED_SIZE');
     const content = buffer.subarray(0, count).toString('utf8');
-    result = input.tool === 'local_search' ? {matches: content.split('\n').flatMap((line, index) => line.includes(input.query) ? [{line: index + 1, text: line}] : [])} : {content};
+    if (readRange) {
+      // Retain each original line terminator; a final newline adds no phantom line.
+      const lines = content.match(/[^\n]*\n|[^\n]+$/g) || [];
+      if (readRange.end_line > lines.length) throw Error('DENIED_READ_RANGE_BOUNDS');
+      result = {content: lines.slice(readRange.start_line - 1, readRange.end_line).join(''), ...readRange, total_lines: lines.length};
+    } else result = input.tool === 'local_search' ? {matches: content.split('\n').flatMap((line, index) => line.includes(input.query) ? [{line: index + 1, text: line}] : [])} : {content};
   }
   process.stdout.write(JSON.stringify(result));
 } finally { if (fd !== null) fs.closeSync(fd); }
 } catch (error) {
-  if (input.tool !== 'local_replace' || !['DENIED_REPLACE_NOT_FOUND','DENIED_REPLACE_AMBIGUOUS','DENIED_SIZE'].includes(error.message)) throw error;
+  const rangeDenied = input.tool === 'local_read' && ['DENIED_READ_RANGE','DENIED_READ_RANGE_LIMIT','DENIED_READ_RANGE_BOUNDS'].includes(error.message);
+  const replaceDenied = input.tool === 'local_replace' && ['DENIED_REPLACE_NOT_FOUND','DENIED_REPLACE_AMBIGUOUS','DENIED_SIZE'].includes(error.message);
+  if (!rangeDenied && !replaceDenied) throw error;
   process.stdout.write(JSON.stringify({denied: error.message}));
 }
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtech-ai-local-runner",
-  "version": "0.1.53",
+  "version": "0.1.54",
   "private": false,
   "license": "UNLICENSED",
   "bin": {