@abot-ai/runtime 1.7.0 → 1.8.0

package/dist/src/model-gateway/providers/openai/structured-message-output.js

@@ -0,0 +1,175 @@
+const IGNORED_OUTPUT_DIAGNOSTIC_LIMIT = 8;
+function readRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function readMessagePhase(value) {
+    if (value === "commentary" || value === "final_answer")
+        return value;
+    return undefined;
+}
+function readOutputIndex(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        return null;
+    }
+    return value;
+}
+function takePendingText(output) {
+    const pending = output.pending;
+    output.pending = [];
+    return pending.map((chunk) => chunk.text);
+}
+function describeOutput(output) {
+    return {
+        itemId: output.itemId?.slice(0, 160) ?? null,
+        outputIndex: output.outputIndex,
+        arrivalOrder: output.arrivalOrder,
+        textByteCount: output.textByteCount,
+        ...(output.phase ? { phase: output.phase } : {}),
+    };
+}
+/** One invocation's structured result; never infer its phase from generated text. */
+export class OpenAIStructuredMessageOutput {
+    outputs = [];
+    byItemId = new Map();
+    byOutputIndex = new Map();
+    unidentifiedOutput;
+    firstTextOutput;
+    selectedOutput;
+    hasExplicitPhase = false;
+    nextOutputOrder = 0;
+    nextChunkSequence = 0;
+    observeItem(event) {
+        const item = readRecord(event.item);
+        if (item.type !== "message")
+            return [];
+        const output = this.resolveOutput(item.id, event.output_index);
+        const phase = readMessagePhase(item.phase);
+        if (!phase)
+            return this.takeSelectedText(output);
+        this.hasExplicitPhase = true;
+        output.phase = phase;
+        if (phase === "commentary") {
+            output.pending = [];
+            return [];
+        }
+        this.selectFinalOutput(output);
+        return this.takeSelectedText(output);
+    }
+    observeResponse(value) {
+        const response = readRecord(value);
+        if (!Array.isArray(response.output))
+            return [];
+        return response.output.flatMap((item, outputIndex) => this.observeItem({ item, output_index: outputIndex }));
+    }
+    consumeDelta(event, text) {
+        const output = this.resolveOutput(event.item_id, event.output_index);
+        this.firstTextOutput ??= output;
+        output.textByteCount += Buffer.byteLength(text, "utf8");
+        if (output.phase === "commentary")
+            return [];
+        output.pending.push({ sequence: this.nextChunkSequence++, text });
+        return this.takeSelectedText(output);
+    }
+    finish() {
+        if (this.selectedOutput) {
+            return { text: takePendingText(this.selectedOutput) };
+        }
+        if (this.hasExplicitPhase) {
+            return { text: [], error: "openai structured response missing final_answer" };
+        }
+        // Older responses have no phase: retain the first text message, never join them.
+        this.selectedOutput = this.firstTextOutput;
+        return {
+            text: this.selectedOutput ? takePendingText(this.selectedOutput) : [],
+        };
+    }
+    diagnostic() {
+        if (!this.selectedOutput || this.outputs.length < 2)
+            return undefined;
+        const ignored = this.outputs.filter((output) => output !== this.selectedOutput);
+        return {
+            outcome: "additional_message_outputs_ignored",
+            outputCount: this.outputs.length,
+            selectedOutput: describeOutput(this.selectedOutput),
+            ignoredOutputCount: ignored.length,
+            sampledIgnoredOutputs: ignored.slice(0, IGNORED_OUTPUT_DIAGNOSTIC_LIMIT).map(describeOutput),
+            omittedIgnoredOutputCount: Math.max(0, ignored.length - IGNORED_OUTPUT_DIAGNOSTIC_LIMIT),
+        };
+    }
+    selectFinalOutput(output) {
+        if (this.selectedOutput)
+            return;
+        this.selectedOutput = output;
+    }
+    takeSelectedText(output) {
+        if (output !== this.selectedOutput)
+            return [];
+        // Keep partial identities buffered until both identifiers can join their chunks.
+        if (output.itemId === null)
+            return [];
+        if (output.outputIndex === null)
+            return [];
+        return takePendingText(output);
+    }
+    mergeOutputs(first, second) {
+        const [output, absorbed] = [first, second].sort((a, b) => a.arrivalOrder - b.arrivalOrder);
+        output.itemId ??= absorbed.itemId;
+        output.outputIndex ??= absorbed.outputIndex;
+        output.phase ??= absorbed.phase;
+        output.textByteCount += absorbed.textByteCount;
+        output.pending = [...output.pending, ...absorbed.pending]
+            .sort((a, b) => a.sequence - b.sequence);
+        this.outputs.splice(this.outputs.indexOf(absorbed), 1);
+        for (const [key, value] of this.byItemId) {
+            if (value === absorbed)
+                this.byItemId.set(key, output);
+        }
+        for (const [key, value] of this.byOutputIndex) {
+            if (value === absorbed)
+                this.byOutputIndex.set(key, output);
+        }
+        if (this.firstTextOutput === absorbed)
+            this.firstTextOutput = output;
+        if (this.selectedOutput === absorbed)
+            this.selectedOutput = output;
+        return output;
+    }
+    reconcileOutputs(itemOutput, indexedOutput) {
+        if (!itemOutput)
+            return indexedOutput;
+        if (!indexedOutput)
+            return itemOutput;
+        if (itemOutput === indexedOutput)
+            return itemOutput;
+        return this.mergeOutputs(itemOutput, indexedOutput);
+    }
+    resolveOutput(itemIdValue, outputIndexValue) {
+        const itemId = typeof itemIdValue === "string" && itemIdValue.length > 0
+            ? itemIdValue : null;
+        const outputIndex = readOutputIndex(outputIndexValue);
+        const itemOutput = itemId === null ? undefined : this.byItemId.get(itemId);
+        const indexedOutput = outputIndex === null ? undefined : this.byOutputIndex.get(outputIndex);
+        let output = this.reconcileOutputs(itemOutput, indexedOutput);
+        if (itemId === null && outputIndex === null)
+            output = this.unidentifiedOutput;
+        if (!output) {
+            output = { itemId, outputIndex, arrivalOrder: ++this.nextOutputOrder,
+                textByteCount: 0, pending: [] };
+            this.outputs.push(output);
+        }
+        if (itemId !== null) {
+            output.itemId = itemId;
+            this.byItemId.set(itemId, output);
+        }
+        if (outputIndex !== null) {
+            output.outputIndex = outputIndex;
+            this.byOutputIndex.set(outputIndex, output);
+        }
+        if (itemId === null && outputIndex === null)
+            this.unidentifiedOutput = output;
+        return output;
+    }
+}

