@ai-agent-forge/plugin-workspace-files-write 0.85.0

package/README.md

@@ -0,0 +1,44 @@
+# @agent-forge/plugin-workspace-files-write
+
+Workspace file write capability plugin for [Agent Forge](https://github.com/agent-forge/agent-forge), extracted from
+the host's `src/plugins/workspace-files-write` (D-075 S3). It registers one full-control tool, `workspace_write`, which
+atomically replaces or patches a host-owned file using opaque file and artifact references; bytes and local paths never
+cross the capability boundary.
+
+The plugin is deliberately inert at load time. Without a host-bound write seam the tool reports an explicit
+`unsupported` result; hosts that want real writes bind `createNodeWorkspaceFilesWriteHostAdapterV1` (sandboxed root,
+artifact resolution, version-checked atomic commits) through their profile machinery. Readonly hosts get no tool
+registration at all.
+
+## Install
+
+```sh
+# from a local checkout
+agent-forge plugin install ./plugins/workspace-files-write
+
+# from npm
+agent-forge plugin install @agent-forge/plugin-workspace-files-write
+```
+
+The package ships two manifests: `agent-forge.json` (ecosystem manifest for the deterministic plugin resolver) and
+`plugin.json` (host-load manifest consumed by `loadCapabilityPluginFromManifest`, entry `./dist/entry.js`).
+
+## Library surface
+
+`import { createNodeWorkspaceFilesWriteHostAdapterV1, createWorkspaceFilesWriteCapabilityFactoryV1 } from "@agent-forge/plugin-workspace-files-write";`
+
+- `createNodeWorkspaceFilesWriteAdapterV1(options?)` — host-injection adapter; requires a host `write` seam, otherwise
+  returns `unsupported`.
+- `createNodeWorkspaceFilesWriteHostAdapterV1({ root, resolveFileRef, readArtifact, ... })` — real sandboxed host
+  writer: atomic rename commits, expectedVersion checks, per-path single-flight serialization, `committed` reporting.
+- `createWorkspaceFilesWriteCapabilityFactoryV1(adapter?)` — registers `workspace_write` on a full-control
+  `CapabilityAPI` (defaults to the unbound adapter).
+- Default export of `dist/entry.js` — the precomposed factory used by external plugin loading.
+
+## Development
+
+```sh
+npm install --ignore-scripts        # repo root, creates the workspace symlink
+npm run build                       # plugins/workspace-files-write (tsgo)
+npm test                            # vitest; the entry fidelity test requires `npm run build` first
+```

package/agent-forge.json

@@ -0,0 +1,12 @@
+{
+	"packageFormatVersion": 1,
+	"id": "agent-forge.plugin.workspace-files-write",
+	"pluginVersion": "0.84.4",
+	"apiVersion": "1",
+	"minHostVersion": "0.84.4",
+	"capabilityRefs": [{ "id": "workspace.files.write", "version": 1 }],
+	"platform": {
+		"os": ["windows", "macos", "linux"],
+		"runtime": [{ "name": "node" }]
+	}
+}

package/dist/capability.d.ts

@@ -0,0 +1,5 @@
+import type { CapabilityPluginSyncFactory } from "@agent-forge/plugin-sdk";
+import type { WorkspaceFilesWriteAdapterV1 } from "./types.ts";
+/** Registers opaque file writes and patches only for a full-control host. */
+export declare function createWorkspaceFilesWriteCapabilityFactoryV1(runtime?: WorkspaceFilesWriteAdapterV1): CapabilityPluginSyncFactory;
+//# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAU3E,OAAO,KAAK,EACX,4BAA4B,EAI5B,MAAM,YAAY,CAAC;AAwGpB,6EAA6E;AAC7E,wBAAgB,4CAA4C,CAC3D,OAAO,GAAE,4BAAuE,GAC9E,2BAA2B,CA+C7B","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { CapabilityPluginSyncFactory } from \"@agent-forge/plugin-sdk\";\nimport { Type } from \"typebox\";\nimport { Value } from \"typebox/value\";\nimport {\n\tcreateNodeWorkspaceFilesWriteAdapterV1,\n\tprojectWorkspaceFilesWriteV1,\n\tWORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1,\n\tWORKSPACE_FILES_WRITE_MAX_REF_CHARS_V1,\n\tWORKSPACE_FILES_WRITE_MAX_VERSION_CHARS_V1,\n} from \"./node-adapter.ts\";\nimport type {\n\tWorkspaceFilesWriteAdapterV1,\n\tWorkspaceFilesWriteModeV1,\n\tWorkspaceFilesWriteRequestV1,\n\tWorkspaceFilesWriteResultV1,\n} from \"./types.ts\";\n\nconst refSchema = Type.String({\n\tminLength: 1,\n\tmaxLength: WORKSPACE_FILES_WRITE_MAX_REF_CHARS_V1,\n\tpattern: \"^[A-Za-z0-9][A-Za-z0-9._:-]*$\",\n});\nconst requestSchema = Type.Object(\n\t{\n\t\tfileRef: refSchema,\n\t\tmode: Type.Union([Type.Literal(\"replace\"), Type.Literal(\"patch\")]),\n\t\tsourceArtifactRef: refSchema,\n\t\texpectedVersion: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tminLength: 1,\n\t\t\t\tmaxLength: WORKSPACE_FILES_WRITE_MAX_VERSION_CHARS_V1,\n\t\t\t\tpattern: \"^[A-Za-z0-9][A-Za-z0-9._:-]*$\",\n\t\t\t}),\n\t\t),\n\t\tcreateIfMissing: Type.Optional(Type.Boolean()),\n\t},\n\t{ additionalProperties: false },\n);\nconst inputSchema = Type.Object({ request: requestSchema }, { additionalProperties: false });\n\nfunction generatedOperationId(): string {\n\treturn `profile-runtime-tool-call-${randomUUID()}`;\n}\n\nfunction operationIdFor(first: unknown, second: unknown): string {\n\tconst explicit = second === undefined ? undefined : first;\n\treturn typeof explicit === \"string\" &&\n\t\texplicit.trim() !== \"\" &&\n\t\texplicit.length <= WORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1\n\t\t? explicit\n\t\t: generatedOperationId();\n}\n\nfunction objectInput(first: unknown, second: unknown): Record<string, unknown> {\n\tconst value = second === undefined ? first : second;\n\tif (value === null || typeof value !== \"object\" || Array.isArray(value))\n\t\tthrow new Error(\"Write input must be an object\");\n\treturn value as Record<string, unknown>;\n}\n\nfunction signalFrom(value: unknown): AbortSignal | undefined {\n\treturn value instanceof AbortSignal ? value : undefined;\n}\n\nfunction fallback(\n\toperationId: string,\n\tstatus: \"failed\" | \"cancelled\",\n\trequest?: Partial<WorkspaceFilesWriteRequestV1>,\n): WorkspaceFilesWriteResultV1 {\n\treturn {\n\t\tversion: 1,\n\t\toperationId,\n\t\tstatus,\n\t\tfileRef: request?.fileRef ?? \"invalid:file\",\n\t\tmode: (request?.mode ?? \"replace\") as WorkspaceFilesWriteModeV1,\n\t\tchanged: false,\n\t\tbytesWritten: 0,\n\t\terror: {\n\t\t\tversion: 1,\n\t\t\tcode: status === \"cancelled\" ? \"cancelled\" : \"adapter_failed\",\n\t\t\tmessage: status === \"cancelled\" ? \"Workspace write was cancelled\" : \"Workspace writer failed\",\n\t\t},\n\t};\n}\n\nfunction invalidInput(operationId: string): WorkspaceFilesWriteResultV1 {\n\treturn {\n\t\t...fallback(operationId, \"failed\"),\n\t\terror: { version: 1, code: \"invalid_input\", message: \"Workspace write request was invalid\" },\n\t};\n}\n\nfunction cancelled(operationId: string, request?: Partial<WorkspaceFilesWriteRequestV1>): WorkspaceFilesWriteResultV1 {\n\treturn fallback(operationId, \"cancelled\", request);\n}\n\nfunction malformed(operationId: string, request?: Partial<WorkspaceFilesWriteRequestV1>): WorkspaceFilesWriteResultV1 {\n\treturn {\n\t\t...fallback(operationId, \"failed\", request),\n\t\terror: { version: 1, code: \"adapter_failed\", message: \"Workspace writer returned an invalid result\" },\n\t};\n}\n\nasync function runWithCancellation(\n\trun: () => Promise<WorkspaceFilesWriteResultV1>,\n\tsignal: AbortSignal | undefined,\n\toperationId: string,\n\trequest: WorkspaceFilesWriteRequestV1,\n): Promise<WorkspaceFilesWriteResultV1> {\n\tconst result = await run();\n\tif (!signal?.aborted || result.status === \"cancelled\") return result;\n\tconst replacement = cancelled(operationId, request);\n\t// An adapter that already committed the write must not lose that fact when\n\t// its result is converted to cancelled after an abort.\n\treturn result.committed === true\n\t\t? { ...replacement, committed: true, changed: result.changed, bytesWritten: result.bytesWritten }\n\t\t: replacement;\n}\n\n/** Registers opaque file writes and patches only for a full-control host. */\nexport function createWorkspaceFilesWriteCapabilityFactoryV1(\n\truntime: WorkspaceFilesWriteAdapterV1 = createNodeWorkspaceFilesWriteAdapterV1(),\n): CapabilityPluginSyncFactory {\n\treturn (api) => {\n\t\tif (api.host.mode === \"readonly\") return;\n\t\tapi.registerTool({\n\t\t\tname: \"workspace_write\",\n\t\t\tlabel: \"Write workspace file\",\n\t\t\tdescription: \"Atomically replace or patch a host-owned file using opaque artifact references\",\n\t\t\tparameters: inputSchema,\n\t\t\texecute: async (first: unknown, second?: unknown, third?: unknown) => {\n\t\t\t\tconst operationId = operationIdFor(first, second);\n\t\t\t\tlet input: Record<string, unknown>;\n\t\t\t\ttry {\n\t\t\t\t\tinput = objectInput(first, second);\n\t\t\t\t\tif (!Value.Check(inputSchema, input)) return invalidInput(operationId);\n\t\t\t\t} catch {\n\t\t\t\t\treturn invalidInput(operationId);\n\t\t\t\t}\n\t\t\t\tconst requestInput = input.request as Record<string, unknown>;\n\t\t\t\tconst request: WorkspaceFilesWriteRequestV1 = {\n\t\t\t\t\tversion: 1,\n\t\t\t\t\toperationId,\n\t\t\t\t\tfileRef: requestInput.fileRef as string,\n\t\t\t\t\tmode: requestInput.mode as WorkspaceFilesWriteModeV1,\n\t\t\t\t\tsourceArtifactRef: requestInput.sourceArtifactRef as string,\n\t\t\t\t\t...(requestInput.expectedVersion === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { expectedVersion: requestInput.expectedVersion as string }),\n\t\t\t\t\t...(requestInput.createIfMissing === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { createIfMissing: requestInput.createIfMissing as boolean }),\n\t\t\t\t};\n\t\t\t\tconst signal = signalFrom(third);\n\t\t\t\tif (signal?.aborted) return cancelled(operationId, request);\n\t\t\t\ttry {\n\t\t\t\t\tconst output = await runWithCancellation(\n\t\t\t\t\t\t() => runtime.write(request, signal),\n\t\t\t\t\t\tsignal,\n\t\t\t\t\t\toperationId,\n\t\t\t\t\t\trequest,\n\t\t\t\t\t);\n\t\t\t\t\treturn projectWorkspaceFilesWriteV1(output, request) ?? malformed(operationId, request);\n\t\t\t\t} catch {\n\t\t\t\t\treturn signal?.aborted ? cancelled(operationId, request) : malformed(operationId, request);\n\t\t\t\t}\n\t\t\t},\n\t\t});\n\t};\n}\n"]}

package/dist/capability.js

@@ -0,0 +1,133 @@
+import { randomUUID } from "node:crypto";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { createNodeWorkspaceFilesWriteAdapterV1, projectWorkspaceFilesWriteV1, WORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1, WORKSPACE_FILES_WRITE_MAX_REF_CHARS_V1, WORKSPACE_FILES_WRITE_MAX_VERSION_CHARS_V1, } from "./node-adapter.js";
+const refSchema = Type.String({
+    minLength: 1,
+    maxLength: WORKSPACE_FILES_WRITE_MAX_REF_CHARS_V1,
+    pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
+});
+const requestSchema = Type.Object({
+    fileRef: refSchema,
+    mode: Type.Union([Type.Literal("replace"), Type.Literal("patch")]),
+    sourceArtifactRef: refSchema,
+    expectedVersion: Type.Optional(Type.String({
+        minLength: 1,
+        maxLength: WORKSPACE_FILES_WRITE_MAX_VERSION_CHARS_V1,
+        pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
+    })),
+    createIfMissing: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+const inputSchema = Type.Object({ request: requestSchema }, { additionalProperties: false });
+function generatedOperationId() {
+    return `profile-runtime-tool-call-${randomUUID()}`;
+}
+function operationIdFor(first, second) {
+    const explicit = second === undefined ? undefined : first;
+    return typeof explicit === "string" &&
+        explicit.trim() !== "" &&
+        explicit.length <= WORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1
+        ? explicit
+        : generatedOperationId();
+}
+function objectInput(first, second) {
+    const value = second === undefined ? first : second;
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Write input must be an object");
+    return value;
+}
+function signalFrom(value) {
+    return value instanceof AbortSignal ? value : undefined;
+}
+function fallback(operationId, status, request) {
+    return {
+        version: 1,
+        operationId,
+        status,
+        fileRef: request?.fileRef ?? "invalid:file",
+        mode: (request?.mode ?? "replace"),
+        changed: false,
+        bytesWritten: 0,
+        error: {
+            version: 1,
+            code: status === "cancelled" ? "cancelled" : "adapter_failed",
+            message: status === "cancelled" ? "Workspace write was cancelled" : "Workspace writer failed",
+        },
+    };
+}
+function invalidInput(operationId) {
+    return {
+        ...fallback(operationId, "failed"),
+        error: { version: 1, code: "invalid_input", message: "Workspace write request was invalid" },
+    };
+}
+function cancelled(operationId, request) {
+    return fallback(operationId, "cancelled", request);
+}
+function malformed(operationId, request) {
+    return {
+        ...fallback(operationId, "failed", request),
+        error: { version: 1, code: "adapter_failed", message: "Workspace writer returned an invalid result" },
+    };
+}
+async function runWithCancellation(run, signal, operationId, request) {
+    const result = await run();
+    if (!signal?.aborted || result.status === "cancelled")
+        return result;
+    const replacement = cancelled(operationId, request);
+    // An adapter that already committed the write must not lose that fact when
+    // its result is converted to cancelled after an abort.
+    return result.committed === true
+        ? { ...replacement, committed: true, changed: result.changed, bytesWritten: result.bytesWritten }
+        : replacement;
+}
+/** Registers opaque file writes and patches only for a full-control host. */
+export function createWorkspaceFilesWriteCapabilityFactoryV1(runtime = createNodeWorkspaceFilesWriteAdapterV1()) {
+    return (api) => {
+        if (api.host.mode === "readonly")
+            return;
+        api.registerTool({
+            name: "workspace_write",
+            label: "Write workspace file",
+            description: "Atomically replace or patch a host-owned file using opaque artifact references",
+            parameters: inputSchema,
+            execute: async (first, second, third) => {
+                const operationId = operationIdFor(first, second);
+                let input;
+                try {
+                    input = objectInput(first, second);
+                    if (!Value.Check(inputSchema, input))
+                        return invalidInput(operationId);
+                }
+                catch {
+                    return invalidInput(operationId);
+                }
+                const requestInput = input.request;
+                const request = {
+                    version: 1,
+                    operationId,
+                    fileRef: requestInput.fileRef,
+                    mode: requestInput.mode,
+                    sourceArtifactRef: requestInput.sourceArtifactRef,
+                    ...(requestInput.expectedVersion === undefined
+                        ? {}
+                        : { expectedVersion: requestInput.expectedVersion }),
+                    ...(requestInput.createIfMissing === undefined
+                        ? {}
+                        : { createIfMissing: requestInput.createIfMissing }),
+                };
+                const signal = signalFrom(third);
+                if (signal?.aborted)
+                    return cancelled(operationId, request);
+                try {
+                    const output = await runWithCancellation(() => runtime.write(request, signal), signal, operationId, request);
+                    return projectWorkspaceFilesWriteV1(output, request) ?? malformed(operationId, request);
+                }
+                catch {
+                    return signal?.aborted ? cancelled(operationId, request) : malformed(operationId, request);
+                }
+            },
+        });
+    };
+}
+//# sourceMappingURL=capability.js.map

package/dist/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { CapabilityPluginSyncFactory } from \"@agent-forge/plugin-sdk\";\nimport { Type } from \"typebox\";\nimport { Value } from \"typebox/value\";\nimport {\n\tcreateNodeWorkspaceFilesWriteAdapterV1,\n\tprojectWorkspaceFilesWriteV1,\n\tWORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1,\n\tWORKSPACE_FILES_WRITE_MAX_REF_CHARS_V1,\n\tWORKSPACE_FILES_WRITE_MAX_VERSION_CHARS_V1,\n} from \"./node-adapter.ts\";\nimport type {\n\tWorkspaceFilesWriteAdapterV1,\n\tWorkspaceFilesWriteModeV1,\n\tWorkspaceFilesWriteRequestV1,\n\tWorkspaceFilesWriteResultV1,\n} from \"./types.ts\";\n\nconst refSchema = Type.String({\n\tminLength: 1,\n\tmaxLength: WORKSPACE_FILES_WRITE_MAX_REF_CHARS_V1,\n\tpattern: \"^[A-Za-z0-9][A-Za-z0-9._:-]*$\",\n});\nconst requestSchema = Type.Object(\n\t{\n\t\tfileRef: refSchema,\n\t\tmode: Type.Union([Type.Literal(\"replace\"), Type.Literal(\"patch\")]),\n\t\tsourceArtifactRef: refSchema,\n\t\texpectedVersion: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tminLength: 1,\n\t\t\t\tmaxLength: WORKSPACE_FILES_WRITE_MAX_VERSION_CHARS_V1,\n\t\t\t\tpattern: \"^[A-Za-z0-9][A-Za-z0-9._:-]*$\",\n\t\t\t}),\n\t\t),\n\t\tcreateIfMissing: Type.Optional(Type.Boolean()),\n\t},\n\t{ additionalProperties: false },\n);\nconst inputSchema = Type.Object({ request: requestSchema }, { additionalProperties: false });\n\nfunction generatedOperationId(): string {\n\treturn `profile-runtime-tool-call-${randomUUID()}`;\n}\n\nfunction operationIdFor(first: unknown, second: unknown): string {\n\tconst explicit = second === undefined ? undefined : first;\n\treturn typeof explicit === \"string\" &&\n\t\texplicit.trim() !== \"\" &&\n\t\texplicit.length <= WORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1\n\t\t? explicit\n\t\t: generatedOperationId();\n}\n\nfunction objectInput(first: unknown, second: unknown): Record<string, unknown> {\n\tconst value = second === undefined ? first : second;\n\tif (value === null || typeof value !== \"object\" || Array.isArray(value))\n\t\tthrow new Error(\"Write input must be an object\");\n\treturn value as Record<string, unknown>;\n}\n\nfunction signalFrom(value: unknown): AbortSignal | undefined {\n\treturn value instanceof AbortSignal ? value : undefined;\n}\n\nfunction fallback(\n\toperationId: string,\n\tstatus: \"failed\" | \"cancelled\",\n\trequest?: Partial<WorkspaceFilesWriteRequestV1>,\n): WorkspaceFilesWriteResultV1 {\n\treturn {\n\t\tversion: 1,\n\t\toperationId,\n\t\tstatus,\n\t\tfileRef: request?.fileRef ?? \"invalid:file\",\n\t\tmode: (request?.mode ?? \"replace\") as WorkspaceFilesWriteModeV1,\n\t\tchanged: false,\n\t\tbytesWritten: 0,\n\t\terror: {\n\t\t\tversion: 1,\n\t\t\tcode: status === \"cancelled\" ? \"cancelled\" : \"adapter_failed\",\n\t\t\tmessage: status === \"cancelled\" ? \"Workspace write was cancelled\" : \"Workspace writer failed\",\n\t\t},\n\t};\n}\n\nfunction invalidInput(operationId: string): WorkspaceFilesWriteResultV1 {\n\treturn {\n\t\t...fallback(operationId, \"failed\"),\n\t\terror: { version: 1, code: \"invalid_input\", message: \"Workspace write request was invalid\" },\n\t};\n}\n\nfunction cancelled(operationId: string, request?: Partial<WorkspaceFilesWriteRequestV1>): WorkspaceFilesWriteResultV1 {\n\treturn fallback(operationId, \"cancelled\", request);\n}\n\nfunction malformed(operationId: string, request?: Partial<WorkspaceFilesWriteRequestV1>): WorkspaceFilesWriteResultV1 {\n\treturn {\n\t\t...fallback(operationId, \"failed\", request),\n\t\terror: { version: 1, code: \"adapter_failed\", message: \"Workspace writer returned an invalid result\" },\n\t};\n}\n\nasync function runWithCancellation(\n\trun: () => Promise<WorkspaceFilesWriteResultV1>,\n\tsignal: AbortSignal | undefined,\n\toperationId: string,\n\trequest: WorkspaceFilesWriteRequestV1,\n): Promise<WorkspaceFilesWriteResultV1> {\n\tconst result = await run();\n\tif (!signal?.aborted || result.status === \"cancelled\") return result;\n\tconst replacement = cancelled(operationId, request);\n\t// An adapter that already committed the write must not lose that fact when\n\t// its result is converted to cancelled after an abort.\n\treturn result.committed === true\n\t\t? { ...replacement, committed: true, changed: result.changed, bytesWritten: result.bytesWritten }\n\t\t: replacement;\n}\n\n/** Registers opaque file writes and patches only for a full-control host. */\nexport function createWorkspaceFilesWriteCapabilityFactoryV1(\n\truntime: WorkspaceFilesWriteAdapterV1 = createNodeWorkspaceFilesWriteAdapterV1(),\n): CapabilityPluginSyncFactory {\n\treturn (api) => {\n\t\tif (api.host.mode === \"readonly\") return;\n\t\tapi.registerTool({\n\t\t\tname: \"workspace_write\",\n\t\t\tlabel: \"Write workspace file\",\n\t\t\tdescription: \"Atomically replace or patch a host-owned file using opaque artifact references\",\n\t\t\tparameters: inputSchema,\n\t\t\texecute: async (first: unknown, second?: unknown, third?: unknown) => {\n\t\t\t\tconst operationId = operationIdFor(first, second);\n\t\t\t\tlet input: Record<string, unknown>;\n\t\t\t\ttry {\n\t\t\t\t\tinput = objectInput(first, second);\n\t\t\t\t\tif (!Value.Check(inputSchema, input)) return invalidInput(operationId);\n\t\t\t\t} catch {\n\t\t\t\t\treturn invalidInput(operationId);\n\t\t\t\t}\n\t\t\t\tconst requestInput = input.request as Record<string, unknown>;\n\t\t\t\tconst request: WorkspaceFilesWriteRequestV1 = {\n\t\t\t\t\tversion: 1,\n\t\t\t\t\toperationId,\n\t\t\t\t\tfileRef: requestInput.fileRef as string,\n\t\t\t\t\tmode: requestInput.mode as WorkspaceFilesWriteModeV1,\n\t\t\t\t\tsourceArtifactRef: requestInput.sourceArtifactRef as string,\n\t\t\t\t\t...(requestInput.expectedVersion === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { expectedVersion: requestInput.expectedVersion as string }),\n\t\t\t\t\t...(requestInput.createIfMissing === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { createIfMissing: requestInput.createIfMissing as boolean }),\n\t\t\t\t};\n\t\t\t\tconst signal = signalFrom(third);\n\t\t\t\tif (signal?.aborted) return cancelled(operationId, request);\n\t\t\t\ttry {\n\t\t\t\t\tconst output = await runWithCancellation(\n\t\t\t\t\t\t() => runtime.write(request, signal),\n\t\t\t\t\t\tsignal,\n\t\t\t\t\t\toperationId,\n\t\t\t\t\t\trequest,\n\t\t\t\t\t);\n\t\t\t\t\treturn projectWorkspaceFilesWriteV1(output, request) ?? malformed(operationId, request);\n\t\t\t\t} catch {\n\t\t\t\t\treturn signal?.aborted ? cancelled(operationId, request) : malformed(operationId, request);\n\t\t\t\t}\n\t\t\t},\n\t\t});\n\t};\n}\n"]}

package/dist/entry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Default-export factory consumed by the host's `loadCapabilityPluginFromManifest`.
+ *
+ * The capability factory already defaults to the Node adapter constructed
+ * without host injection: the write seam (artifact resolution, sandboxed
+ * paths, atomic writes) is host-owned, so the registered `workspace_write`
+ * tool reports an explicit `unsupported` result until a host binds a real
+ * writer through its own profile machinery (fail-closed by design, same
+ * contract as the embedded build). Readonly hosts get no tool registration
+ * at all.
+ */
+declare const _default: import("@agent-forge/plugin-sdk").CapabilityPluginSyncFactory;
+export default _default;
+//# sourceMappingURL=entry.d.ts.map

package/dist/entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../src/entry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;;AACH,wBAA8D","sourcesContent":["import { createWorkspaceFilesWriteCapabilityFactoryV1 } from \"./capability.ts\";\n\n/**\n * Default-export factory consumed by the host's `loadCapabilityPluginFromManifest`.\n *\n * The capability factory already defaults to the Node adapter constructed\n * without host injection: the write seam (artifact resolution, sandboxed\n * paths, atomic writes) is host-owned, so the registered `workspace_write`\n * tool reports an explicit `unsupported` result until a host binds a real\n * writer through its own profile machinery (fail-closed by design, same\n * contract as the embedded build). Readonly hosts get no tool registration\n * at all.\n */\nexport default createWorkspaceFilesWriteCapabilityFactoryV1();\n"]}

