mtech-ai-local-runner 0.1.48 → 0.1.50

package/dist/src/gateway-client.js

@@ -12,6 +12,51 @@ export class GatewayToolError extends Error {
         this.code = code;
     }
 }
+const PUSH_CHANNEL = /^private-ai-gateway\.[a-z0-9_-]{1,32}\.runner\.[a-z0-9:_-]{1,128}$/;
+const PUSH_APP_KEY = /^[A-Za-z0-9_-]{1,128}$/;
+const CHANNEL_AUTH = /^[^:\s]{1,128}:[a-f0-9]{64}$/;
+/*
+ * A sync result without the ask keys ends every stored delivery (the e1c08b33 kill switch), so a result that is not
+ * clearly a sync answer is refused instead of being read as "asks off": the transport retries it with backoff.
+ */
+export function parseRunnerSync(result, runnerId) {
+    const body = result && typeof result === "object" && !Array.isArray(result) ? result : undefined;
+    const malformed = (key) => body !== undefined && body[key] !== undefined && !Array.isArray(body[key]);
+    if (body === undefined || !Array.isArray(body.opens) || malformed("ask_deliveries") || malformed("closed_delivery_ids")) {
+        throw new GatewayToolError("Gateway returned an invalid runner sync result", "local_agent_runner_sync", "GATEWAY_INVALID_TOOL_RESULT");
+    }
+    return {
+        opens: body.opens,
+        ...(Array.isArray(body.ask_deliveries) ? { askDeliveries: body.ask_deliveries } : {}),
+        ...(Array.isArray(body.closed_delivery_ids) ? { closedDeliveryIds: body.closed_delivery_ids } : {}),
+        jobAvailable: body.job_available === true,
+        push: parsePush(body.push, runnerId),
+        syncSeconds: clampSeconds(body.sync_seconds, 15, 120, 30),
+        fallbackSyncSeconds: clampSeconds(body.fallback_sync_seconds, 5, 30, 8),
+    };
+}
+function clampSeconds(value, min, max, fallback) {
+    return typeof value === "number" && Number.isInteger(value) ? Math.min(max, Math.max(min, value)) : fallback;
+}
+function parsePush(value, runnerId) {
+    if (!value || typeof value !== "object")
+        return null;
+    const { url, app_key: appKey, channel, event } = value;
+    if (typeof url !== "string" || typeof appKey !== "string" || typeof channel !== "string" || event !== "runner.sync")
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "wss:" || !PUSH_APP_KEY.test(appKey) || !PUSH_CHANNEL.test(channel))
+        return null;
+    if (!channel.endsWith(`.runner.${runnerId.toLowerCase()}`))
+        return null;
+    return { url, appKey, channel, event };
+}
 function nested(value, path) {
     return path.split(".").reduce((current, key) => {
         if (!current || typeof current !== "object")
@@ -479,6 +524,27 @@ export class McpGatewayClient {
             ...(input.failureCode ? { failure_code: input.failureCode } : {}),
         }, signal);
     }
+    /** acknowledgedClosureIds: closures handled since the last sync; the Gateway lists each again until acknowledged. */
+    async syncRunner(input, signal) {
+        const acknowledged = (input.acknowledgedClosureIds ?? []).slice(0, 50);
+        const result = await this.callTool("local_agent_runner_sync", {
+            runner_id: this.runnerId,
+            adapter_versions: input.adapterVersions,
+            reason: input.reason,
+            ...(acknowledged.length > 0 ? { acknowledged_closure_ids: acknowledged } : {}),
+        }, signal);
+        return parseRunnerSync(result, this.runnerId);
+    }
+    async authorizeRunnerChannel(socketId, signal) {
+        const result = await this.callTool("local_agent_runner_channel_auth", {
+            runner_id: this.runnerId,
+            socket_id: socketId,
+        }, signal);
+        if (typeof result?.channel !== "string" || typeof result.auth !== "string" || !CHANNEL_AUTH.test(result.auth)) {
+            throw new GatewayToolError("Gateway returned an invalid channel authorization", "local_agent_runner_channel_auth", "GATEWAY_INVALID_TOOL_RESULT");
+        }
+        return { channel: result.channel, auth: result.auth };
+    }
     async localRunnerStatus() {
         return this.callTool("local_agent_runner_status", { runner_id: this.runnerId });
     }

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

@@ -6,7 +6,7 @@ import { evaluateCommand } from './command-policy.js';
 import { runSandboxed, runSandboxedMeasured } from './subprocess-sandbox.js';
 import { LOCAL_TOOL_WORKER } from './local-tool-worker.js';
 import { verifyCommandIntegrity } from './registered-command-integrity.js';
-export const LOCAL_TOOL_NAMES = ['local_read', 'local_search', 'local_edit', 'local_test'];
+export const LOCAL_TOOL_NAMES = ['local_read', 'local_search', 'local_edit', 'local_replace', 'local_test'];
 // Private state/control basenames only: Auth.php, auth/ and mcp.ts are ordinary source.
 const sensitive = (segment) => /^(?:\.git|\.mcp(?:\..*)?|\.npmrc|\.netrc|id_rsa|id_ed25519|\.local-runner|\.runner|\.env(?:\..*)?|\.codex|\.claude|\.ssh|\.aws|\.config|auth\.(?:json|toml|ya?ml)(?:\..*)?|credentials(?:\..*)?|AGENTS\.md|CLAUDE\.md|mcp\.(?:json|toml|ya?ml)(?:\..*)?)$/i.test(segment);
 const contains = (root, file) => file === root || file.startsWith(root + path.sep);
@@ -40,11 +40,19 @@ export class LocalToolPolicy {
         if (!args || typeof args !== 'object' || Array.isArray(args))
             throw new Error('DENIED_ARGUMENTS');
         const input = args;
-        if (tool === 'local_edit' && this.options.access !== 'write')
+        if ((tool === 'local_edit' || tool === 'local_replace') && this.options.access !== 'write')
             throw new Error('DENIED_READ_ONLY');
         if (tool === 'local_test')
             return this.test(input);
         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)
+                throw new Error('DENIED_REPLACE_OLD');
+            if (typeof input.new !== 'string' || Buffer.byteLength(input.new) > 1024 * 1024)
+                throw new Error('DENIED_CONTENT');
+            if (isPatchContent(input.new))
+                throw new Error('DENIED_PATCH_CONTENT');
+        }
         if (tool === 'local_edit' && (typeof input.content !== 'string' || Buffer.byteLength(input.content) > 1024 * 1024))
             throw new Error('DENIED_CONTENT');
         if (tool === 'local_edit' && isPatchContent(input.content))