package/dist/src/model-gateway/server.js

@@ -1,7 +1,11 @@
+import { pathToFileURL } from "node:url";
+import { recoverRuntimeSetupEdit } from "../web-ui/local-runtime/runtime-setup-edit-recovery.js";
 import { createModelGatewayServer, resolveModelGatewayPort, } from "./server/index.js";
 export * from "./server/index.js";
 export { buildOllamaPayload, buildOllamaRawPayload, resolveFormat, } from "./providers/ollama.js";
-if (import.meta.url === `file://${process.argv[1]}`) {
+const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (import.meta.url === invokedPath) {
+    await recoverRuntimeSetupEdit(process.cwd());
     const port = resolveModelGatewayPort();
     createModelGatewayServer().listen(port, () => {
         console.log(`MODEL GATEWAY RUNNING ${port}`);

package/dist/src/plugin-contract/index.d.ts

@@ -1,2 +1,3 @@
 export type * from "./entrypoint.js";
 export * from "./manifest.js";
+export * from "./platform-compatibility.js";

package/dist/src/plugin-contract/index.js

@@ -1 +1,2 @@
 export * from "./manifest.js";
+export * from "./platform-compatibility.js";

package/dist/src/plugin-contract/manifest.d.ts

@@ -1,4 +1,5 @@
 import type { ToolCatalogGroup, ToolDevelopmentRole, ToolEventPresentation, ToolNormalInvocationApproval, ToolNormalInvocationAttachmentInput, ToolNormalInvocationEffect, ToolNormalInvocationFixedValue, ToolNormalInvocationInput, ToolNormalInvocationPayload, ToolNormalInvocationOutputChannels, ToolPayloadChannelSpec, ToolRoutingCapability, ToolRuntimePathBinding } from "../capabilities/tool-types.js";
+import { ABOT_PLUGIN_COMPATIBILITY_EXTENSION, type PluginPlatformDeclaration } from "./platform-compatibility.js";
 export declare const AGENT_PLUGIN_MANIFEST_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
 export declare const ABOT_RUNTIME_EXTENSION = "ai.abot.runtime";
 export declare const ABOT_RUNTIME_EXTENSION_VERSION: 1;
@@ -48,6 +49,7 @@ export type AgentPluginManifest = Readonly<{
     description?: string;
     extensions: Readonly<{
         [ABOT_RUNTIME_EXTENSION]: AbotRuntimePluginExtension;
+        [ABOT_PLUGIN_COMPATIBILITY_EXTENSION]?: PluginPlatformDeclaration;
         [namespace: string]: unknown;
     }>;
 }>;

package/dist/src/plugin-contract/manifest.js

@@ -1,3 +1,4 @@
+import { ABOT_PLUGIN_COMPATIBILITY_EXTENSION, } from "./platform-compatibility.js";
 export const AGENT_PLUGIN_MANIFEST_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
 export const ABOT_RUNTIME_EXTENSION = "ai.abot.runtime";
 export const ABOT_RUNTIME_EXTENSION_VERSION = 1;

package/dist/src/plugin-contract/platform-compatibility.d.ts

@@ -0,0 +1,16 @@
+export declare const ABOT_PLUGIN_COMPATIBILITY_EXTENSION = "ai.abot.compatibility";
+export declare const ABOT_PLUGIN_COMPATIBILITY_VERSION: 1;
+export declare const PLUGIN_RUNTIME_PLATFORMS: readonly ["linux", "darwin", "win32"];
+export type PluginRuntimePlatform = (typeof PLUGIN_RUNTIME_PLATFORMS)[number];
+/** The OS running Runtime, independent of a connected computer's OS. */
+export type PluginPlatformDeclaration = Readonly<{
+    version: typeof ABOT_PLUGIN_COMPATIBILITY_VERSION;
+    runtimePlatforms: readonly PluginRuntimePlatform[];
+}>;
+export type PluginPlatformCompatibility = Readonly<{
+    supported: boolean;
+    status: "declared" | "legacy" | "unsupported" | "undeclared";
+    runtimePlatform: NodeJS.Platform;
+    runtimePlatforms?: readonly PluginRuntimePlatform[];
+    reason?: string;
+}>;

package/dist/src/plugin-contract/platform-compatibility.js

@@ -0,0 +1,3 @@
+export const ABOT_PLUGIN_COMPATIBILITY_EXTENSION = "ai.abot.compatibility";
+export const ABOT_PLUGIN_COMPATIBILITY_VERSION = 1;
+export const PLUGIN_RUNTIME_PLATFORMS = ["linux", "darwin", "win32"];

package/dist/src/plugin-sdk/computer-access.d.ts

@@ -1,4 +1,5 @@
 /** Shared computer access. Import this subpath only when your plugin uses the host. */
+export { HOST_SECRET_PROTECTION_CAPABILITY } from "../computer-access/companion/secret-protection-protocol.js";
 export { executeHostOperation, readHostStatus, } from "../computer-access/companion/broker-client.js";
 export { HOST_OPERATIONS, type HostIdentity, type HostOperation, type HostStatus, isHostIdentifier, isHostIdentity, isHostOperation, } from "../computer-access/companion/protocol.js";
 export { computerFields, computerInputError, computerRecord, computerText, readNativeComputerAction, readPhysicalRectangle, } from "../computer-access/computer/action-input.js";
@@ -19,3 +20,6 @@ export type { SystemProcessResult } from "../computer-access/contracts.js";
 export { createSystemOutputCapture, type SystemOutputReceipt } from "../computer-access/command-output-capture.js";
 export { DEFAULT_SYSTEM_OUTPUT_RETENTION_MS, scheduleSystemOutputCleanup } from "../computer-access/command-output-retention.js";
 export { SYSTEM_OUTPUT_CAPABILITY, SYSTEM_OUTPUT_CHUNK_BYTES, readSystemOutputTransfer } from "../computer-access/companion/command-output-protocol.js";
+export type { SystemResultProtection } from "../computer-access/system-result-protection.js";
+export type { SystemApplication } from "../computer-access/contracts.js";
+export type { SystemApplicationCatalog, SystemApplicationCatalogScope } from "../computer-access/application-catalog.js";

package/dist/src/plugin-sdk/computer-access.js

@@ -1,4 +1,5 @@
 /** Shared computer access. Import this subpath only when your plugin uses the host. */
+export { HOST_SECRET_PROTECTION_CAPABILITY } from "../computer-access/companion/secret-protection-protocol.js";
 export { executeHostOperation, readHostStatus, } from "../computer-access/companion/broker-client.js";
 export { HOST_OPERATIONS, isHostIdentifier, isHostIdentity, isHostOperation, } from "../computer-access/companion/protocol.js";
 export { computerFields, computerInputError, computerRecord, computerText, readNativeComputerAction, readPhysicalRectangle, } from "../computer-access/computer/action-input.js";

package/dist/src/plugin-sdk/files-windows/process.d.ts

@@ -0,0 +1,3 @@
+import { spawn } from "node:child_process";
+/** Read-only helper. Never alters execution policy, retries, or reads through a fallback. */
+export declare function runWindowsBoundedRead(request: Readonly<Record<string, unknown>>, maxBytes: number, signal?: AbortSignal, spawnProcess?: typeof spawn): Promise<string>;

package/dist/src/plugin-sdk/files-windows/process.js

@@ -0,0 +1,93 @@
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { WINDOWS_BOUNDED_READ_SOURCE } from "./read-script.js";
+import { windowsReadAbortError, windowsReadError } from "./result.js";
+const BOOTSTRAP = [
+    "$ErrorActionPreference='Stop'",
+    'if ($ExecutionContext.SessionState.LanguageMode -ne \'FullLanguage\') { Write-Output \'{"ok":false,"code":"filesystem_windows_policy_blocked"}\'; exit 0 }',
+    "$env:PSModulePath=[IO.Path]::Combine($PSHOME,'Modules')",
+    "[Console]::InputEncoding=[Text.UTF8Encoding]::new($false)",
+    "[Console]::OutputEncoding=[Text.UTF8Encoding]::new($false)",
+    "$started=$false",
+    "try {",
+    "$envelope=[Console]::In.ReadToEnd() | ConvertFrom-Json",
+    "Add-Type -ReferencedAssemblies @('System.Web.Extensions') -TypeDefinition $envelope.source",
+    "$started=$true",
+    "[Console]::Write([AbotFilesystem]::Run($envelope.request))",
+    '} catch { if ($started) { [Console]::Write(\'{"ok":false,"code":"filesystem_native_operation_failed"}\') } else { [Console]::Write(\'{"ok":false,"code":"filesystem_windows_helper_unavailable"}\') } }',
+].join(";");
+const UNAVAILABLE = '{"ok":false,"code":"filesystem_windows_helper_unavailable"}';
+/** Read-only helper. Never alters execution policy, retries, or reads through a fallback. */
+export async function runWindowsBoundedRead(request, maxBytes, signal, spawnProcess = spawn) {
+    if (signal?.aborted)
+        throw windowsReadAbortError();
+    const input = JSON.stringify({
+        source: WINDOWS_BOUNDED_READ_SOURCE,
+        request: JSON.stringify(request),
+    });
+    if (Buffer.byteLength(input) > 2 * 1024 * 1024)
+        throw windowsReadError("EINVAL");
+    const outputLimit = 4 * Math.ceil(Math.min(maxBytes, 2_147_483_647) / 3) + 4096;
+    const executable = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    return new Promise((resolve, reject) => {
+        const child = spawnProcess(executable, ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", BOOTSTRAP], { windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+        const chunks = [];
+        let byteCount = 0;
+        let failure;
+        let unavailable = false;
+        const stop = (error) => {
+            failure ??= error;
+            child.kill("SIGKILL");
+        };
+        const abort = () => stop(windowsReadAbortError());
+        const timer = setTimeout(() => stop(windowsReadError("ETIMEDOUT")), 15_000);
+        timer.unref();
+        signal?.addEventListener("abort", abort, { once: true });
+        child.stdout.on("data", (chunk) => {
+            if (failure)
+                return;
+            byteCount += chunk.length;
+            if (byteCount > outputLimit) {
+                stop(windowsReadError("EOVERFLOW"));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        // Compiler/native diagnostics may contain private paths. Never expose them.
+        child.stderr.resume();
+        child.stdin.on("error", () => {
+            if (child.pid === undefined)
+                return;
+            stop(windowsReadError("EIO"));
+        });
+        child.once("error", () => {
+            if (child.pid === undefined) {
+                unavailable = true;
+                return;
+            }
+            stop(windowsReadError("EIO"));
+        });
+        child.once("close", (code) => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            if (failure) {
+                reject(failure);
+                return;
+            }
+            if (unavailable) {
+                resolve(UNAVAILABLE);
+                return;
+            }
+            if (code !== 0) {
+                reject(windowsReadError("EIO"));
+                return;
+            }
+            resolve(Buffer.concat(chunks).toString("utf8"));
+        });
+        if (signal?.aborted) {
+            abort();
+            return;
+        }
+        child.stdin.end(input, "utf8");
+    });
+}

package/dist/src/plugin-sdk/files-windows/read-script.d.ts

@@ -0,0 +1 @@
+export declare const WINDOWS_BOUNDED_READ_SOURCE: string;

package/dist/src/plugin-sdk/files-windows/read-script.js

@@ -0,0 +1,43 @@
+import { WINDOWS_FILESYSTEM_NATIVE } from "../../shared/windows-file-io/native-script.js";
+import { WINDOWS_FILESYSTEM_AUTHORITY } from "../../shared/windows-file-io/authority-script.js";
+import { WINDOWS_FILE_READ_BYTES } from "../../shared/windows-file-io/read-bytes-script.js";
+const BOUNDED_READ = String.raw `
+public static partial class AbotFilesystem {
+  static object ReadBounded(Dictionary<string,object> request) {
+    long maximum;
+    if (!Int64.TryParse(Text(request, "maxBytes"), out maximum) || maximum < 0 ||
+        maximum > 9007199254740991L) throw new FsFault("filesystem_invalid_request");
+    string[] parts=Components(request);
+    if (parts.Length == 0) return Record("ok", false, "reason", "not_regular_file");
+    using (var chain=new DirectoryChain(request)) {
+      chain.Walk(parts, parts.Length-1, false);
+      using (var file=OpenHandle(chain.Current, parts[parts.Length-1], false, 1, 0x80000000, 1)) {
+        var expected=request["targetIdentity"] as Dictionary<string,object>;
+        if (expected == null || !MatchesIdentity(Identity(file), expected))
+          return Record("ok", false, "reason", "changed_during_read");
+        var before=Metadata(file);
+        long size=Convert.ToInt64(before["size"]);
+        // Both the byte array and the base64 JSON response must fit .NET strings.
+        if (size > maximum || size > (Int32.MaxValue-4096L)/4*3)
+          return Record("ok", false, "reason", "too_large", "byteCount", size);
+        var bytes=ReadBytes(file, 0, (int)size);
+        if (!SameMetadata(before, Metadata(file)))
+          return Record("ok", false, "reason", "changed_during_read");
+        return Record("ok", true, "bytes", Convert.ToBase64String(bytes), "byteCount", size);
+      }
+    }
+  }
+  public static string Run(string input) {
+    var json=new JavaScriptSerializer { MaxJsonLength=Int32.MaxValue };
+    try { return json.Serialize(ReadBounded(json.Deserialize<Dictionary<string,object>>(input))); }
+    catch (FsFault error) { return json.Serialize(Record("ok", false, "code", error.Code)); }
+    catch { return json.Serialize(Record("ok", false, "code", "filesystem_native_operation_failed")); }
+  }
+}
+`;
+export const WINDOWS_BOUNDED_READ_SOURCE = [
+    WINDOWS_FILESYSTEM_NATIVE,
+    WINDOWS_FILESYSTEM_AUTHORITY,
+    WINDOWS_FILE_READ_BYTES,
+    BOUNDED_READ,
+].join("\n");

package/dist/src/plugin-sdk/files-windows/read.d.ts

@@ -0,0 +1,6 @@
+import type { BoundedRegularFileReadResult } from "../files.js";
+export declare function readWindowsBoundedRegularFile(absolutePath: string, options: Readonly<{
+    maxBytes: number;
+    rootPath: string;
+    signal?: AbortSignal;
+}>): Promise<BoundedRegularFileReadResult>;

package/dist/src/plugin-sdk/files-windows/read.js

@@ -0,0 +1,56 @@
+import { lstat, open, realpath } from "node:fs/promises";
+import { win32 } from "node:path";
+import { runWindowsBoundedRead } from "./process.js";
+import { decodeWindowsReadResult, windowsReadAbortError } from "./result.js";
+function isOutsideRoot(rootRelative) {
+    if (win32.isAbsolute(rootRelative))
+        return true;
+    if (rootRelative === "..")
+        return true;
+    return rootRelative.startsWith("..\\");
+}
+function identity(stats) {
+    return {
+        device: String(stats.dev),
+        inode: String(stats.ino),
+        birthtimeNs: String(stats.birthtimeNs),
+    };
+}
+export async function readWindowsBoundedRegularFile(absolutePath, options) {
+    const relativePath = win32.relative(options.rootPath, absolutePath);
+    if (isOutsideRoot(relativePath))
+        return Object.freeze({ ok: false, reason: "outside_root" });
+    if (relativePath === "")
+        return Object.freeze({ ok: false, reason: "not_regular_file" });
+    let root;
+    try {
+        const canonicalRoot = await realpath(options.rootPath);
+        root = await open(canonicalRoot, "r");
+        const rootStats = await root.stat({ bigint: true });
+        if (!rootStats.isDirectory() || rootStats.ino <= 0n)
+            return Object.freeze({ ok: false, reason: "safe_open_unsupported" });
+        // Metadata only: all content reads happen through the rooted native handles.
+        const targetPath = win32.resolve(canonicalRoot, relativePath);
+        const target = await lstat(targetPath, { bigint: true });
+        if (!target.isFile())
+            return Object.freeze({ ok: false, reason: "not_regular_file" });
+        const canonicalTarget = await realpath(targetPath);
+        if (isOutsideRoot(win32.relative(canonicalRoot, canonicalTarget)))
+            return Object.freeze({ ok: false, reason: "outside_root" });
+        if (options.signal?.aborted)
+            throw windowsReadAbortError();
+        const raw = await runWindowsBoundedRead({
+            rootPath: canonicalRoot,
+            relativePath: relativePath.split(win32.sep).join("/"),
+            rootIdentity: identity(rootStats),
+            targetIdentity: identity(target),
+            maxBytes: String(options.maxBytes),
+        }, options.maxBytes, options.signal);
+        if (options.signal?.aborted)
+            throw windowsReadAbortError();
+        return decodeWindowsReadResult(raw, options.maxBytes);
+    }
+    finally {
+        await root?.close();
+    }
+}

package/dist/src/plugin-sdk/files-windows/result.d.ts

@@ -0,0 +1,4 @@
+import type { BoundedRegularFileReadResult } from "../files.js";
+export declare function windowsReadError(code: string): Error;
+export declare function windowsReadAbortError(): Error;
+export declare function decodeWindowsReadResult(raw: string, maxBytes: number): BoundedRegularFileReadResult;

package/dist/src/plugin-sdk/files-windows/result.js

@@ -0,0 +1,67 @@
+export function windowsReadError(code) {
+    const error = new Error("The Windows safe file read failed (" + code + "). No fallback read was attempted.");
+    return Object.assign(error, { code });
+}
+export function windowsReadAbortError() {
+    const error = new Error("The file read was cancelled.");
+    error.name = "AbortError";
+    return error;
+}
+const FAILURE_REASONS = new Set([
+    "not_regular_file",
+    "too_large",
+    "changed_during_read",
+    "outside_root",
+    "safe_open_unsupported",
+]);
+function hasByteCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function decodeNativeFailure(code) {
+    switch (code) {
+        case "filesystem_windows_policy_blocked":
+        case "filesystem_windows_helper_unavailable":
+        case "filesystem_safe_io_unsupported":
+            return Object.freeze({ ok: false, reason: "safe_open_unsupported" });
+        case "filesystem_path_changed":
+        case "filesystem_target_changed":
+        case "filesystem_read_changed":
+        case "filesystem_read_incomplete":
+            return Object.freeze({ ok: false, reason: "changed_during_read" });
+        case "file_too_large":
+            return Object.freeze({ ok: false, reason: "too_large" });
+        case "file_not_found": throw windowsReadError("ENOENT");
+        case "filesystem_access_denied": throw windowsReadError("EACCES");
+        default: throw windowsReadError("EIO");
+    }
+}
+export function decodeWindowsReadResult(raw, maxBytes) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw windowsReadError("EIO");
+    }
+    if (value?.ok === false && typeof value.code === "string")
+        return decodeNativeFailure(value.code);
+    if (value?.ok === false && FAILURE_REASONS.has(value.reason)) {
+        if (value.byteCount !== undefined && !hasByteCount(value.byteCount))
+            throw windowsReadError("EIO");
+        return Object.freeze({
+            ok: false,
+            reason: value.reason,
+            ...(value.byteCount !== undefined ? { byteCount: value.byteCount } : {}),
+        });
+    }
+    if (value?.ok !== true || !hasByteCount(value.byteCount))
+        throw windowsReadError("EIO");
+    if (value.byteCount > maxBytes || typeof value.bytes !== "string")
+        throw windowsReadError("EIO");
+    if (value.bytes.length !== 4 * Math.ceil(value.byteCount / 3))
+        throw windowsReadError("EIO");
+    const bytes = Buffer.from(value.bytes, "base64");
+    if (bytes.length !== value.byteCount || bytes.toString("base64") !== value.bytes)
+        throw windowsReadError("EIO");
+    return Object.freeze({ ok: true, bytes, byteCount: value.byteCount });
+}

package/dist/src/plugin-sdk/files.js

@@ -24,6 +24,10 @@ export async function readBoundedRegularFile(absolutePath, options) {
         throw new RangeError("maxBytes must be a non-negative safe integer");
     }
     throwIfAborted(options.signal);
+    if (process.platform === "win32") {
+        const { readWindowsBoundedRegularFile } = await import("./files-windows/read.js");
+        return readWindowsBoundedRegularFile(absolutePath, options);
+    }
     if (typeof constants.O_NOFOLLOW !== "number") {
         return Object.freeze({ ok: false, reason: "safe_open_unsupported" });
     }

package/dist/src/plugin-sdk/index.d.ts

@@ -4,6 +4,7 @@ export * from "./parameters.js";
 export * from "./paths.js";
 export * from "./plugin.js";
 export * from "./results.js";
+export * from "./mutation-result.js";
 export * from "./context-text-result.js";
 export * from "../capabilities/tool-media.js";
 export * from "./tool-availability-brief.js";

package/dist/src/plugin-sdk/index.js

@@ -4,6 +4,7 @@ export * from "./parameters.js";
 export * from "./paths.js";
 export * from "./plugin.js";
 export * from "./results.js";
+export * from "./mutation-result.js";
 export * from "./context-text-result.js";
 export * from "../capabilities/tool-media.js";
 export * from "./tool-availability-brief.js";

package/dist/src/plugin-sdk/mutation-result.d.ts

@@ -0,0 +1,7 @@
+import type { ToolImplementationOutput } from "../plugin-contract/entrypoint.js";
+import { type SuccessResultInput, type ToolResultBudget } from "./results.js";
+/**
+ * Reports a mutation already confirmed by the owning plugin. This helper
+ * preserves its receipt; it does not execute or independently verify a change.
+ */
+export declare function mutationSuccessResult(input: SuccessResultInput, resultBudget?: ToolResultBudget): ToolImplementationOutput;

package/dist/src/plugin-sdk/mutation-result.js

@@ -0,0 +1,11 @@
+import { successResult, } from "./results.js";
+/**
+ * Reports a mutation already confirmed by the owning plugin. This helper
+ * preserves its receipt; it does not execute or independently verify a change.
+ */
+export function mutationSuccessResult(input, resultBudget) {
+    return successResult({
+        ...input,
+        data: { ...input.data, mutationEvidence: true },
+    }, resultBudget);
+}

package/dist/src/runtime/adapters/long-term-memory/file-lock/acquisition.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { removeEmptyLockTree, removeObservedOwner } from "./cleanup.js";
 import { fileSystemErrorCode, INCOMPLETE_LOCK_GRACE_MS, LOCK_ACQUIRE_TIMEOUT_MS, LOCK_RETRY_DELAY_MS, ownerFileName, } from "./contracts.js";
 import { installLockDirectory } from "./install.js";
+import { isWindowsLockReadDenial } from "./path-observation.js";
 import { readLockSnapshot } from "./snapshot.js";
 import { removeObservedOwnerSynchronously } from "./synchronous-release.js";
 export async function acquireFileLock(lockPath, options) {
@@ -18,7 +19,7 @@ export async function acquireFileLock(lockPath, options) {
         catch (error) {
             if (!isLockContention(error))
                 throw error;
-            const removed = await removeAbandonedLock(lockPath, processIsAlive);
+            const removed = await removeAbandonedLock(lockPath, processIsAlive, deadline, retryDelayMs);
             if (removed)
                 continue;
             if (Date.now() >= deadline) {
@@ -45,8 +46,8 @@ function createRelease(lockPath, token, releaseMode) {
 function requiresSynchronousRelease(mode) {
     return mode === "synchronous";
 }
-async function removeAbandonedLock(lockPath, processIsAlive) {
-    const snapshot = await readLockSnapshot(lockPath);
+async function removeAbandonedLock(lockPath, processIsAlive, deadline, retryDelayMs) {
+    const snapshot = await readContendedSnapshot(lockPath, deadline, retryDelayMs);
     if (!snapshot)
         return true;
     if (snapshot.kind === "legacy_file" || !snapshot.reclaimable)
@@ -64,6 +65,22 @@ async function removeAbandonedLock(lockPath, processIsAlive) {
     }
     return removeEmptyLockTree(lockPath, snapshot.hasLeaseDirectory);
 }
+async function readContendedSnapshot(lockPath, deadline, retryDelayMs) {
+    for (;;) {
+        try {
+            return await readLockSnapshot(lockPath);
+        }
+        catch (error) {
+            if (!isWindowsLockReadDenial(error))
+                throw error;
+            if (Date.now() >= deadline)
+                throw error;
+            // Windows can deny a pending deletion while stat still sees the directory.
+            // Wait within the acquisition budget; an unreadable owner is never reclaimed.
+            await delay(Math.min(retryDelayMs, Math.max(deadline - Date.now(), 0)));
+        }
+    }
+}
 async function hasLiveObservedOwner(snapshot, processIsAlive) {
     if (snapshot.ownerPid === undefined)
         return false;