package/dist/entry.js

@@ -0,0 +1,14 @@
+import { createWorkspaceFilesWriteCapabilityFactoryV1 } from "./capability.js";
+/**
+ * Default-export factory consumed by the host's `loadCapabilityPluginFromManifest`.
+ *
+ * The capability factory already defaults to the Node adapter constructed
+ * without host injection: the write seam (artifact resolution, sandboxed
+ * paths, atomic writes) is host-owned, so the registered `workspace_write`
+ * tool reports an explicit `unsupported` result until a host binds a real
+ * writer through its own profile machinery (fail-closed by design, same
+ * contract as the embedded build). Readonly hosts get no tool registration
+ * at all.
+ */
+export default createWorkspaceFilesWriteCapabilityFactoryV1();
+//# sourceMappingURL=entry.js.map

package/dist/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../src/entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4CAA4C,EAAE,MAAM,iBAAiB,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,eAAe,4CAA4C,EAAE,CAAC","sourcesContent":["import { createWorkspaceFilesWriteCapabilityFactoryV1 } from \"./capability.ts\";\n\n/**\n * Default-export factory consumed by the host's `loadCapabilityPluginFromManifest`.\n *\n * The capability factory already defaults to the Node adapter constructed\n * without host injection: the write seam (artifact resolution, sandboxed\n * paths, atomic writes) is host-owned, so the registered `workspace_write`\n * tool reports an explicit `unsupported` result until a host binds a real\n * writer through its own profile machinery (fail-closed by design, same\n * contract as the embedded build). Readonly hosts get no tool registration\n * at all.\n */\nexport default createWorkspaceFilesWriteCapabilityFactoryV1();\n"]}

package/dist/host.d.ts