@@ -52,10 +60,13 @@ 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 })], readFiles: tool === 'local_edit' ? [file, temp] : [file], writeFiles: tool === 'local_edit' ? [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 })], 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');
-        return JSON.parse(output);
+        const result = JSON.parse(output);
+        if (tool === 'local_replace' && ['DENIED_REPLACE_NOT_FOUND', 'DENIED_REPLACE_AMBIGUOUS', 'DENIED_SIZE'].includes(result.denied))
+            throw new Error(result.denied);
+        return result;
     }
     async authorizedFile(value, allowMissing = false) {
         if (typeof value !== 'string' || !value || value.includes('\0') || path.isAbsolute(value) || value.split(/[\\/]/).some(p => p === '..' || sensitive(p)))

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

@@ -24,11 +24,12 @@ const schemas = {
     local_read: { type: 'object', properties: { path: { type: 'string' } }, 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 },
     local_test: { type: 'object', properties: { command: { type: 'string' } }, required: ['command'], additionalProperties: false },
 };
 /** 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.' : `Scoped ${name} operation`, inputSchema: structuredClone(schemas[name]) }));
+    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]) }));
 }
 /** Job-only JSON MCP endpoint; intentionally has no Gateway transport or discovery. */
 export class LocalToolServer {

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

@@ -5,6 +5,12 @@ const fs = require('node:fs');
 const input = JSON.parse(process.argv[1]);
 const isPatchContent = ${isPatchContent.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');
+  if (typeof input.new !== 'string' || Buffer.byteLength(input.new) > 1048576) throw Error('DENIED_CONTENT');
+  if (isPatchContent(input.new)) throw Error('DENIED_PATCH_CONTENT');
+}
+try {
 let current = '';
 for (const part of input.path.split('/').filter(Boolean)) {
   current += '/' + part;
@@ -27,8 +33,20 @@ try {
     if (actual.ino !== before.ino || actual.dev !== before.dev || actual.ino !== final.ino || actual.dev !== final.dev || actual.nlink !== 1) throw Error('DENIED_RACE');
   }
   let result;
-  if (input.tool === 'local_edit') {
-    const data = Buffer.from(input.content, 'utf8');
+  if (input.tool === 'local_edit' || input.tool === 'local_replace') {
+    let content = input.content;
+    if (input.tool === 'local_replace') {
+      const buffer = Buffer.alloc(1048577);
+      const count = fs.readSync(fd, buffer, 0, buffer.length, 0);
+      if (count > 1048576) throw Error('DENIED_SIZE');
+      const original = new TextDecoder('utf-8', {fatal: true, ignoreBOM: true}).decode(buffer.subarray(0, count));
+      const first = original.indexOf(input.old);
+      if (first < 0) throw Error('DENIED_REPLACE_NOT_FOUND');
+      if (original.indexOf(input.old, first + 1) >= 0) throw Error('DENIED_REPLACE_AMBIGUOUS');
+      content = original.slice(0, first) + input.new + original.slice(first + input.old.length);
+    }
+    const data = Buffer.from(content, 'utf8');
+    if (data.length > 1048576) throw Error('DENIED_SIZE');
     const temp = fs.openSync(input.temp, fs.constants.O_NOFOLLOW | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, before ? before.mode & 0o777 : 0o600);
     try {
       fs.writeFileSync(temp, data);
@@ -37,6 +55,7 @@ try {
       if (tempStat.nlink !== 1 || tempStat.ino !== tempFinal.ino || tempStat.dev !== tempFinal.dev) throw Error('DENIED_RACE');
       if (actual) {
         const still = fs.lstatSync(input.path);
+        if (input.tool === 'local_replace' && (still.size !== actual.size || still.mtimeMs !== actual.mtimeMs || still.ctimeMs !== actual.ctimeMs)) throw Error('DENIED_RACE');
         if (still.isSymbolicLink() || still.ino !== actual.ino || still.dev !== actual.dev || still.nlink !== 1) throw Error('DENIED_RACE');
         fs.renameSync(input.temp, input.path);
       } else {
@@ -57,4 +76,8 @@ try {
   }
   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;
+  process.stdout.write(JSON.stringify({denied: error.message}));
+}
 `;

package/dist/src/safety/pre-tool-use-hook.js

@@ -1,4 +1,4 @@
-export const CLAUDE_LOCAL_MCP_TOOLS = Object.freeze(["local_read", "local_search", "local_edit", "local_test"].map(name => `mcp__ai_local__${name}`));
+export const CLAUDE_LOCAL_MCP_TOOLS = Object.freeze(["local_read", "local_search", "local_edit", "local_replace", "local_test"].map(name => `mcp__ai_local__${name}`));
 function allow(reasonCode) {
     return {
         hookSpecificOutput: {

package/dist/src/transport/abortable-delay.js

@@ -0,0 +1,12 @@
+/** Resolves after the delay or at once on abort, and never leaves a listener on a long-lived signal. */
+export function abortableDelay(milliseconds, signal) {
+    return new Promise(resolve => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => { clearTimeout(timer); resolve(); };
+        const timer = setTimeout(() => { signal.removeEventListener("abort", onAbort); resolve(); }, milliseconds);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/src/transport/pusher-protocol.js

@@ -0,0 +1,66 @@
+const SOCKET_ID = /^\d{1,20}\.\d{1,20}$/;
+const DEFAULT_ACTIVITY_TIMEOUT_SECONDS = 30;
+export function subscribeFrame(channel, auth) {
+    return JSON.stringify({ event: "pusher:subscribe", data: { channel, auth } });
+}
+export function pingFrame() {
+    return JSON.stringify({ event: "pusher:ping", data: {} });
+}
+export function pongFrame() {
+    return JSON.stringify({ event: "pusher:pong", data: {} });
+}
+export function decodeFrame(raw, expected) {
+    let frame;
+    try {
+        frame = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "ignored" };
+    }
+    if (!frame || typeof frame !== "object" || Array.isArray(frame))
+        return { kind: "ignored" };
+    const { event, channel, data } = frame;
+    if (typeof event !== "string")
+        return { kind: "ignored" };
+    switch (event) {
+        case "pusher:connection_established": {
+            const payload = parseData(data);
+            const socketId = payload?.socket_id;
+            if (typeof socketId !== "string" || !SOCKET_ID.test(socketId))
+                return { kind: "error" };
+            const timeout = payload?.activity_timeout;
+            const activityTimeoutSeconds = typeof timeout === "number" && Number.isInteger(timeout) && timeout >= 5 && timeout <= 600
+                ? timeout : DEFAULT_ACTIVITY_TIMEOUT_SECONDS;
+            return { kind: "connected", socketId, activityTimeoutSeconds };
+        }
+        case "pusher_internal:subscription_succeeded":
+            return channel === expected.channel ? { kind: "subscribed" } : { kind: "ignored" };
+        case "pusher:ping":
+            return { kind: "ping" };
+        case "pusher:pong":
+            return { kind: "pong" };
+        case "pusher:error": {
+            const code = parseData(data)?.code;
+            return typeof code === "number" ? { kind: "error", code } : { kind: "error" };
+        }
+        case "pusher:subscription_error":
+            return { kind: "error" };
+        default:
+            break;
+    }
+    if (event.startsWith("client-") || event.startsWith("pusher"))
+        return { kind: "ignored" };
+    return channel === expected.channel && event === expected.event ? { kind: "signal" } : { kind: "ignored" };
+}
+function parseData(data) {
+    if (typeof data === "string") {
+        try {
+            const parsed = JSON.parse(data);
+            return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return data && typeof data === "object" && !Array.isArray(data) ? data : undefined;
+}

package/dist/src/transport/reverb-socket.js

@@ -0,0 +1,144 @@
+import WebSocket from "ws";
+import { decodeFrame, pingFrame, pongFrame, subscribeFrame } from "./pusher-protocol.js";
+const CONNECT_TIMEOUT_MS = 10_000;
+const SUBSCRIBE_TIMEOUT_MS = 10_000;
+/** How long close() waits for the server's close frame before dropping the connection. */
+const CLOSE_GRACE_MS = 1_000;
+const PONG_TIMEOUT_MS = 10_000;
+const MAX_PING_INTERVAL_MS = 30_000;
+/*
+ * ws sends no User-Agent of its own, and the ELSA load balancer's WAF (AWS managed common rules) answers a request
+ * without one with 403 before Reverb sees it. Measured against the development Reverb on 2026-10-24.
+ */
+export function pushSocketOptions(packageVersion, connectTimeoutMs) {
+    return { handshakeTimeout: connectTimeoutMs, headers: { "User-Agent": `mtec-ai-local-runner/${packageVersion}` } };
+}
+export function pushSocketUrl(target, packageVersion) {
+    const url = new URL(target.url);
+    if (url.protocol !== "wss:")
+        throw new Error("PUSH_URL_NOT_WSS");
+    url.pathname = `/app/${encodeURIComponent(target.appKey)}`;
+    url.search = new URLSearchParams({ protocol: "7", client: "mtec-ai-local-runner", version: packageVersion, flash: "false" }).toString();
+    return url.toString();
+}
+export class ReverbSocket {
+    target;
+    events;
+    options;
+    socket;
+    ended = false;
+    ownerClosed = false;
+    pingIntervalMs;
+    connectTimer;
+    subscribeTimer;
+    pingTimer;
+    pongTimer;
+    constructor(target, events, options) {
+        this.target = target;
+        this.events = events;
+        this.options = options;
+        this.pingIntervalMs = options.maxPingIntervalMs ?? MAX_PING_INTERVAL_MS;
+        const connectTimeoutMs = options.connectTimeoutMs ?? CONNECT_TIMEOUT_MS;
+        const url = pushSocketUrl(target, options.packageVersion);
+        const create = options.createSocket ?? ((value) => new WebSocket(value, pushSocketOptions(options.packageVersion, connectTimeoutMs)));
+        this.socket = create(url);
+        this.connectTimer = setTimeout(() => this.fail("connect_timeout"), connectTimeoutMs);
+        this.socket.on("message", data => this.onMessage(String(data)));
+        this.socket.on("close", () => this.fail("closed"));
+        this.socket.on("error", () => this.fail("error"));
+    }
+    subscribe(auth) {
+        if (this.ended)
+            return;
+        clearTimeout(this.subscribeTimer);
+        this.subscribeTimer = setTimeout(() => this.fail("subscribe_timeout"), this.options.subscribeTimeoutMs ?? SUBSCRIBE_TIMEOUT_MS);
+        this.send(subscribeFrame(this.target.channel, auth));
+    }
+    close() {
+        if (this.ended)
+            return;
+        this.ownerClosed = true;
+        this.end();
+        try {
+            this.socket.close();
+        }
+        catch { /* Closing a socket that is already gone is fine. */ }
+        // ws waits up to 30 s for the server's close frame, which would hold a stopping daemon open.
+        const drop = setTimeout(() => { try {
+            this.socket.terminate();
+        }
+        catch { /* Already gone. */ } }, CLOSE_GRACE_MS);
+        drop.unref?.();
+    }
+    onMessage(raw) {
+        if (this.ended)
+            return;
+        this.armPing();
+        const frame = decodeFrame(raw, { channel: this.target.channel, event: this.target.event });
+        switch (frame.kind) {
+            case "connected":
+                clearTimeout(this.connectTimer);
+                this.pingIntervalMs = Math.min(frame.activityTimeoutSeconds * 1000, this.options.maxPingIntervalMs ?? MAX_PING_INTERVAL_MS);
+                this.armPing();
+                this.events.onConnected(frame.socketId);
+                break;
+            case "subscribed":
+                clearTimeout(this.subscribeTimer);
+                this.events.onSubscribed();
+                break;
+            case "signal":
+                this.events.onSignal();
+                break;
+            case "ping":
+                this.send(pongFrame());
+                break;
+            case "error":
+                // The Pusher close code decides how soon the transport reconnects (4000-4099: not unchanged).
+                this.fail(frame.code !== undefined && Number.isInteger(frame.code) && frame.code >= 4000 && frame.code <= 4299 ? `protocol_error_${frame.code}` : "protocol_error");
+                break;
+            default:
+                break;
+        }
+    }
+    armPing() {
+        clearTimeout(this.pongTimer);
+        this.pongTimer = undefined;
+        clearTimeout(this.pingTimer);
+        if (this.ended)
+            return;
+        this.pingTimer = setTimeout(() => {
+            this.send(pingFrame());
+            if (this.ended)
+                return;
+            this.pongTimer = setTimeout(() => this.fail("pong_timeout"), this.options.pongTimeoutMs ?? PONG_TIMEOUT_MS);
+        }, this.pingIntervalMs);
+    }
+    send(frame) {
+        if (this.ended)
+            return;
+        try {
+            this.socket.send(frame);
+        }
+        catch {
+            this.fail("send_failed");
+        }
+    }
+    fail(reason) {
+        if (this.ended)
+            return;
+        this.end();
+        try {
+            this.socket.terminate();
+        }
+        catch { /* The socket may already be gone. */ }
+        if (!this.ownerClosed)
+            this.events.onClosed(reason);
+    }
+    end() {
+        this.ended = true;
+        clearTimeout(this.connectTimer);
+        clearTimeout(this.subscribeTimer);
+        clearTimeout(this.pingTimer);
+        clearTimeout(this.pongTimer);
+    }
+}