@@ -0,0 +1,22 @@
+import type { NodeWorkspaceFilesWriteHostOptionsV1, WorkspaceFilesPatchDocumentV1, WorkspaceFilesWriteAdapterV1, WorkspaceFilesWriteRequestV1, WorkspaceFilesWriteResultV1 } from "./types.ts";
+declare function resolveSandboxedPath(root: string, fileRef: string, resolveFileRef: NodeWorkspaceFilesWriteHostOptionsV1["resolveFileRef"], signal: AbortSignal): Promise<string>;
+declare function parsePatch(bytes: Uint8Array): WorkspaceFilesPatchDocumentV1;
+declare function applyPatch(source: Uint8Array, patchBytes: Uint8Array): Uint8Array;
+/**
+ * Host-level write: resolves the sandboxed path, then serializes the
+ * read-check-commit critical section per resolved canonical path so concurrent
+ * requests cannot both pass the expectedVersion check (single-flight). After
+ * the rename committed new bytes, a later artifact-record failure or
+ * cancellation is reported with `committed: true` and a truthful changed state
+ * instead of masking the write that already reached the disk. The timeout and
+ * stop race of the full adapter lives in node-adapter; this seam exposes the
+ * host mapping itself.
+ */
+export declare function createNodeWorkspaceFilesWriteHostWriteV1(options: NodeWorkspaceFilesWriteHostOptionsV1): (request: WorkspaceFilesWriteRequestV1, signal: AbortSignal) => Promise<WorkspaceFilesWriteResultV1>;
+/**
+ * Real Node host adapter. All local paths and bytes stay inside this host;
+ * model-facing requests and results remain opaque and bounded.
+ */
+export declare function createNodeWorkspaceFilesWriteHostAdapterV1(options: NodeWorkspaceFilesWriteHostOptionsV1): WorkspaceFilesWriteAdapterV1;
+export { applyPatch, parsePatch, resolveSandboxedPath };
+//# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACX,oCAAoC,EACpC,6BAA6B,EAE7B,4BAA4B,EAC5B,4BAA4B,EAC5B,2BAA2B,EAC3B,MAAM,YAAY,CAAC;AAmCpB,iBAAe,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,oCAAoC,CAAC,gBAAgB,CAAC,EACtE,MAAM,EAAE,WAAW,GACjB,OAAO,CAAC,MAAM,CAAC,CAoBjB;AAcD,iBAAS,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,6BAA6B,CAoCpE;AAED,iBAAS,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,GAAG,UAAU,CAW1E;AAeD;;;;;;;;;GASG;AACH,wBAAgB,wCAAwC,CACvD,OAAO,EAAE,oCAAoC,GAC3C,CAAC,OAAO,EAAE,4BAA4B,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,2BAA2B,CAAC,CAgItG;AAED;;;GAGG;AACH,wBAAgB,0CAA0C,CACzD,OAAO,EAAE,oCAAoC,GAC3C,4BAA4B,CAK9B;AAED,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,oBAAoB,EAAE,CAAC","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { readFile as fsReadFile, mkdtemp, realpath, rename, rm, stat, writeFile } from \"node:fs/promises\";\nimport { basename, dirname, isAbsolute, join, relative, resolve, sep } from \"node:path\";\nimport { createNodeWorkspaceFilesWriteAdapterV1 } from \"./node-adapter.ts\";\nimport type {\n\tNodeWorkspaceFilesWriteHostOptionsV1,\n\tWorkspaceFilesPatchDocumentV1,\n\tWorkspaceFilesPatchOperationV1,\n\tWorkspaceFilesWriteAdapterV1,\n\tWorkspaceFilesWriteRequestV1,\n\tWorkspaceFilesWriteResultV1,\n} from \"./types.ts\";\n\nconst MAX_ARTIFACT_BYTES_V1 = 256 * 1024 * 1024;\nconst MAX_PATCH_OPERATIONS_V1 = 16_384;\nconst MAX_PATCH_REPLACEMENT_CHARS_V1 = 1_048_576;\n\nclass HostWriteFailureV1 extends Error {\n\treadonly code: string;\n\n\tconstructor(code: string, message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"HostWriteFailureV1\";\n\t\tthis.code = code;\n\t}\n}\n\nfunction throwIfAborted(signal: AbortSignal): void {\n\tif (signal.aborted) throw new HostWriteFailureV1(\"cancelled\", \"Workspace write was cancelled\");\n}\n\nfunction digest(bytes: Uint8Array): string {\n\treturn createHash(\"sha256\").update(bytes).digest(\"hex\");\n}\n\nfunction isInside(root: string, target: string): boolean {\n\tconst relativePath = relative(root, target);\n\treturn (\n\t\trelativePath !== \"\" && relativePath !== \".\" && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath)\n\t);\n}\n\nfunction isWithin(root: string, target: string): boolean {\n\treturn target === root || isInside(root, target);\n}\n\nasync function resolveSandboxedPath(\n\troot: string,\n\tfileRef: string,\n\tresolveFileRef: NodeWorkspaceFilesWriteHostOptionsV1[\"resolveFileRef\"],\n\tsignal: AbortSignal,\n): Promise<string> {\n\tthrowIfAborted(signal);\n\tconst rootPath = await realpath(root);\n\tconst requested = await resolveFileRef(fileRef, signal);\n\tif (!isAbsolute(requested))\n\t\tthrow new HostWriteFailureV1(\"invalid_file_ref\", \"Resolved workspace file is not absolute\");\n\tconst candidate = resolve(requested);\n\tconst parent = await realpath(dirname(candidate));\n\tif (!isWithin(rootPath, parent))\n\t\tthrow new HostWriteFailureV1(\"sandbox_violation\", \"Workspace parent is outside the host root\");\n\tconst canonicalCandidate = join(parent, basename(candidate));\n\tlet existing: string | undefined;\n\ttry {\n\t\texisting = await realpath(canonicalCandidate);\n\t} catch {\n\t\texisting = undefined;\n\t}\n\tif (existing !== undefined && !isInside(rootPath, existing))\n\t\tthrow new HostWriteFailureV1(\"sandbox_violation\", \"Workspace file resolves outside the host root\");\n\treturn canonicalCandidate;\n}\n\nasync function readSourceArtifact(\n\trequest: WorkspaceFilesWriteRequestV1,\n\toptions: NodeWorkspaceFilesWriteHostOptionsV1,\n\tsignal: AbortSignal,\n): Promise<Uint8Array> {\n\tthrowIfAborted(signal);\n\tconst bytes = await options.readArtifact(request.sourceArtifactRef, signal);\n\tif (!(bytes instanceof Uint8Array) || bytes.byteLength > MAX_ARTIFACT_BYTES_V1)\n\t\tthrow new HostWriteFailureV1(\"artifact_budget_exceeded\", \"Workspace source artifact exceeds the host budget\");\n\treturn bytes;\n}\n\nfunction parsePatch(bytes: Uint8Array): WorkspaceFilesPatchDocumentV1 {\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(new TextDecoder(\"utf-8\", { fatal: true }).decode(bytes));\n\t} catch {\n\t\tthrow new HostWriteFailureV1(\"invalid_patch\", \"Workspace patch artifact is not valid UTF-8 JSON\");\n\t}\n\tif (value === null || typeof value !== \"object\" || Array.isArray(value))\n\t\tthrow new HostWriteFailureV1(\"invalid_patch\", \"Workspace patch document must be an object\");\n\tconst record = value as Record<string, unknown>;\n\tif (record.version !== 1 || !Array.isArray(record.operations) || record.operations.length > MAX_PATCH_OPERATIONS_V1)\n\t\tthrow new HostWriteFailureV1(\"invalid_patch\", \"Workspace patch document is invalid\");\n\tlet previousEnd = 0;\n\tconst operations: WorkspaceFilesPatchOperationV1[] = [];\n\tfor (const item of record.operations) {\n\t\tif (item === null || typeof item !== \"object\" || Array.isArray(item))\n\t\t\tthrow new HostWriteFailureV1(\"invalid_patch\", \"Workspace patch operation is invalid\");\n\t\tconst operation = item as Record<string, unknown>;\n\t\tif (\n\t\t\t!Number.isSafeInteger(operation.start) ||\n\t\t\t!Number.isSafeInteger(operation.end) ||\n\t\t\t(operation.start as number) < 0 ||\n\t\t\t(operation.end as number) < (operation.start as number) ||\n\t\t\ttypeof operation.replacement !== \"string\" ||\n\t\t\t[...(operation.replacement as string)].length > MAX_PATCH_REPLACEMENT_CHARS_V1 ||\n\t\t\t(operation.start as number) < previousEnd\n\t\t)\n\t\t\tthrow new HostWriteFailureV1(\"invalid_patch\", \"Workspace patch operation is invalid\");\n\t\tpreviousEnd = operation.end as number;\n\t\toperations.push({\n\t\t\tstart: operation.start as number,\n\t\t\tend: operation.end as number,\n\t\t\treplacement: operation.replacement as string,\n\t\t});\n\t}\n\treturn { version: 1, operations };\n}\n\nfunction applyPatch(source: Uint8Array, patchBytes: Uint8Array): Uint8Array {\n\tconst patch = parsePatch(patchBytes);\n\tconst text = new TextDecoder(\"utf-8\", { fatal: true }).decode(source);\n\tlet output = text;\n\tfor (let index = patch.operations.length - 1; index >= 0; index -= 1) {\n\t\tconst operation = patch.operations[index]!;\n\t\tif (operation.end > output.length)\n\t\t\tthrow new HostWriteFailureV1(\"invalid_patch\", \"Workspace patch range exceeds the file\");\n\t\toutput = `${output.slice(0, operation.start)}${operation.replacement}${output.slice(operation.end)}`;\n\t}\n\treturn new TextEncoder().encode(output);\n}\n\nasync function atomicWrite(path: string, bytes: Uint8Array, signal: AbortSignal): Promise<void> {\n\tthrowIfAborted(signal);\n\tconst directory = await mkdtemp(join(dirname(path), \".agent-forge-write-\"));\n\tconst temporary = join(directory, basename(path));\n\ttry {\n\t\tawait writeFile(temporary, bytes);\n\t\tthrowIfAborted(signal);\n\t\tawait rename(temporary, path);\n\t} finally {\n\t\tawait rm(directory, { recursive: true, force: true }).catch(() => undefined);\n\t}\n}\n\n/**\n * Host-level write: resolves the sandboxed path, then serializes the\n * read-check-commit critical section per resolved canonical path so concurrent\n * requests cannot both pass the expectedVersion check (single-flight). After\n * the rename committed new bytes, a later artifact-record failure or\n * cancellation is reported with `committed: true` and a truthful changed state\n * instead of masking the write that already reached the disk. The timeout and\n * stop race of the full adapter lives in node-adapter; this seam exposes the\n * host mapping itself.\n */\nexport function createNodeWorkspaceFilesWriteHostWriteV1(\n\toptions: NodeWorkspaceFilesWriteHostOptionsV1,\n): (request: WorkspaceFilesWriteRequestV1, signal: AbortSignal) => Promise<WorkspaceFilesWriteResultV1> {\n\tif (!isAbsolute(options.root)) throw new Error(\"root must be an absolute path\");\n\tconst writeGates = new Map<string, Promise<void>>();\n\tconst runSerialized = async <T>(key: string, work: () => Promise<T>): Promise<T> => {\n\t\tconst previous = writeGates.get(key);\n\t\tlet releaseGate: (() => void) | undefined;\n\t\tconst gate = new Promise<void>((resolveGate) => {\n\t\t\treleaseGate = resolveGate;\n\t\t});\n\t\tconst chained =\n\t\t\tprevious === undefined\n\t\t\t\t? gate\n\t\t\t\t: previous.then(\n\t\t\t\t\t\t() => gate,\n\t\t\t\t\t\t() => gate,\n\t\t\t\t\t);\n\t\twriteGates.set(key, chained);\n\t\ttry {\n\t\t\tawait previous;\n\t\t\treturn await work();\n\t\t} finally {\n\t\t\treleaseGate?.();\n\t\t\tif (writeGates.get(key) === chained) writeGates.delete(key);\n\t\t}\n\t};\n\tconst performWrite = async (\n\t\trequest: WorkspaceFilesWriteRequestV1,\n\t\tsignal: AbortSignal,\n\t): Promise<WorkspaceFilesWriteResultV1> => {\n\t\t/** Set only after the rename committed new bytes, so later failures cannot mask the disk state. */\n\t\tconst commit = { committed: false, bytes: 0 };\n\t\ttry {\n\t\t\tthrowIfAborted(signal);\n\t\t\tconst path = await resolveSandboxedPath(options.root, request.fileRef, options.resolveFileRef, signal);\n\t\t\treturn await runSerialized(path, async () => {\n\t\t\t\tthrowIfAborted(signal);\n\t\t\t\tlet current = new Uint8Array();\n\t\t\t\tlet exists = true;\n\t\t\t\ttry {\n\t\t\t\t\tconst information = await stat(path);\n\t\t\t\t\tif (!information.isFile())\n\t\t\t\t\t\tthrow new HostWriteFailureV1(\"invalid_file_ref\", \"Workspace target is not a file\");\n\t\t\t\t\tcurrent = new Uint8Array(\n\t\t\t\t\t\tawait (options.readWorkspaceFile === undefined\n\t\t\t\t\t\t\t? fsReadFile(path)\n\t\t\t\t\t\t\t: options.readWorkspaceFile(path, signal)),\n\t\t\t\t\t);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tif (error instanceof HostWriteFailureV1) throw error;\n\t\t\t\t\tif (error === null || typeof error !== \"object\" || (error as { code?: unknown }).code !== \"ENOENT\")\n\t\t\t\t\t\tthrow new HostWriteFailureV1(\"read_failed\", \"Workspace target could not be read\");\n\t\t\t\t\texists = false;\n\t\t\t\t}\n\t\t\t\tif (!exists && request.createIfMissing !== true)\n\t\t\t\t\tthrow new HostWriteFailureV1(\"file_missing\", \"Workspace target does not exist\");\n\t\t\t\tif (request.expectedVersion !== undefined && request.expectedVersion !== digest(current))\n\t\t\t\t\tthrow new HostWriteFailureV1(\n\t\t\t\t\t\t\"version_conflict\",\n\t\t\t\t\t\t\"Workspace target version does not match expectedVersion\",\n\t\t\t\t\t);\n\t\t\t\tconst source = await readSourceArtifact(request, options, signal);\n\t\t\t\tconst next = request.mode === \"replace\" ? source : applyPatch(current, source);\n\t\t\t\tconst changed = digest(current) !== digest(next);\n\t\t\t\tif (changed) {\n\t\t\t\t\tawait atomicWrite(path, next, signal);\n\t\t\t\t\tcommit.committed = true;\n\t\t\t\t\tcommit.bytes = next.byteLength;\n\t\t\t\t}\n\t\t\t\tconst outputArtifactRef =\n\t\t\t\t\toptions.writeArtifact === undefined\n\t\t\t\t\t\t? undefined\n\t\t\t\t\t\t: (\n\t\t\t\t\t\t\t\tawait options.writeArtifact(\n\t\t\t\t\t\t\t\t\t{ operationId: request.operationId, fileRef: request.fileRef, bytes: next },\n\t\t\t\t\t\t\t\t\tsignal,\n\t\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\t).artifactRef;\n\t\t\t\treturn {\n\t\t\t\t\tversion: 1 as const,\n\t\t\t\t\toperationId: request.operationId,\n\t\t\t\t\tstatus: \"succeeded\" as const,\n\t\t\t\t\tfileRef: request.fileRef,\n\t\t\t\t\tmode: request.mode,\n\t\t\t\t\tchanged,\n\t\t\t\t\tbytesWritten: changed ? next.byteLength : 0,\n\t\t\t\t\t...(outputArtifactRef === undefined ? {} : { outputArtifactRef }),\n\t\t\t\t\tversionToken: digest(next),\n\t\t\t\t};\n\t\t\t});\n\t\t} catch (error) {\n\t\t\tconst cancelled = signal.aborted || (error instanceof HostWriteFailureV1 && error.code === \"cancelled\");\n\t\t\tif (commit.committed) {\n\t\t\t\treturn {\n\t\t\t\t\tversion: 1 as const,\n\t\t\t\t\toperationId: request.operationId,\n\t\t\t\t\tstatus: cancelled ? (\"cancelled\" as const) : (\"failed\" as const),\n\t\t\t\t\tfileRef: request.fileRef,\n\t\t\t\t\tmode: request.mode,\n\t\t\t\t\tchanged: true,\n\t\t\t\t\tbytesWritten: commit.bytes,\n\t\t\t\t\tcommitted: true,\n\t\t\t\t\terror: {\n\t\t\t\t\t\tversion: 1 as const,\n\t\t\t\t\t\tcode: cancelled ? \"cancelled\" : \"artifact_record_failed\",\n\t\t\t\t\t\tmessage: cancelled\n\t\t\t\t\t\t\t? \"Workspace write was cancelled\"\n\t\t\t\t\t\t\t: \"Workspace file was committed but the artifact record failed\",\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst code = cancelled ? \"cancelled\" : error instanceof HostWriteFailureV1 ? error.code : \"adapter_failed\";\n\t\t\treturn {\n\t\t\t\tversion: 1 as const,\n\t\t\t\toperationId: request.operationId,\n\t\t\t\tstatus: cancelled ? (\"cancelled\" as const) : (\"failed\" as const),\n\t\t\t\tfileRef: request.fileRef,\n\t\t\t\tmode: request.mode,\n\t\t\t\tchanged: false,\n\t\t\t\tbytesWritten: 0,\n\t\t\t\terror: {\n\t\t\t\t\tversion: 1 as const,\n\t\t\t\t\tcode,\n\t\t\t\t\tmessage: cancelled ? \"Workspace write was cancelled\" : \"Workspace write failed\",\n\t\t\t\t},\n\t\t\t};\n\t\t}\n\t};\n\treturn performWrite;\n}\n\n/**\n * Real Node host adapter. All local paths and bytes stay inside this host;\n * model-facing requests and results remain opaque and bounded.\n */\nexport function createNodeWorkspaceFilesWriteHostAdapterV1(\n\toptions: NodeWorkspaceFilesWriteHostOptionsV1,\n): WorkspaceFilesWriteAdapterV1 {\n\treturn createNodeWorkspaceFilesWriteAdapterV1({\n\t\tdefaultTimeoutMs: options.defaultTimeoutMs,\n\t\twrite: createNodeWorkspaceFilesWriteHostWriteV1(options),\n\t});\n}\n\nexport { applyPatch, parsePatch, resolveSandboxedPath };\n"]}

package/dist/host.js

@@ -0,0 +1,258 @@
+import { createHash } from "node:crypto";
+import { readFile as fsReadFile, mkdtemp, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { createNodeWorkspaceFilesWriteAdapterV1 } from "./node-adapter.js";
+const MAX_ARTIFACT_BYTES_V1 = 256 * 1024 * 1024;
+const MAX_PATCH_OPERATIONS_V1 = 16_384;
+const MAX_PATCH_REPLACEMENT_CHARS_V1 = 1_048_576;
+class HostWriteFailureV1 extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "HostWriteFailureV1";
+        this.code = code;
+    }
+}
+function throwIfAborted(signal) {
+    if (signal.aborted)
+        throw new HostWriteFailureV1("cancelled", "Workspace write was cancelled");
+}
+function digest(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function isInside(root, target) {
+    const relativePath = relative(root, target);
+    return (relativePath !== "" && relativePath !== "." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath));
+}
+function isWithin(root, target) {
+    return target === root || isInside(root, target);
+}
+async function resolveSandboxedPath(root, fileRef, resolveFileRef, signal) {
+    throwIfAborted(signal);
+    const rootPath = await realpath(root);
+    const requested = await resolveFileRef(fileRef, signal);
+    if (!isAbsolute(requested))
+        throw new HostWriteFailureV1("invalid_file_ref", "Resolved workspace file is not absolute");
+    const candidate = resolve(requested);
+    const parent = await realpath(dirname(candidate));
+    if (!isWithin(rootPath, parent))
+        throw new HostWriteFailureV1("sandbox_violation", "Workspace parent is outside the host root");
+    const canonicalCandidate = join(parent, basename(candidate));
+    let existing;
+    try {
+        existing = await realpath(canonicalCandidate);
+    }
+    catch {
+        existing = undefined;
+    }
+    if (existing !== undefined && !isInside(rootPath, existing))
+        throw new HostWriteFailureV1("sandbox_violation", "Workspace file resolves outside the host root");
+    return canonicalCandidate;
+}
+async function readSourceArtifact(request, options, signal) {
+    throwIfAborted(signal);
+    const bytes = await options.readArtifact(request.sourceArtifactRef, signal);
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength > MAX_ARTIFACT_BYTES_V1)
+        throw new HostWriteFailureV1("artifact_budget_exceeded", "Workspace source artifact exceeds the host budget");
+    return bytes;
+}
+function parsePatch(bytes) {
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new HostWriteFailureV1("invalid_patch", "Workspace patch artifact is not valid UTF-8 JSON");
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new HostWriteFailureV1("invalid_patch", "Workspace patch document must be an object");
+    const record = value;
+    if (record.version !== 1 || !Array.isArray(record.operations) || record.operations.length > MAX_PATCH_OPERATIONS_V1)
+        throw new HostWriteFailureV1("invalid_patch", "Workspace patch document is invalid");
+    let previousEnd = 0;
+    const operations = [];
+    for (const item of record.operations) {
+        if (item === null || typeof item !== "object" || Array.isArray(item))
+            throw new HostWriteFailureV1("invalid_patch", "Workspace patch operation is invalid");
+        const operation = item;
+        if (!Number.isSafeInteger(operation.start) ||
+            !Number.isSafeInteger(operation.end) ||
+            operation.start < 0 ||
+            operation.end < operation.start ||
+            typeof operation.replacement !== "string" ||
+            [...operation.replacement].length > MAX_PATCH_REPLACEMENT_CHARS_V1 ||
+            operation.start < previousEnd)
+            throw new HostWriteFailureV1("invalid_patch", "Workspace patch operation is invalid");
+        previousEnd = operation.end;
+        operations.push({
+            start: operation.start,
+            end: operation.end,
+            replacement: operation.replacement,
+        });
+    }
+    return { version: 1, operations };
+}
+function applyPatch(source, patchBytes) {
+    const patch = parsePatch(patchBytes);
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(source);
+    let output = text;
+    for (let index = patch.operations.length - 1; index >= 0; index -= 1) {
+        const operation = patch.operations[index];
+        if (operation.end > output.length)
+            throw new HostWriteFailureV1("invalid_patch", "Workspace patch range exceeds the file");
+        output = `${output.slice(0, operation.start)}${operation.replacement}${output.slice(operation.end)}`;
+    }
+    return new TextEncoder().encode(output);
+}
+async function atomicWrite(path, bytes, signal) {
+    throwIfAborted(signal);
+    const directory = await mkdtemp(join(dirname(path), ".agent-forge-write-"));
+    const temporary = join(directory, basename(path));
+    try {
+        await writeFile(temporary, bytes);
+        throwIfAborted(signal);
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/**
+ * Host-level write: resolves the sandboxed path, then serializes the
+ * read-check-commit critical section per resolved canonical path so concurrent
+ * requests cannot both pass the expectedVersion check (single-flight). After
+ * the rename committed new bytes, a later artifact-record failure or
+ * cancellation is reported with `committed: true` and a truthful changed state
+ * instead of masking the write that already reached the disk. The timeout and
+ * stop race of the full adapter lives in node-adapter; this seam exposes the
+ * host mapping itself.
+ */
+export function createNodeWorkspaceFilesWriteHostWriteV1(options) {
+    if (!isAbsolute(options.root))
+        throw new Error("root must be an absolute path");
+    const writeGates = new Map();
+    const runSerialized = async (key, work) => {
+        const previous = writeGates.get(key);
+        let releaseGate;
+        const gate = new Promise((resolveGate) => {
+            releaseGate = resolveGate;
+        });
+        const chained = previous === undefined
+            ? gate
+            : previous.then(() => gate, () => gate);
+        writeGates.set(key, chained);
+        try {
+            await previous;
+            return await work();
+        }
+        finally {
+            releaseGate?.();
+            if (writeGates.get(key) === chained)
+                writeGates.delete(key);
+        }
+    };
+    const performWrite = async (request, signal) => {
+        /** Set only after the rename committed new bytes, so later failures cannot mask the disk state. */
+        const commit = { committed: false, bytes: 0 };
+        try {
+            throwIfAborted(signal);
+            const path = await resolveSandboxedPath(options.root, request.fileRef, options.resolveFileRef, signal);
+            return await runSerialized(path, async () => {
+                throwIfAborted(signal);
+                let current = new Uint8Array();
+                let exists = true;
+                try {
+                    const information = await stat(path);
+                    if (!information.isFile())
+                        throw new HostWriteFailureV1("invalid_file_ref", "Workspace target is not a file");
+                    current = new Uint8Array(await (options.readWorkspaceFile === undefined
+                        ? fsReadFile(path)
+                        : options.readWorkspaceFile(path, signal)));
+                }
+                catch (error) {
+                    if (error instanceof HostWriteFailureV1)
+                        throw error;
+                    if (error === null || typeof error !== "object" || error.code !== "ENOENT")
+                        throw new HostWriteFailureV1("read_failed", "Workspace target could not be read");
+                    exists = false;
+                }
+                if (!exists && request.createIfMissing !== true)
+                    throw new HostWriteFailureV1("file_missing", "Workspace target does not exist");
+                if (request.expectedVersion !== undefined && request.expectedVersion !== digest(current))
+                    throw new HostWriteFailureV1("version_conflict", "Workspace target version does not match expectedVersion");
+                const source = await readSourceArtifact(request, options, signal);
+                const next = request.mode === "replace" ? source : applyPatch(current, source);
+                const changed = digest(current) !== digest(next);
+                if (changed) {
+                    await atomicWrite(path, next, signal);
+                    commit.committed = true;
+                    commit.bytes = next.byteLength;
+                }
+                const outputArtifactRef = options.writeArtifact === undefined
+                    ? undefined
+                    : (await options.writeArtifact({ operationId: request.operationId, fileRef: request.fileRef, bytes: next }, signal)).artifactRef;
+                return {
+                    version: 1,
+                    operationId: request.operationId,
+                    status: "succeeded",
+                    fileRef: request.fileRef,
+                    mode: request.mode,
+                    changed,
+                    bytesWritten: changed ? next.byteLength : 0,
+                    ...(outputArtifactRef === undefined ? {} : { outputArtifactRef }),
+                    versionToken: digest(next),
+                };
+            });
+        }
+        catch (error) {
+            const cancelled = signal.aborted || (error instanceof HostWriteFailureV1 && error.code === "cancelled");
+            if (commit.committed) {
+                return {
+                    version: 1,
+                    operationId: request.operationId,
+                    status: cancelled ? "cancelled" : "failed",
+                    fileRef: request.fileRef,
+                    mode: request.mode,
+                    changed: true,
+                    bytesWritten: commit.bytes,
+                    committed: true,
+                    error: {
+                        version: 1,
+                        code: cancelled ? "cancelled" : "artifact_record_failed",
+                        message: cancelled
+                            ? "Workspace write was cancelled"
+                            : "Workspace file was committed but the artifact record failed",
+                    },
+                };
+            }
+            const code = cancelled ? "cancelled" : error instanceof HostWriteFailureV1 ? error.code : "adapter_failed";
+            return {
+                version: 1,
+                operationId: request.operationId,
+                status: cancelled ? "cancelled" : "failed",
+                fileRef: request.fileRef,
+                mode: request.mode,
+                changed: false,
+                bytesWritten: 0,
+                error: {
+                    version: 1,
+                    code,
+                    message: cancelled ? "Workspace write was cancelled" : "Workspace write failed",
+                },
+            };
+        }
+    };
+    return performWrite;
+}
+/**
+ * Real Node host adapter. All local paths and bytes stay inside this host;
+ * model-facing requests and results remain opaque and bounded.
+ */
+export function createNodeWorkspaceFilesWriteHostAdapterV1(options) {
+    return createNodeWorkspaceFilesWriteAdapterV1({
+        defaultTimeoutMs: options.defaultTimeoutMs,
+        write: createNodeWorkspaceFilesWriteHostWriteV1(options),
+    });
+}
+export { applyPatch, parsePatch, resolveSandboxedPath };
+//# sourceMappingURL=host.js.map

package/dist/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { readFile as fsReadFile, mkdtemp, realpath, rename, rm, stat, writeFile } from \"node:fs/promises\";\nimport { basename, dirname, isAbsolute, join, relative, resolve, sep } from \"node:path\";\nimport { createNodeWorkspaceFilesWriteAdapterV1 } from \"./node-adapter.ts\";\nimport type {\n\tNodeWorkspaceFilesWriteHostOptionsV1,\n\tWorkspaceFilesPatchDocumentV1,\n\tWorkspaceFilesPatchOperationV1,\n\tWorkspaceFilesWriteAdapterV1,\n\tWorkspaceFilesWriteRequestV1,\n\tWorkspaceFilesWriteResultV1,\n} from \"./types.ts\";\n\nconst MAX_ARTIFACT_BYTES_V1 = 256 * 1024 * 1024;\nconst MAX_PATCH_OPERATIONS_V1 = 16_384;\nconst MAX_PATCH_REPLACEMENT_CHARS_V1 = 1_048_576;\n\nclass HostWriteFailureV1 extends Error {\n\treadonly code: string;\n\n\tconstructor(code: string, message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"HostWriteFailureV1\";\n\t\tthis.code = code;\n\t}\n}\n\nfunction throwIfAborted(signal: AbortSignal): void {\n\tif (signal.aborted) throw new HostWriteFailureV1(\"cancelled\", \"Workspace write was cancelled\");\n}\n\nfunction digest(bytes: Uint8Array): string {\n\treturn createHash(\"sha256\").update(bytes).digest(\"hex\");\n}\n\nfunction isInside(root: string, target: string): boolean {\n\tconst relativePath = relative(root, target);\n\treturn (\n\t\trelativePath !== \"\" && relativePath !== \".\" && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath)\n\t);\n}\n\nfunction isWithin(root: string, target: string): boolean {\n\treturn target === root || isInside(root, target);\n}\n\nasync function resolveSandboxedPath(\n\troot: string,\n\tfileRef: string,\n\tresolveFileRef: NodeWorkspaceFilesWriteHostOptionsV1[\"resolveFileRef\"],\n\tsignal: AbortSignal,\n): Promise<string> {\n\tthrowIfAborted(signal);\n\tconst rootPath = await realpath(root);\n\tconst requested = await resolveFileRef(fileRef, signal);\n\tif (!isAbsolute(requested))\n\t\tthrow new HostWriteFailureV1(\"invalid_file_ref\", \"Resolved workspace file is not absolute\");\n\tconst candidate = resolve(requested);\n\tconst parent = await realpath(dirname(candidate));\n\tif (!isWithin(rootPath, parent))\n\t\tthrow new HostWriteFailureV1(\"sandbox_violation\", \"Workspace parent is outside the host root\");\n\tconst canonicalCandidate = join(parent, basename(candidate));\n\tlet existing: string | undefined;\n\ttry {\n\t\texisting = await realpath(canonicalCandidate);\n\t} catch {\n\t\texisting = undefined;\n\t}\n\tif (existing !== undefined && !isInside(rootPath, existing))\n\t\tthrow new HostWriteFailureV1(\"sandbox_violation\", \"Workspace file resolves outside the host root\");\n\treturn canonicalCandidate;\n}\n\nasync function readSourceArtifact(\n\trequest: WorkspaceFilesWriteRequestV1,\n\toptions: NodeWorkspaceFilesWriteHostOptionsV1,\n\tsignal: AbortSignal,\n): Promise<Uint8Array> {\n\tthrowIfAborted(signal);\n\tconst bytes = await options.readArtifact(request.sourceArtifactRef, signal);\n\tif (!(bytes instanceof Uint8Array) || bytes.byteLength > MAX_ARTIFACT_BYTES_V1)\n\t\tthrow new HostWriteFailureV1(\"artifact_budget_exceeded\", \"Workspace source artifact exceeds the host budget\");\n\treturn bytes;\n}\n\nfunction parsePatch(bytes: Uint8Array): WorkspaceFilesPatchDocumentV1 {\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(new TextDecoder(\"utf-8\", { fatal: true }).decode(bytes));\n\t} catch {\n\t\tthrow new HostWriteFailureV1(\"invalid_patch\", \"Workspace patch artifact is not valid UTF-8 JSON\");\n\t}\n\tif (value === null || typeof value !== \"object\" || Array.isArray(value))\n\t\tthrow new HostWriteFailureV1(\"invalid_patch\", \"Workspace patch document must be an object\");\n\tconst record = value as Record<string, unknown>;\n\tif (record.version !== 1 || !Array.isArray(record.operations) || record.operations.length > MAX_PATCH_OPERATIONS_V1)\n\t\tthrow new HostWriteFailureV1(\"invalid_patch\", \"Workspace patch document is invalid\");\n\tlet previousEnd = 0;\n\tconst operations: WorkspaceFilesPatchOperationV1[] = [];\n\tfor (const item of record.operations) {\n\t\tif (item === null || typeof item !== \"object\" || Array.isArray(item))\n\t\t\tthrow new HostWriteFailureV1(\"invalid_patch\", \"Workspace patch operation is invalid\");\n\t\tconst operation = item as Record<string, unknown>;\n\t\tif (\n\t\t\t!Number.isSafeInteger(operation.start) ||\n\t\t\t!Number.isSafeInteger(operation.end) ||\n\t\t\t(operation.start as number) < 0 ||\n\t\t\t(operation.end as number) < (operation.start as number) ||\n\t\t\ttypeof operation.replacement !== \"string\" ||\n\t\t\t[...(operation.replacement as string)].length > MAX_PATCH_REPLACEMENT_CHARS_V1 ||\n\t\t\t(operation.start as number) < previousEnd\n\t\t)\n\t\t\tthrow new HostWriteFailureV1(\"invalid_patch\", \"Workspace patch operation is invalid\");\n\t\tpreviousEnd = operation.end as number;\n\t\toperations.push({\n\t\t\tstart: operation.start as number,\n\t\t\tend: operation.end as number,\n\t\t\treplacement: operation.replacement as string,\n\t\t});\n\t}\n\treturn { version: 1, operations };\n}\n\nfunction applyPatch(source: Uint8Array, patchBytes: Uint8Array): Uint8Array {\n\tconst patch = parsePatch(patchBytes);\n\tconst text = new TextDecoder(\"utf-8\", { fatal: true }).decode(source);\n\tlet output = text;\n\tfor (let index = patch.operations.length - 1; index >= 0; index -= 1) {\n\t\tconst operation = patch.operations[index]!;\n\t\tif (operation.end > output.length)\n\t\t\tthrow new HostWriteFailureV1(\"invalid_patch\", \"Workspace patch range exceeds the file\");\n\t\toutput = `${output.slice(0, operation.start)}${operation.replacement}${output.slice(operation.end)}`;\n\t}\n\treturn new TextEncoder().encode(output);\n}\n\nasync function atomicWrite(path: string, bytes: Uint8Array, signal: AbortSignal): Promise<void> {\n\tthrowIfAborted(signal);\n\tconst directory = await mkdtemp(join(dirname(path), \".agent-forge-write-\"));\n\tconst temporary = join(directory, basename(path));\n\ttry {\n\t\tawait writeFile(temporary, bytes);\n\t\tthrowIfAborted(signal);\n\t\tawait rename(temporary, path);\n\t} finally {\n\t\tawait rm(directory, { recursive: true, force: true }).catch(() => undefined);\n\t}\n}\n\n/**\n * Host-level write: resolves the sandboxed path, then serializes the\n * read-check-commit critical section per resolved canonical path so concurrent\n * requests cannot both pass the expectedVersion check (single-flight). After\n * the rename committed new bytes, a later artifact-record failure or\n * cancellation is reported with `committed: true` and a truthful changed state\n * instead of masking the write that already reached the disk. The timeout and\n * stop race of the full adapter lives in node-adapter; this seam exposes the\n * host mapping itself.\n */\nexport function createNodeWorkspaceFilesWriteHostWriteV1(\n\toptions: NodeWorkspaceFilesWriteHostOptionsV1,\n): (request: WorkspaceFilesWriteRequestV1, signal: AbortSignal) => Promise<WorkspaceFilesWriteResultV1> {\n\tif (!isAbsolute(options.root)) throw new Error(\"root must be an absolute path\");\n\tconst writeGates = new Map<string, Promise<void>>();\n\tconst runSerialized = async <T>(key: string, work: () => Promise<T>): Promise<T> => {\n\t\tconst previous = writeGates.get(key);\n\t\tlet releaseGate: (() => void) | undefined;\n\t\tconst gate = new Promise<void>((resolveGate) => {\n\t\t\treleaseGate = resolveGate;\n\t\t});\n\t\tconst chained =\n\t\t\tprevious === undefined\n\t\t\t\t? gate\n\t\t\t\t: previous.then(\n\t\t\t\t\t\t() => gate,\n\t\t\t\t\t\t() => gate,\n\t\t\t\t\t);\n\t\twriteGates.set(key, chained);\n\t\ttry {\n\t\t\tawait previous;\n\t\t\treturn await work();\n\t\t} finally {\n\t\t\treleaseGate?.();\n\t\t\tif (writeGates.get(key) === chained) writeGates.delete(key);\n\t\t}\n\t};\n\tconst performWrite = async (\n\t\trequest: WorkspaceFilesWriteRequestV1,\n\t\tsignal: AbortSignal,\n\t): Promise<WorkspaceFilesWriteResultV1> => {\n\t\t/** Set only after the rename committed new bytes, so later failures cannot mask the disk state. */\n\t\tconst commit = { committed: false, bytes: 0 };\n\t\ttry {\n\t\t\tthrowIfAborted(signal);\n\t\t\tconst path = await resolveSandboxedPath(options.root, request.fileRef, options.resolveFileRef, signal);\n\t\t\treturn await runSerialized(path, async () => {\n\t\t\t\tthrowIfAborted(signal);\n\t\t\t\tlet current = new Uint8Array();\n\t\t\t\tlet exists = true;\n\t\t\t\ttry {\n\t\t\t\t\tconst information = await stat(path);\n\t\t\t\t\tif (!information.isFile())\n\t\t\t\t\t\tthrow new HostWriteFailureV1(\"invalid_file_ref\", \"Workspace target is not a file\");\n\t\t\t\t\tcurrent = new Uint8Array(\n\t\t\t\t\t\tawait (options.readWorkspaceFile === undefined\n\t\t\t\t\t\t\t? fsReadFile(path)\n\t\t\t\t\t\t\t: options.readWorkspaceFile(path, signal)),\n\t\t\t\t\t);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tif (error instanceof HostWriteFailureV1) throw error;\n\t\t\t\t\tif (error === null || typeof error !== \"object\" || (error as { code?: unknown }).code !== \"ENOENT\")\n\t\t\t\t\t\tthrow new HostWriteFailureV1(\"read_failed\", \"Workspace target could not be read\");\n\t\t\t\t\texists = false;\n\t\t\t\t}\n\t\t\t\tif (!exists && request.createIfMissing !== true)\n\t\t\t\t\tthrow new HostWriteFailureV1(\"file_missing\", \"Workspace target does not exist\");\n\t\t\t\tif (request.expectedVersion !== undefined && request.expectedVersion !== digest(current))\n\t\t\t\t\tthrow new HostWriteFailureV1(\n\t\t\t\t\t\t\"version_conflict\",\n\t\t\t\t\t\t\"Workspace target version does not match expectedVersion\",\n\t\t\t\t\t);\n\t\t\t\tconst source = await readSourceArtifact(request, options, signal);\n\t\t\t\tconst next = request.mode === \"replace\" ? source : applyPatch(current, source);\n\t\t\t\tconst changed = digest(current) !== digest(next);\n\t\t\t\tif (changed) {\n\t\t\t\t\tawait atomicWrite(path, next, signal);\n\t\t\t\t\tcommit.committed = true;\n\t\t\t\t\tcommit.bytes = next.byteLength;\n\t\t\t\t}\n\t\t\t\tconst outputArtifactRef =\n\t\t\t\t\toptions.writeArtifact === undefined\n\t\t\t\t\t\t? undefined\n\t\t\t\t\t\t: (\n\t\t\t\t\t\t\t\tawait options.writeArtifact(\n\t\t\t\t\t\t\t\t\t{ operationId: request.operationId, fileRef: request.fileRef, bytes: next },\n\t\t\t\t\t\t\t\t\tsignal,\n\t\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\t).artifactRef;\n\t\t\t\treturn {\n\t\t\t\t\tversion: 1 as const,\n\t\t\t\t\toperationId: request.operationId,\n\t\t\t\t\tstatus: \"succeeded\" as const,\n\t\t\t\t\tfileRef: request.fileRef,\n\t\t\t\t\tmode: request.mode,\n\t\t\t\t\tchanged,\n\t\t\t\t\tbytesWritten: changed ? next.byteLength : 0,\n\t\t\t\t\t...(outputArtifactRef === undefined ? {} : { outputArtifactRef }),\n\t\t\t\t\tversionToken: digest(next),\n\t\t\t\t};\n\t\t\t});\n\t\t} catch (error) {\n\t\t\tconst cancelled = signal.aborted || (error instanceof HostWriteFailureV1 && error.code === \"cancelled\");\n\t\t\tif (commit.committed) {\n\t\t\t\treturn {\n\t\t\t\t\tversion: 1 as const,\n\t\t\t\t\toperationId: request.operationId,\n\t\t\t\t\tstatus: cancelled ? (\"cancelled\" as const) : (\"failed\" as const),\n\t\t\t\t\tfileRef: request.fileRef,\n\t\t\t\t\tmode: request.mode,\n\t\t\t\t\tchanged: true,\n\t\t\t\t\tbytesWritten: commit.bytes,\n\t\t\t\t\tcommitted: true,\n\t\t\t\t\terror: {\n\t\t\t\t\t\tversion: 1 as const,\n\t\t\t\t\t\tcode: cancelled ? \"cancelled\" : \"artifact_record_failed\",\n\t\t\t\t\t\tmessage: cancelled\n\t\t\t\t\t\t\t? \"Workspace write was cancelled\"\n\t\t\t\t\t\t\t: \"Workspace file was committed but the artifact record failed\",\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst code = cancelled ? \"cancelled\" : error instanceof HostWriteFailureV1 ? error.code : \"adapter_failed\";\n\t\t\treturn {\n\t\t\t\tversion: 1 as const,\n\t\t\t\toperationId: request.operationId,\n\t\t\t\tstatus: cancelled ? (\"cancelled\" as const) : (\"failed\" as const),\n\t\t\t\tfileRef: request.fileRef,\n\t\t\t\tmode: request.mode,\n\t\t\t\tchanged: false,\n\t\t\t\tbytesWritten: 0,\n\t\t\t\terror: {\n\t\t\t\t\tversion: 1 as const,\n\t\t\t\t\tcode,\n\t\t\t\t\tmessage: cancelled ? \"Workspace write was cancelled\" : \"Workspace write failed\",\n\t\t\t\t},\n\t\t\t};\n\t\t}\n\t};\n\treturn performWrite;\n}\n\n/**\n * Real Node host adapter. All local paths and bytes stay inside this host;\n * model-facing requests and results remain opaque and bounded.\n */\nexport function createNodeWorkspaceFilesWriteHostAdapterV1(\n\toptions: NodeWorkspaceFilesWriteHostOptionsV1,\n): WorkspaceFilesWriteAdapterV1 {\n\treturn createNodeWorkspaceFilesWriteAdapterV1({\n\t\tdefaultTimeoutMs: options.defaultTimeoutMs,\n\t\twrite: createNodeWorkspaceFilesWriteHostWriteV1(options),\n\t});\n}\n\nexport { applyPatch, parsePatch, resolveSandboxedPath };\n"]}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createWorkspaceFilesWriteCapabilityFactoryV1 } from "./capability.ts";
+export { applyPatch, createNodeWorkspaceFilesWriteHostAdapterV1, createNodeWorkspaceFilesWriteHostWriteV1, parsePatch, resolveSandboxedPath, } from "./host.ts";
+export { createNodeWorkspaceFilesWriteAdapterV1, projectWorkspaceFilesWriteV1, WORKSPACE_FILES_WRITE_MAX_BYTES_V1, WORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1, WORKSPACE_FILES_WRITE_MAX_OUTPUT_BYTES_V1, WORKSPACE_FILES_WRITE_MAX_REF_CHARS_V1, WORKSPACE_FILES_WRITE_MAX_VERSION_CHARS_V1, } from "./node-adapter.ts";
+export type * from "./types.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4CAA4C,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EACN,UAAU,EACV,0CAA0C,EAC1C,wCAAwC,EACxC,UAAU,EACV,oBAAoB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,sCAAsC,EACtC,4BAA4B,EAC5B,kCAAkC,EAClC,+CAA+C,EAC/C,yCAAyC,EACzC,sCAAsC,EACtC,0CAA0C,GAC1C,MAAM,mBAAmB,CAAC;AAC3B,mBAAmB,YAAY,CAAC","sourcesContent":["export { createWorkspaceFilesWriteCapabilityFactoryV1 } from \"./capability.ts\";\nexport {\n\tapplyPatch,\n\tcreateNodeWorkspaceFilesWriteHostAdapterV1,\n\tcreateNodeWorkspaceFilesWriteHostWriteV1,\n\tparsePatch,\n\tresolveSandboxedPath,\n} from \"./host.ts\";\nexport {\n\tcreateNodeWorkspaceFilesWriteAdapterV1,\n\tprojectWorkspaceFilesWriteV1,\n\tWORKSPACE_FILES_WRITE_MAX_BYTES_V1,\n\tWORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1,\n\tWORKSPACE_FILES_WRITE_MAX_OUTPUT_BYTES_V1,\n\tWORKSPACE_FILES_WRITE_MAX_REF_CHARS_V1,\n\tWORKSPACE_FILES_WRITE_MAX_VERSION_CHARS_V1,\n} from \"./node-adapter.ts\";\nexport type * from \"./types.ts\";\n"]}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createWorkspaceFilesWriteCapabilityFactoryV1 } from "./capability.js";
+export { applyPatch, createNodeWorkspaceFilesWriteHostAdapterV1, createNodeWorkspaceFilesWriteHostWriteV1, parsePatch, resolveSandboxedPath, } from "./host.js";
+export { createNodeWorkspaceFilesWriteAdapterV1, projectWorkspaceFilesWriteV1, WORKSPACE_FILES_WRITE_MAX_BYTES_V1, WORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1, WORKSPACE_FILES_WRITE_MAX_OUTPUT_BYTES_V1, WORKSPACE_FILES_WRITE_MAX_REF_CHARS_V1, WORKSPACE_FILES_WRITE_MAX_VERSION_CHARS_V1, } from "./node-adapter.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4CAA4C,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EACN,UAAU,EACV,0CAA0C,EAC1C,wCAAwC,EACxC,UAAU,EACV,oBAAoB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,sCAAsC,EACtC,4BAA4B,EAC5B,kCAAkC,EAClC,+CAA+C,EAC/C,yCAAyC,EACzC,sCAAsC,EACtC,0CAA0C,GAC1C,MAAM,mBAAmB,CAAC","sourcesContent":["export { createWorkspaceFilesWriteCapabilityFactoryV1 } from \"./capability.ts\";\nexport {\n\tapplyPatch,\n\tcreateNodeWorkspaceFilesWriteHostAdapterV1,\n\tcreateNodeWorkspaceFilesWriteHostWriteV1,\n\tparsePatch,\n\tresolveSandboxedPath,\n} from \"./host.ts\";\nexport {\n\tcreateNodeWorkspaceFilesWriteAdapterV1,\n\tprojectWorkspaceFilesWriteV1,\n\tWORKSPACE_FILES_WRITE_MAX_BYTES_V1,\n\tWORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1,\n\tWORKSPACE_FILES_WRITE_MAX_OUTPUT_BYTES_V1,\n\tWORKSPACE_FILES_WRITE_MAX_REF_CHARS_V1,\n\tWORKSPACE_FILES_WRITE_MAX_VERSION_CHARS_V1,\n} from \"./node-adapter.ts\";\nexport type * from \"./types.ts\";\n"]}

package/dist/node-adapter.d.ts

@@ -0,0 +1,13 @@
+import { type NodeWorkspaceFilesWriteAdapterOptionsV1, type WorkspaceFilesWriteAdapterV1, type WorkspaceFilesWriteRequestV1, type WorkspaceFilesWriteResultV1 } from "./types.ts";
+export declare const WORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1 = 256;
+export declare const WORKSPACE_FILES_WRITE_MAX_REF_CHARS_V1 = 256;
+export declare const WORKSPACE_FILES_WRITE_MAX_VERSION_CHARS_V1 = 256;
+export declare const WORKSPACE_FILES_WRITE_MAX_OUTPUT_BYTES_V1: number;
+export declare const WORKSPACE_FILES_WRITE_MAX_BYTES_V1: number;
+declare function safeRef(value: unknown): value is string;
+declare function validateRequest(request: WorkspaceFilesWriteRequestV1): string | undefined;
+/** Projects host output down to status and bounded metadata; it never returns content. */
+export declare function projectWorkspaceFilesWriteV1(value: unknown, request: WorkspaceFilesWriteRequestV1): WorkspaceFilesWriteResultV1 | undefined;
+export declare function createNodeWorkspaceFilesWriteAdapterV1(options?: NodeWorkspaceFilesWriteAdapterOptionsV1): WorkspaceFilesWriteAdapterV1;
+export { safeRef, validateRequest };
+//# sourceMappingURL=node-adapter.d.ts.map

package/dist/node-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-adapter.d.ts","sourceRoot":"","sources":["../src/node-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,KAAK,uCAAuC,EAG5C,KAAK,4BAA4B,EAEjC,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,+CAA+C,MAAM,CAAC;AACnE,eAAO,MAAM,sCAAsC,MAAM,CAAC;AAC1D,eAAO,MAAM,0CAA0C,MAAM,CAAC;AAC9D,eAAO,MAAM,yCAAyC,QAAY,CAAC;AACnE,eAAO,MAAM,kCAAkC,QAAyB,CAAC;AASzE,iBAAS,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhD;AAuCD,iBAAS,eAAe,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,GAAG,SAAS,CAUlF;AAsBD,0FAA0F;AAC1F,wBAAgB,4BAA4B,CAC3C,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,4BAA4B,GACnC,2BAA2B,GAAG,SAAS,CA4CzC;AA4FD,wBAAgB,sCAAsC,CACrD,OAAO,GAAE,uCAA4C,GACnD,4BAA4B,CAmB9B;AAED,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC","sourcesContent":["import type { JsonValue } from \"@agent-forge/plugin-sdk\";\nimport { projectPluginContextV1 } from \"@agent-forge/plugin-sdk\";\nimport {\n\ttype NodeWorkspaceFilesWriteAdapterOptionsV1,\n\tWORKSPACE_FILES_WRITE_HOST_ADAPTER_ID_V1,\n\tWORKSPACE_FILES_WRITE_HOST_ADAPTER_VERSION_V1,\n\ttype WorkspaceFilesWriteAdapterV1,\n\ttype WorkspaceFilesWriteModeV1,\n\ttype WorkspaceFilesWriteRequestV1,\n\ttype WorkspaceFilesWriteResultV1,\n} from \"./types.ts\";\n\nexport const WORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1 = 256;\nexport const WORKSPACE_FILES_WRITE_MAX_REF_CHARS_V1 = 256;\nexport const WORKSPACE_FILES_WRITE_MAX_VERSION_CHARS_V1 = 256;\nexport const WORKSPACE_FILES_WRITE_MAX_OUTPUT_BYTES_V1 = 64 * 1024;\nexport const WORKSPACE_FILES_WRITE_MAX_BYTES_V1 = 4 * 1024 * 1024 * 1024;\n\nconst OPAQUE_REF_V1 = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u;\nconst VERSION_TOKEN_V1 = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u;\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nfunction safeRef(value: unknown): value is string {\n\treturn typeof value === \"string\" && OPAQUE_REF_V1.test(value);\n}\n\nfunction safeVersionToken(value: unknown): value is string | undefined {\n\treturn value === undefined || (typeof value === \"string\" && VERSION_TOKEN_V1.test(value));\n}\n\nfunction validOperationId(value: unknown): value is string {\n\treturn (\n\t\ttypeof value === \"string\" &&\n\t\tvalue.trim() !== \"\" &&\n\t\tvalue.length <= WORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1 &&\n\t\t!/[\\u0000-\\u001f\\u007f]/u.test(value)\n\t);\n}\n\nfunction validMode(value: unknown): value is WorkspaceFilesWriteModeV1 {\n\treturn value === \"replace\" || value === \"patch\";\n}\n\nfunction error(\n\toperationId: string,\n\tfileRef: string,\n\tmode: WorkspaceFilesWriteModeV1,\n\tstatus: WorkspaceFilesWriteResultV1[\"status\"],\n\tcode: string,\n\tmessage: string,\n): WorkspaceFilesWriteResultV1 {\n\treturn {\n\t\tversion: 1,\n\t\toperationId,\n\t\tstatus,\n\t\tfileRef,\n\t\tmode,\n\t\tchanged: false,\n\t\tbytesWritten: 0,\n\t\terror: { version: 1, code, message },\n\t};\n}\n\nfunction validateRequest(request: WorkspaceFilesWriteRequestV1): string | undefined {\n\tif (request.version !== 1) return \"version must be 1\";\n\tif (!validOperationId(request.operationId)) return \"operationId is invalid\";\n\tif (!safeRef(request.fileRef)) return \"fileRef must be an opaque host handle\";\n\tif (!validMode(request.mode)) return \"mode must be replace or patch\";\n\tif (!safeRef(request.sourceArtifactRef)) return \"sourceArtifactRef must be an opaque artifact handle\";\n\tif (!safeVersionToken(request.expectedVersion)) return \"expectedVersion is invalid\";\n\tif (request.createIfMissing !== undefined && typeof request.createIfMissing !== \"boolean\")\n\t\treturn \"createIfMissing is invalid\";\n\treturn undefined;\n}\n\nfunction boundedError(value: unknown): WorkspaceFilesWriteResultV1[\"error\"] | undefined {\n\tif (!isRecord(value)) return undefined;\n\tif (\n\t\tvalue.version !== 1 ||\n\t\ttypeof value.code !== \"string\" ||\n\t\t!/^[a-z][a-z0-9_]{0,127}$/u.test(value.code) ||\n\t\ttypeof value.message !== \"string\" ||\n\t\tvalue.message.trim() === \"\" ||\n\t\tvalue.message.length > 512\n\t)\n\t\treturn undefined;\n\treturn { version: 1, code: value.code, message: value.message.slice(0, 512) };\n}\n\nfunction nonNegativeBytes(value: unknown): value is number {\n\treturn (\n\t\tNumber.isSafeInteger(value) && (value as number) >= 0 && (value as number) <= WORKSPACE_FILES_WRITE_MAX_BYTES_V1\n\t);\n}\n\n/** Projects host output down to status and bounded metadata; it never returns content. */\nexport function projectWorkspaceFilesWriteV1(\n\tvalue: unknown,\n\trequest: WorkspaceFilesWriteRequestV1,\n): WorkspaceFilesWriteResultV1 | undefined {\n\tif (!isRecord(value)) return undefined;\n\tif (\n\t\tvalue.version !== 1 ||\n\t\tvalue.operationId !== request.operationId ||\n\t\tvalue.fileRef !== request.fileRef ||\n\t\tvalue.mode !== request.mode ||\n\t\ttypeof value.status !== \"string\" ||\n\t\t![\"succeeded\", \"failed\", \"cancelled\", \"needs_user\", \"unsupported\"].includes(value.status) ||\n\t\ttypeof value.changed !== \"boolean\" ||\n\t\t!nonNegativeBytes(value.bytesWritten) ||\n\t\t(!safeRef(value.outputArtifactRef) && value.outputArtifactRef !== undefined) ||\n\t\t!safeVersionToken(value.versionToken) ||\n\t\t(value.committed !== undefined && typeof value.committed !== \"boolean\")\n\t)\n\t\treturn undefined;\n\tconst result: WorkspaceFilesWriteResultV1 = {\n\t\tversion: 1,\n\t\toperationId: request.operationId,\n\t\tstatus: value.status as WorkspaceFilesWriteResultV1[\"status\"],\n\t\tfileRef: request.fileRef,\n\t\tmode: request.mode,\n\t\tchanged: value.changed,\n\t\tbytesWritten: value.bytesWritten,\n\t\t...(value.committed === true ? { committed: true } : {}),\n\t\t...(value.outputArtifactRef === undefined ? {} : { outputArtifactRef: value.outputArtifactRef }),\n\t\t...(value.versionToken === undefined ? {} : { versionToken: value.versionToken }),\n\t\t...(value.error === undefined ? {} : { error: boundedError(value.error) }),\n\t};\n\tif (result.status !== \"succeeded\" && result.error === undefined) return undefined;\n\tif (result.status === \"succeeded\" && result.error !== undefined) return undefined;\n\tif (\n\t\tprojectPluginContextV1(\n\t\t\t{\n\t\t\t\tversion: 1,\n\t\t\t\toperationId: request.operationId,\n\t\t\t\titems: [result] as unknown as JsonValue[],\n\t\t\t\ttruncated: false,\n\t\t\t},\n\t\t\t{ maxOutputBytes: WORKSPACE_FILES_WRITE_MAX_OUTPUT_BYTES_V1, maxInlineItems: 1, maxCellChars: 512 },\n\t\t).status !== \"succeeded\"\n\t)\n\t\treturn undefined;\n\treturn result;\n}\n\nfunction timeoutMs(value: number | undefined): number {\n\tif (value === undefined) return 30_000;\n\tif (!Number.isSafeInteger(value) || value < 1 || value > 120_000) throw new Error(\"defaultTimeoutMs is invalid\");\n\treturn value;\n}\n\nasync function runHost(\n\tcallback: ((signal: AbortSignal) => Promise<unknown>) | undefined,\n\ttimeout: number,\n\trequest: WorkspaceFilesWriteRequestV1,\n\tsignal: AbortSignal | undefined,\n): Promise<WorkspaceFilesWriteResultV1> {\n\tif (callback === undefined)\n\t\treturn error(\n\t\t\trequest.operationId,\n\t\t\trequest.fileRef,\n\t\t\trequest.mode,\n\t\t\t\"unsupported\",\n\t\t\t\"workspace_files_write_unavailable\",\n\t\t\t\"No workspace file writer is bound\",\n\t\t);\n\tif (signal?.aborted)\n\t\treturn error(\n\t\t\trequest.operationId,\n\t\t\trequest.fileRef,\n\t\t\trequest.mode,\n\t\t\t\"cancelled\",\n\t\t\t\"cancelled\",\n\t\t\t\"Workspace write was cancelled\",\n\t\t);\n\tconst controller = new AbortController();\n\tlet stop: \"timeout\" | \"cancelled\" | undefined;\n\tlet timer: ReturnType<typeof setTimeout> | undefined;\n\tlet removeAbort: (() => void) | undefined;\n\tconst stopPromise = new Promise<void>((resolve) => {\n\t\tconst cancel = () => {\n\t\t\tstop ??= \"cancelled\";\n\t\t\tcontroller.abort();\n\t\t\tresolve();\n\t\t};\n\t\tif (signal !== undefined) {\n\t\t\tsignal.addEventListener(\"abort\", cancel, { once: true });\n\t\t\tremoveAbort = () => signal.removeEventListener(\"abort\", cancel);\n\t\t}\n\t\ttimer = setTimeout(() => {\n\t\t\tif (stop === undefined) {\n\t\t\t\tstop = \"timeout\";\n\t\t\t\tcontroller.abort();\n\t\t\t\tresolve();\n\t\t\t}\n\t\t}, timeout);\n\t});\n\tconst callbackPromise = callback(controller.signal).then(\n\t\t(value) => ({ kind: \"value\" as const, value }),\n\t\t() => ({ kind: \"failed\" as const }),\n\t);\n\ttry {\n\t\tconst outcome = await Promise.race([callbackPromise, stopPromise.then(() => ({ kind: \"stopped\" as const }))]);\n\t\tif (outcome.kind !== \"value\" || stop !== undefined) {\n\t\t\tconst failure = outcome.kind === \"failed\" && stop === undefined;\n\t\t\treturn error(\n\t\t\t\trequest.operationId,\n\t\t\t\trequest.fileRef,\n\t\t\t\trequest.mode,\n\t\t\t\tstop === \"cancelled\" ? \"cancelled\" : \"failed\",\n\t\t\t\tfailure ? \"adapter_failed\" : stop === \"cancelled\" ? \"cancelled\" : \"timeout\",\n\t\t\t\tfailure\n\t\t\t\t\t? \"Workspace writer failed\"\n\t\t\t\t\t: stop === \"cancelled\"\n\t\t\t\t\t\t? \"Workspace write was cancelled\"\n\t\t\t\t\t\t: \"Workspace write timed out\",\n\t\t\t);\n\t\t}\n\t\treturn (\n\t\t\tprojectWorkspaceFilesWriteV1(outcome.value, request) ??\n\t\t\terror(\n\t\t\t\trequest.operationId,\n\t\t\t\trequest.fileRef,\n\t\t\t\trequest.mode,\n\t\t\t\t\"failed\",\n\t\t\t\t\"adapter_failed\",\n\t\t\t\t\"Workspace writer returned an invalid result\",\n\t\t\t)\n\t\t);\n\t} finally {\n\t\tif (timer !== undefined) clearTimeout(timer);\n\t\tremoveAbort?.();\n\t}\n}\n\nexport function createNodeWorkspaceFilesWriteAdapterV1(\n\toptions: NodeWorkspaceFilesWriteAdapterOptionsV1 = {},\n): WorkspaceFilesWriteAdapterV1 {\n\tconst timeout = timeoutMs(options.defaultTimeoutMs);\n\treturn {\n\t\tadapterId: WORKSPACE_FILES_WRITE_HOST_ADAPTER_ID_V1,\n\t\tadapterVersion: WORKSPACE_FILES_WRITE_HOST_ADAPTER_VERSION_V1,\n\t\twrite: async (request, signal) => {\n\t\t\tconst invalid = validateRequest(request);\n\t\t\tif (invalid !== undefined)\n\t\t\t\treturn error(request.operationId, request.fileRef, request.mode, \"failed\", \"invalid_input\", invalid);\n\t\t\treturn runHost(\n\t\t\t\toptions.write === undefined\n\t\t\t\t\t? undefined\n\t\t\t\t\t: (hostSignal) => options.write?.(request, hostSignal) ?? Promise.resolve(undefined),\n\t\t\t\ttimeout,\n\t\t\t\trequest,\n\t\t\t\tsignal,\n\t\t\t);\n\t\t},\n\t};\n}\n\nexport { safeRef, validateRequest };\n"]}

package/dist/node-adapter.js

@@ -0,0 +1,184 @@
+import { projectPluginContextV1 } from "@agent-forge/plugin-sdk";
+import { WORKSPACE_FILES_WRITE_HOST_ADAPTER_ID_V1, WORKSPACE_FILES_WRITE_HOST_ADAPTER_VERSION_V1, } from "./types.js";
+export const WORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1 = 256;
+export const WORKSPACE_FILES_WRITE_MAX_REF_CHARS_V1 = 256;
+export const WORKSPACE_FILES_WRITE_MAX_VERSION_CHARS_V1 = 256;
+export const WORKSPACE_FILES_WRITE_MAX_OUTPUT_BYTES_V1 = 64 * 1024;
+export const WORKSPACE_FILES_WRITE_MAX_BYTES_V1 = 4 * 1024 * 1024 * 1024;
+const OPAQUE_REF_V1 = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u;
+const VERSION_TOKEN_V1 = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function safeRef(value) {
+    return typeof value === "string" && OPAQUE_REF_V1.test(value);
+}
+function safeVersionToken(value) {
+    return value === undefined || (typeof value === "string" && VERSION_TOKEN_V1.test(value));
+}
+function validOperationId(value) {
+    return (typeof value === "string" &&
+        value.trim() !== "" &&
+        value.length <= WORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1 &&
+        !/[\u0000-\u001f\u007f]/u.test(value));
+}
+function validMode(value) {
+    return value === "replace" || value === "patch";
+}
+function error(operationId, fileRef, mode, status, code, message) {
+    return {
+        version: 1,
+        operationId,
+        status,
+        fileRef,
+        mode,
+        changed: false,
+        bytesWritten: 0,
+        error: { version: 1, code, message },
+    };
+}
+function validateRequest(request) {
+    if (request.version !== 1)
+        return "version must be 1";
+    if (!validOperationId(request.operationId))
+        return "operationId is invalid";
+    if (!safeRef(request.fileRef))
+        return "fileRef must be an opaque host handle";
+    if (!validMode(request.mode))
+        return "mode must be replace or patch";
+    if (!safeRef(request.sourceArtifactRef))
+        return "sourceArtifactRef must be an opaque artifact handle";
+    if (!safeVersionToken(request.expectedVersion))
+        return "expectedVersion is invalid";
+    if (request.createIfMissing !== undefined && typeof request.createIfMissing !== "boolean")
+        return "createIfMissing is invalid";
+    return undefined;
+}
+function boundedError(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (value.version !== 1 ||
+        typeof value.code !== "string" ||
+        !/^[a-z][a-z0-9_]{0,127}$/u.test(value.code) ||
+        typeof value.message !== "string" ||
+        value.message.trim() === "" ||
+        value.message.length > 512)
+        return undefined;
+    return { version: 1, code: value.code, message: value.message.slice(0, 512) };
+}
+function nonNegativeBytes(value) {
+    return (Number.isSafeInteger(value) && value >= 0 && value <= WORKSPACE_FILES_WRITE_MAX_BYTES_V1);
+}
+/** Projects host output down to status and bounded metadata; it never returns content. */
+export function projectWorkspaceFilesWriteV1(value, request) {
+    if (!isRecord(value))
+        return undefined;
+    if (value.version !== 1 ||
+        value.operationId !== request.operationId ||
+        value.fileRef !== request.fileRef ||
+        value.mode !== request.mode ||
+        typeof value.status !== "string" ||
+        !["succeeded", "failed", "cancelled", "needs_user", "unsupported"].includes(value.status) ||
+        typeof value.changed !== "boolean" ||
+        !nonNegativeBytes(value.bytesWritten) ||
+        (!safeRef(value.outputArtifactRef) && value.outputArtifactRef !== undefined) ||
+        !safeVersionToken(value.versionToken) ||
+        (value.committed !== undefined && typeof value.committed !== "boolean"))
+        return undefined;
+    const result = {
+        version: 1,
+        operationId: request.operationId,
+        status: value.status,
+        fileRef: request.fileRef,
+        mode: request.mode,
+        changed: value.changed,
+        bytesWritten: value.bytesWritten,
+        ...(value.committed === true ? { committed: true } : {}),
+        ...(value.outputArtifactRef === undefined ? {} : { outputArtifactRef: value.outputArtifactRef }),
+        ...(value.versionToken === undefined ? {} : { versionToken: value.versionToken }),
+        ...(value.error === undefined ? {} : { error: boundedError(value.error) }),
+    };
+    if (result.status !== "succeeded" && result.error === undefined)
+        return undefined;
+    if (result.status === "succeeded" && result.error !== undefined)
+        return undefined;
+    if (projectPluginContextV1({
+        version: 1,
+        operationId: request.operationId,
+        items: [result],
+        truncated: false,
+    }, { maxOutputBytes: WORKSPACE_FILES_WRITE_MAX_OUTPUT_BYTES_V1, maxInlineItems: 1, maxCellChars: 512 }).status !== "succeeded")
+        return undefined;
+    return result;
+}
+function timeoutMs(value) {
+    if (value === undefined)
+        return 30_000;
+    if (!Number.isSafeInteger(value) || value < 1 || value > 120_000)
+        throw new Error("defaultTimeoutMs is invalid");
+    return value;
+}
+async function runHost(callback, timeout, request, signal) {
+    if (callback === undefined)
+        return error(request.operationId, request.fileRef, request.mode, "unsupported", "workspace_files_write_unavailable", "No workspace file writer is bound");
+    if (signal?.aborted)
+        return error(request.operationId, request.fileRef, request.mode, "cancelled", "cancelled", "Workspace write was cancelled");
+    const controller = new AbortController();
+    let stop;
+    let timer;
+    let removeAbort;
+    const stopPromise = new Promise((resolve) => {
+        const cancel = () => {
+            stop ??= "cancelled";
+            controller.abort();
+            resolve();
+        };
+        if (signal !== undefined) {
+            signal.addEventListener("abort", cancel, { once: true });
+            removeAbort = () => signal.removeEventListener("abort", cancel);
+        }
+        timer = setTimeout(() => {
+            if (stop === undefined) {
+                stop = "timeout";
+                controller.abort();
+                resolve();
+            }
+        }, timeout);
+    });
+    const callbackPromise = callback(controller.signal).then((value) => ({ kind: "value", value }), () => ({ kind: "failed" }));
+    try {
+        const outcome = await Promise.race([callbackPromise, stopPromise.then(() => ({ kind: "stopped" }))]);
+        if (outcome.kind !== "value" || stop !== undefined) {
+            const failure = outcome.kind === "failed" && stop === undefined;
+            return error(request.operationId, request.fileRef, request.mode, stop === "cancelled" ? "cancelled" : "failed", failure ? "adapter_failed" : stop === "cancelled" ? "cancelled" : "timeout", failure
+                ? "Workspace writer failed"
+                : stop === "cancelled"
+                    ? "Workspace write was cancelled"
+                    : "Workspace write timed out");
+        }
+        return (projectWorkspaceFilesWriteV1(outcome.value, request) ??
+            error(request.operationId, request.fileRef, request.mode, "failed", "adapter_failed", "Workspace writer returned an invalid result"));
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        removeAbort?.();
+    }
+}
+export function createNodeWorkspaceFilesWriteAdapterV1(options = {}) {
+    const timeout = timeoutMs(options.defaultTimeoutMs);
+    return {
+        adapterId: WORKSPACE_FILES_WRITE_HOST_ADAPTER_ID_V1,
+        adapterVersion: WORKSPACE_FILES_WRITE_HOST_ADAPTER_VERSION_V1,
+        write: async (request, signal) => {
+            const invalid = validateRequest(request);
+            if (invalid !== undefined)
+                return error(request.operationId, request.fileRef, request.mode, "failed", "invalid_input", invalid);
+            return runHost(options.write === undefined
+                ? undefined
+                : (hostSignal) => options.write?.(request, hostSignal) ?? Promise.resolve(undefined), timeout, request, signal);
+        },
+    };
+}
+export { safeRef, validateRequest };
+//# sourceMappingURL=node-adapter.js.map

package/dist/node-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-adapter.js","sourceRoot":"","sources":["../src/node-adapter.ts"],"names":[],"mappings":"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","sourcesContent":["import type { JsonValue } from \"@agent-forge/plugin-sdk\";\nimport { projectPluginContextV1 } from \"@agent-forge/plugin-sdk\";\nimport {\n\ttype NodeWorkspaceFilesWriteAdapterOptionsV1,\n\tWORKSPACE_FILES_WRITE_HOST_ADAPTER_ID_V1,\n\tWORKSPACE_FILES_WRITE_HOST_ADAPTER_VERSION_V1,\n\ttype WorkspaceFilesWriteAdapterV1,\n\ttype WorkspaceFilesWriteModeV1,\n\ttype WorkspaceFilesWriteRequestV1,\n\ttype WorkspaceFilesWriteResultV1,\n} from \"./types.ts\";\n\nexport const WORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1 = 256;\nexport const WORKSPACE_FILES_WRITE_MAX_REF_CHARS_V1 = 256;\nexport const WORKSPACE_FILES_WRITE_MAX_VERSION_CHARS_V1 = 256;\nexport const WORKSPACE_FILES_WRITE_MAX_OUTPUT_BYTES_V1 = 64 * 1024;\nexport const WORKSPACE_FILES_WRITE_MAX_BYTES_V1 = 4 * 1024 * 1024 * 1024;\n\nconst OPAQUE_REF_V1 = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u;\nconst VERSION_TOKEN_V1 = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u;\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nfunction safeRef(value: unknown): value is string {\n\treturn typeof value === \"string\" && OPAQUE_REF_V1.test(value);\n}\n\nfunction safeVersionToken(value: unknown): value is string | undefined {\n\treturn value === undefined || (typeof value === \"string\" && VERSION_TOKEN_V1.test(value));\n}\n\nfunction validOperationId(value: unknown): value is string {\n\treturn (\n\t\ttypeof value === \"string\" &&\n\t\tvalue.trim() !== \"\" &&\n\t\tvalue.length <= WORKSPACE_FILES_WRITE_MAX_OPERATION_ID_CHARS_V1 &&\n\t\t!/[\\u0000-\\u001f\\u007f]/u.test(value)\n\t);\n}\n\nfunction validMode(value: unknown): value is WorkspaceFilesWriteModeV1 {\n\treturn value === \"replace\" || value === \"patch\";\n}\n\nfunction error(\n\toperationId: string,\n\tfileRef: string,\n\tmode: WorkspaceFilesWriteModeV1,\n\tstatus: WorkspaceFilesWriteResultV1[\"status\"],\n\tcode: string,\n\tmessage: string,\n): WorkspaceFilesWriteResultV1 {\n\treturn {\n\t\tversion: 1,\n\t\toperationId,\n\t\tstatus,\n\t\tfileRef,\n\t\tmode,\n\t\tchanged: false,\n\t\tbytesWritten: 0,\n\t\terror: { version: 1, code, message },\n\t};\n}\n\nfunction validateRequest(request: WorkspaceFilesWriteRequestV1): string | undefined {\n\tif (request.version !== 1) return \"version must be 1\";\n\tif (!validOperationId(request.operationId)) return \"operationId is invalid\";\n\tif (!safeRef(request.fileRef)) return \"fileRef must be an opaque host handle\";\n\tif (!validMode(request.mode)) return \"mode must be replace or patch\";\n\tif (!safeRef(request.sourceArtifactRef)) return \"sourceArtifactRef must be an opaque artifact handle\";\n\tif (!safeVersionToken(request.expectedVersion)) return \"expectedVersion is invalid\";\n\tif (request.createIfMissing !== undefined && typeof request.createIfMissing !== \"boolean\")\n\t\treturn \"createIfMissing is invalid\";\n\treturn undefined;\n}\n\nfunction boundedError(value: unknown): WorkspaceFilesWriteResultV1[\"error\"] | undefined {\n\tif (!isRecord(value)) return undefined;\n\tif (\n\t\tvalue.version !== 1 ||\n\t\ttypeof value.code !== \"string\" ||\n\t\t!/^[a-z][a-z0-9_]{0,127}$/u.test(value.code) ||\n\t\ttypeof value.message !== \"string\" ||\n\t\tvalue.message.trim() === \"\" ||\n\t\tvalue.message.length > 512\n\t)\n\t\treturn undefined;\n\treturn { version: 1, code: value.code, message: value.message.slice(0, 512) };\n}\n\nfunction nonNegativeBytes(value: unknown): value is number {\n\treturn (\n\t\tNumber.isSafeInteger(value) && (value as number) >= 0 && (value as number) <= WORKSPACE_FILES_WRITE_MAX_BYTES_V1\n\t);\n}\n\n/** Projects host output down to status and bounded metadata; it never returns content. */\nexport function projectWorkspaceFilesWriteV1(\n\tvalue: unknown,\n\trequest: WorkspaceFilesWriteRequestV1,\n): WorkspaceFilesWriteResultV1 | undefined {\n\tif (!isRecord(value)) return undefined;\n\tif (\n\t\tvalue.version !== 1 ||\n\t\tvalue.operationId !== request.operationId ||\n\t\tvalue.fileRef !== request.fileRef ||\n\t\tvalue.mode !== request.mode ||\n\t\ttypeof value.status !== \"string\" ||\n\t\t![\"succeeded\", \"failed\", \"cancelled\", \"needs_user\", \"unsupported\"].includes(value.status) ||\n\t\ttypeof value.changed !== \"boolean\" ||\n\t\t!nonNegativeBytes(value.bytesWritten) ||\n\t\t(!safeRef(value.outputArtifactRef) && value.outputArtifactRef !== undefined) ||\n\t\t!safeVersionToken(value.versionToken) ||\n\t\t(value.committed !== undefined && typeof value.committed !== \"boolean\")\n\t)\n\t\treturn undefined;\n\tconst result: WorkspaceFilesWriteResultV1 = {\n\t\tversion: 1,\n\t\toperationId: request.operationId,\n\t\tstatus: value.status as WorkspaceFilesWriteResultV1[\"status\"],\n\t\tfileRef: request.fileRef,\n\t\tmode: request.mode,\n\t\tchanged: value.changed,\n\t\tbytesWritten: value.bytesWritten,\n\t\t...(value.committed === true ? { committed: true } : {}),\n\t\t...(value.outputArtifactRef === undefined ? {} : { outputArtifactRef: value.outputArtifactRef }),\n\t\t...(value.versionToken === undefined ? {} : { versionToken: value.versionToken }),\n\t\t...(value.error === undefined ? {} : { error: boundedError(value.error) }),\n\t};\n\tif (result.status !== \"succeeded\" && result.error === undefined) return undefined;\n\tif (result.status === \"succeeded\" && result.error !== undefined) return undefined;\n\tif (\n\t\tprojectPluginContextV1(\n\t\t\t{\n\t\t\t\tversion: 1,\n\t\t\t\toperationId: request.operationId,\n\t\t\t\titems: [result] as unknown as JsonValue[],\n\t\t\t\ttruncated: false,\n\t\t\t},\n\t\t\t{ maxOutputBytes: WORKSPACE_FILES_WRITE_MAX_OUTPUT_BYTES_V1, maxInlineItems: 1, maxCellChars: 512 },\n\t\t).status !== \"succeeded\"\n\t)\n\t\treturn undefined;\n\treturn result;\n}\n\nfunction timeoutMs(value: number | undefined): number {\n\tif (value === undefined) return 30_000;\n\tif (!Number.isSafeInteger(value) || value < 1 || value > 120_000) throw new Error(\"defaultTimeoutMs is invalid\");\n\treturn value;\n}\n\nasync function runHost(\n\tcallback: ((signal: AbortSignal) => Promise<unknown>) | undefined,\n\ttimeout: number,\n\trequest: WorkspaceFilesWriteRequestV1,\n\tsignal: AbortSignal | undefined,\n): Promise<WorkspaceFilesWriteResultV1> {\n\tif (callback === undefined)\n\t\treturn error(\n\t\t\trequest.operationId,\n\t\t\trequest.fileRef,\n\t\t\trequest.mode,\n\t\t\t\"unsupported\",\n\t\t\t\"workspace_files_write_unavailable\",\n\t\t\t\"No workspace file writer is bound\",\n\t\t);\n\tif (signal?.aborted)\n\t\treturn error(\n\t\t\trequest.operationId,\n\t\t\trequest.fileRef,\n\t\t\trequest.mode,\n\t\t\t\"cancelled\",\n\t\t\t\"cancelled\",\n\t\t\t\"Workspace write was cancelled\",\n\t\t);\n\tconst controller = new AbortController();\n\tlet stop: \"timeout\" | \"cancelled\" | undefined;\n\tlet timer: ReturnType<typeof setTimeout> | undefined;\n\tlet removeAbort: (() => void) | undefined;\n\tconst stopPromise = new Promise<void>((resolve) => {\n\t\tconst cancel = () => {\n\t\t\tstop ??= \"cancelled\";\n\t\t\tcontroller.abort();\n\t\t\tresolve();\n\t\t};\n\t\tif (signal !== undefined) {\n\t\t\tsignal.addEventListener(\"abort\", cancel, { once: true });\n\t\t\tremoveAbort = () => signal.removeEventListener(\"abort\", cancel);\n\t\t}\n\t\ttimer = setTimeout(() => {\n\t\t\tif (stop === undefined) {\n\t\t\t\tstop = \"timeout\";\n\t\t\t\tcontroller.abort();\n\t\t\t\tresolve();\n\t\t\t}\n\t\t}, timeout);\n\t});\n\tconst callbackPromise = callback(controller.signal).then(\n\t\t(value) => ({ kind: \"value\" as const, value }),\n\t\t() => ({ kind: \"failed\" as const }),\n\t);\n\ttry {\n\t\tconst outcome = await Promise.race([callbackPromise, stopPromise.then(() => ({ kind: \"stopped\" as const }))]);\n\t\tif (outcome.kind !== \"value\" || stop !== undefined) {\n\t\t\tconst failure = outcome.kind === \"failed\" && stop === undefined;\n\t\t\treturn error(\n\t\t\t\trequest.operationId,\n\t\t\t\trequest.fileRef,\n\t\t\t\trequest.mode,\n\t\t\t\tstop === \"cancelled\" ? \"cancelled\" : \"failed\",\n\t\t\t\tfailure ? \"adapter_failed\" : stop === \"cancelled\" ? \"cancelled\" : \"timeout\",\n\t\t\t\tfailure\n\t\t\t\t\t? \"Workspace writer failed\"\n\t\t\t\t\t: stop === \"cancelled\"\n\t\t\t\t\t\t? \"Workspace write was cancelled\"\n\t\t\t\t\t\t: \"Workspace write timed out\",\n\t\t\t);\n\t\t}\n\t\treturn (\n\t\t\tprojectWorkspaceFilesWriteV1(outcome.value, request) ??\n\t\t\terror(\n\t\t\t\trequest.operationId,\n\t\t\t\trequest.fileRef,\n\t\t\t\trequest.mode,\n\t\t\t\t\"failed\",\n\t\t\t\t\"adapter_failed\",\n\t\t\t\t\"Workspace writer returned an invalid result\",\n\t\t\t)\n\t\t);\n\t} finally {\n\t\tif (timer !== undefined) clearTimeout(timer);\n\t\tremoveAbort?.();\n\t}\n}\n\nexport function createNodeWorkspaceFilesWriteAdapterV1(\n\toptions: NodeWorkspaceFilesWriteAdapterOptionsV1 = {},\n): WorkspaceFilesWriteAdapterV1 {\n\tconst timeout = timeoutMs(options.defaultTimeoutMs);\n\treturn {\n\t\tadapterId: WORKSPACE_FILES_WRITE_HOST_ADAPTER_ID_V1,\n\t\tadapterVersion: WORKSPACE_FILES_WRITE_HOST_ADAPTER_VERSION_V1,\n\t\twrite: async (request, signal) => {\n\t\t\tconst invalid = validateRequest(request);\n\t\t\tif (invalid !== undefined)\n\t\t\t\treturn error(request.operationId, request.fileRef, request.mode, \"failed\", \"invalid_input\", invalid);\n\t\t\treturn runHost(\n\t\t\t\toptions.write === undefined\n\t\t\t\t\t? undefined\n\t\t\t\t\t: (hostSignal) => options.write?.(request, hostSignal) ?? Promise.resolve(undefined),\n\t\t\t\ttimeout,\n\t\t\t\trequest,\n\t\t\t\tsignal,\n\t\t\t);\n\t\t},\n\t};\n}\n\nexport { safeRef, validateRequest };\n"]}

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+import type { PluginErrorV1, PluginResultStatusV1 } from "@agent-forge/plugin-sdk";
+export declare const WORKSPACE_FILES_WRITE_PLUGIN_ID_V1: "agent-forge.plugin.workspace-files-write";
+export declare const WORKSPACE_FILES_WRITE_CAPABILITY_VERSION_V1: 1;
+export declare const WORKSPACE_FILES_WRITE_HOST_ADAPTER_ID_V1: "node-workspace-files-write";
+export declare const WORKSPACE_FILES_WRITE_HOST_ADAPTER_VERSION_V1: "1.0.0";
+export type WorkspaceFilesWriteModeV1 = "replace" | "patch";
+/**
+ * A write request carries only opaque references. The host resolves the source
+ * artifact and file handle; bytes and local paths never cross the capability
+ * boundary or enter the model context.
+ */
+export interface WorkspaceFilesWriteRequestV1 {
+    readonly version: 1;
+    readonly operationId: string;
+    readonly fileRef: string;
+    readonly mode: WorkspaceFilesWriteModeV1;
+    readonly sourceArtifactRef: string;
+    readonly expectedVersion?: string;
+    readonly createIfMissing?: boolean;
+}
+export interface WorkspaceFilesWriteResultV1 {
+    readonly version: 1;
+    readonly operationId: string;
+    readonly status: PluginResultStatusV1;
+    readonly fileRef: string;
+    readonly mode: WorkspaceFilesWriteModeV1;
+    readonly changed: boolean;
+    readonly bytesWritten: number;
+    /**
+     * True only when the host already renamed the new bytes onto the target and a
+     * later step (artifact record or cancellation) failed; it keeps a failed or
+     * cancelled result distinguishable from a failure that never touched the disk.
+     */
+    readonly committed?: boolean;
+    readonly outputArtifactRef?: string;
+    readonly versionToken?: string;
+    readonly error?: PluginErrorV1;
+}
+export interface WorkspaceFilesWriteAdapterV1 {
+    readonly adapterId: string;
+    readonly adapterVersion: string;
+    readonly write: (request: WorkspaceFilesWriteRequestV1, signal?: AbortSignal) => Promise<WorkspaceFilesWriteResultV1>;
+}
+export interface NodeWorkspaceFilesWriteAdapterOptionsV1 {
+    /** Host-owned resolver and writer; the model never supplies a local path. */
+    readonly write?: (request: WorkspaceFilesWriteRequestV1, signal: AbortSignal) => Promise<unknown>;
+    readonly defaultTimeoutMs?: number;
+}
+export interface WorkspaceFilesPatchOperationV1 {
+    readonly start: number;
+    readonly end: number;
+    readonly replacement: string;
+}
+export interface WorkspaceFilesPatchDocumentV1 {
+    readonly version: 1;
+    readonly operations: readonly WorkspaceFilesPatchOperationV1[];
+}
+/** Host-only resolver: it may return a local path, but that path never enters a model-facing DTO. */
+export interface NodeWorkspaceFilesWriteHostOptionsV1 {
+    readonly root: string;
+    readonly resolveFileRef: (fileRef: string, signal: AbortSignal) => Promise<string> | string;
+    /** Optional host file reader seam for virtual filesystems and deterministic tests. */
+    readonly readWorkspaceFile?: (path: string, signal: AbortSignal) => Promise<Uint8Array>;
+    readonly readArtifact: (artifactRef: string, signal: AbortSignal) => Promise<Uint8Array>;
+    readonly writeArtifact?: (input: {
+        readonly operationId: string;
+        readonly fileRef: string;
+        readonly bytes: Uint8Array;
+    }, signal: AbortSignal) => Promise<{
+        readonly artifactRef: string;
+    }>;
+    readonly defaultTimeoutMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAEnF,eAAO,MAAM,kCAAkC,4CAAsD,CAAC;AACtG,eAAO,MAAM,2CAA2C,GAAa,CAAC;AACtE,eAAO,MAAM,wCAAwC,8BAAwC,CAAC;AAC9F,eAAO,MAAM,6CAA6C,SAAmB,CAAC;AAE9E,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,OAAO,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,2BAA2B;IAC3C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,CACf,OAAO,EAAE,4BAA4B,EACrC,MAAM,CAAC,EAAE,WAAW,KAChB,OAAO,CAAC,2BAA2B,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,uCAAuC;IACvD,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,4BAA4B,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClG,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,8BAA8B;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,6BAA6B;IAC7C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,SAAS,8BAA8B,EAAE,CAAC;CAC/D;AAED,qGAAqG;AACrG,MAAM,WAAW,oCAAoC;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IAC5F,sFAAsF;IACtF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IACxF,QAAQ,CAAC,YAAY,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IACzF,QAAQ,CAAC,aAAa,CAAC,EAAE,CACxB,KAAK,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;KAAE,EAC7F,MAAM,EAAE,WAAW,KACf,OAAO,CAAC;QAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACnC","sourcesContent":["import type { PluginErrorV1, PluginResultStatusV1 } from \"@agent-forge/plugin-sdk\";\n\nexport const WORKSPACE_FILES_WRITE_PLUGIN_ID_V1 = \"agent-forge.plugin.workspace-files-write\" as const;\nexport const WORKSPACE_FILES_WRITE_CAPABILITY_VERSION_V1 = 1 as const;\nexport const WORKSPACE_FILES_WRITE_HOST_ADAPTER_ID_V1 = \"node-workspace-files-write\" as const;\nexport const WORKSPACE_FILES_WRITE_HOST_ADAPTER_VERSION_V1 = \"1.0.0\" as const;\n\nexport type WorkspaceFilesWriteModeV1 = \"replace\" | \"patch\";\n\n/**\n * A write request carries only opaque references. The host resolves the source\n * artifact and file handle; bytes and local paths never cross the capability\n * boundary or enter the model context.\n */\nexport interface WorkspaceFilesWriteRequestV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\treadonly fileRef: string;\n\treadonly mode: WorkspaceFilesWriteModeV1;\n\treadonly sourceArtifactRef: string;\n\treadonly expectedVersion?: string;\n\treadonly createIfMissing?: boolean;\n}\n\nexport interface WorkspaceFilesWriteResultV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\treadonly status: PluginResultStatusV1;\n\treadonly fileRef: string;\n\treadonly mode: WorkspaceFilesWriteModeV1;\n\treadonly changed: boolean;\n\treadonly bytesWritten: number;\n\t/**\n\t * True only when the host already renamed the new bytes onto the target and a\n\t * later step (artifact record or cancellation) failed; it keeps a failed or\n\t * cancelled result distinguishable from a failure that never touched the disk.\n\t */\n\treadonly committed?: boolean;\n\treadonly outputArtifactRef?: string;\n\treadonly versionToken?: string;\n\treadonly error?: PluginErrorV1;\n}\n\nexport interface WorkspaceFilesWriteAdapterV1 {\n\treadonly adapterId: string;\n\treadonly adapterVersion: string;\n\treadonly write: (\n\t\trequest: WorkspaceFilesWriteRequestV1,\n\t\tsignal?: AbortSignal,\n\t) => Promise<WorkspaceFilesWriteResultV1>;\n}\n\nexport interface NodeWorkspaceFilesWriteAdapterOptionsV1 {\n\t/** Host-owned resolver and writer; the model never supplies a local path. */\n\treadonly write?: (request: WorkspaceFilesWriteRequestV1, signal: AbortSignal) => Promise<unknown>;\n\treadonly defaultTimeoutMs?: number;\n}\n\nexport interface WorkspaceFilesPatchOperationV1 {\n\treadonly start: number;\n\treadonly end: number;\n\treadonly replacement: string;\n}\n\nexport interface WorkspaceFilesPatchDocumentV1 {\n\treadonly version: 1;\n\treadonly operations: readonly WorkspaceFilesPatchOperationV1[];\n}\n\n/** Host-only resolver: it may return a local path, but that path never enters a model-facing DTO. */\nexport interface NodeWorkspaceFilesWriteHostOptionsV1 {\n\treadonly root: string;\n\treadonly resolveFileRef: (fileRef: string, signal: AbortSignal) => Promise<string> | string;\n\t/** Optional host file reader seam for virtual filesystems and deterministic tests. */\n\treadonly readWorkspaceFile?: (path: string, signal: AbortSignal) => Promise<Uint8Array>;\n\treadonly readArtifact: (artifactRef: string, signal: AbortSignal) => Promise<Uint8Array>;\n\treadonly writeArtifact?: (\n\t\tinput: { readonly operationId: string; readonly fileRef: string; readonly bytes: Uint8Array },\n\t\tsignal: AbortSignal,\n\t) => Promise<{ readonly artifactRef: string }>;\n\treadonly defaultTimeoutMs?: number;\n}\n"]}

package/dist/types.js

@@ -0,0 +1,5 @@
+export const WORKSPACE_FILES_WRITE_PLUGIN_ID_V1 = "agent-forge.plugin.workspace-files-write";
+export const WORKSPACE_FILES_WRITE_CAPABILITY_VERSION_V1 = 1;
+export const WORKSPACE_FILES_WRITE_HOST_ADAPTER_ID_V1 = "node-workspace-files-write";
+export const WORKSPACE_FILES_WRITE_HOST_ADAPTER_VERSION_V1 = "1.0.0";
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,kCAAkC,GAAG,0CAAmD,CAAC;AACtG,MAAM,CAAC,MAAM,2CAA2C,GAAG,CAAU,CAAC;AACtE,MAAM,CAAC,MAAM,wCAAwC,GAAG,4BAAqC,CAAC;AAC9F,MAAM,CAAC,MAAM,6CAA6C,GAAG,OAAgB,CAAC","sourcesContent":["import type { PluginErrorV1, PluginResultStatusV1 } from \"@agent-forge/plugin-sdk\";\n\nexport const WORKSPACE_FILES_WRITE_PLUGIN_ID_V1 = \"agent-forge.plugin.workspace-files-write\" as const;\nexport const WORKSPACE_FILES_WRITE_CAPABILITY_VERSION_V1 = 1 as const;\nexport const WORKSPACE_FILES_WRITE_HOST_ADAPTER_ID_V1 = \"node-workspace-files-write\" as const;\nexport const WORKSPACE_FILES_WRITE_HOST_ADAPTER_VERSION_V1 = \"1.0.0\" as const;\n\nexport type WorkspaceFilesWriteModeV1 = \"replace\" | \"patch\";\n\n/**\n * A write request carries only opaque references. The host resolves the source\n * artifact and file handle; bytes and local paths never cross the capability\n * boundary or enter the model context.\n */\nexport interface WorkspaceFilesWriteRequestV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\treadonly fileRef: string;\n\treadonly mode: WorkspaceFilesWriteModeV1;\n\treadonly sourceArtifactRef: string;\n\treadonly expectedVersion?: string;\n\treadonly createIfMissing?: boolean;\n}\n\nexport interface WorkspaceFilesWriteResultV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\treadonly status: PluginResultStatusV1;\n\treadonly fileRef: string;\n\treadonly mode: WorkspaceFilesWriteModeV1;\n\treadonly changed: boolean;\n\treadonly bytesWritten: number;\n\t/**\n\t * True only when the host already renamed the new bytes onto the target and a\n\t * later step (artifact record or cancellation) failed; it keeps a failed or\n\t * cancelled result distinguishable from a failure that never touched the disk.\n\t */\n\treadonly committed?: boolean;\n\treadonly outputArtifactRef?: string;\n\treadonly versionToken?: string;\n\treadonly error?: PluginErrorV1;\n}\n\nexport interface WorkspaceFilesWriteAdapterV1 {\n\treadonly adapterId: string;\n\treadonly adapterVersion: string;\n\treadonly write: (\n\t\trequest: WorkspaceFilesWriteRequestV1,\n\t\tsignal?: AbortSignal,\n\t) => Promise<WorkspaceFilesWriteResultV1>;\n}\n\nexport interface NodeWorkspaceFilesWriteAdapterOptionsV1 {\n\t/** Host-owned resolver and writer; the model never supplies a local path. */\n\treadonly write?: (request: WorkspaceFilesWriteRequestV1, signal: AbortSignal) => Promise<unknown>;\n\treadonly defaultTimeoutMs?: number;\n}\n\nexport interface WorkspaceFilesPatchOperationV1 {\n\treadonly start: number;\n\treadonly end: number;\n\treadonly replacement: string;\n}\n\nexport interface WorkspaceFilesPatchDocumentV1 {\n\treadonly version: 1;\n\treadonly operations: readonly WorkspaceFilesPatchOperationV1[];\n}\n\n/** Host-only resolver: it may return a local path, but that path never enters a model-facing DTO. */\nexport interface NodeWorkspaceFilesWriteHostOptionsV1 {\n\treadonly root: string;\n\treadonly resolveFileRef: (fileRef: string, signal: AbortSignal) => Promise<string> | string;\n\t/** Optional host file reader seam for virtual filesystems and deterministic tests. */\n\treadonly readWorkspaceFile?: (path: string, signal: AbortSignal) => Promise<Uint8Array>;\n\treadonly readArtifact: (artifactRef: string, signal: AbortSignal) => Promise<Uint8Array>;\n\treadonly writeArtifact?: (\n\t\tinput: { readonly operationId: string; readonly fileRef: string; readonly bytes: Uint8Array },\n\t\tsignal: AbortSignal,\n\t) => Promise<{ readonly artifactRef: string }>;\n\treadonly defaultTimeoutMs?: number;\n}\n"]}

package/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@ai-agent-forge/plugin-workspace-files-write",
+	"version": "0.85.0",
+	"description": "Workspace file write capability plugin for Agent Forge (full-control workspace_write tool with atomic replace/patch)",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"agent-forge.json",
+		"plugin.json",
+		"README.md"
+	],
+	"scripts": {
+		"clean": "shx rm -rf dist",
+		"build": "tsgo -p tsconfig.build.json",
+		"test": "vitest --run",
+		"prepublishOnly": "npm run clean && npm run build"
+	},
+	"keywords": [
+		"agent-forge",
+		"plugin",
+		"workspace",
+		"write"
+	],
+	"author": "Agent Forge contributors",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/agent-forge/agent-forge.git",
+		"directory": "plugins/workspace-files-write"
+	},
+	"bugs": {
+		"url": "https://github.com/agent-forge/agent-forge/issues"
+	},
+	"homepage": "https://github.com/agent-forge/agent-forge#readme",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"dependencies": {
+		"@agent-forge/plugin-sdk": "^0.85.0",
+		"typebox": "1.3.27"
+	},
+	"devDependencies": {
+		"@agent-forge/agent-forge": "^0.85.0",
+		"shx": "0.4.0",
+		"vitest": "4.1.9"
+	}
+}

package/plugin.json

@@ -0,0 +1,9 @@
+{
+	"id": "agent-forge.plugin.workspace-files-write",
+	"version": "0.84.4",
+	"apiVersion": "1-draft",
+	"entry": "./dist/entry.js",
+	"hostVersion": ">=0.84.4",
+	"requiredCapabilities": ["tools"],
+	"provides": [{ "id": "workspace.files.write", "version": 1, "kind": "contribution" }]
+}