@relayflows/sdk 2.0.44 → 2.0.46

package/dist/flow-tool-manifest.js

@@ -0,0 +1,79 @@
+import { canonicalize } from './canonical.js';
+import { sha256 } from './bundle.js';
+import { snapshotJsonValue } from './json-value.js';
+import { FLOW_TOOL_LIMITS, FLOW_TOOL_SCHEMA_DIALECT, flowToolSchema, compileFlowToolSchema } from './flow-tool-schema.js';
+const FIELDS = ['name', 'description', 'flow', 'inputSchema', 'resultSchema'];
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+function record(value, fields, at) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError(`${at}: expected an object`);
+    if (Object.keys(value).some(key => !fields.includes(key)) || fields.some(key => !Object.hasOwn(value, key))) {
+        // Unknown field names may themselves be sensitive caller data; do not echo them.
+        throw new TypeError(`${at}: missing or unknown fields`);
+    }
+    return value;
+}
+function declaration(value) {
+    const data = record(snapshotJsonValue(value, 'flow tool', FLOW_TOOL_LIMITS), FIELDS, 'flow tool');
+    if (typeof data.name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_-]{0,63}$/.test(data.name)) {
+        throw new TypeError('flow tool.name: expected a portable tool name (1–64 ASCII characters)');
+    }
+    if (typeof data.description !== 'string' || !data.description.trim() || data.description.length > 4096) {
+        throw new TypeError('flow tool.description: expected 1–4096 characters of operator-authored description');
+    }
+    const flow = record(data.flow, ['name', 'version', 'digest'], 'flow tool.flow');
+    if (typeof flow.name !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(flow.name)) {
+        throw new TypeError('flow tool.flow.name: expected a safe flow name');
+    }
+    if (typeof flow.version !== 'string' || flow.version.length > 128 || !VERSION.test(flow.version)
+        || flow.version.split('+')[0].split('-').slice(1).join('-').split('.').some(id => /^0\d+$/.test(id))) {
+        throw new TypeError('flow tool.flow.version: expected a semantic version');
+    }
+    if (typeof flow.digest !== 'string' || !DIGEST.test(flow.digest))
+        throw new TypeError('flow tool.flow.digest: expected sha256 and 64 lowercase hex digits');
+    return Object.freeze({
+        name: data.name, description: data.description,
+        flow: Object.freeze({ name: flow.name, version: flow.version, digest: flow.digest }),
+        inputSchema: flowToolSchema(data.inputSchema, 'flow tool.inputSchema'),
+        resultSchema: flowToolSchema(data.resultSchema, 'flow tool.resultSchema'),
+    });
+}
+/** Explicit runtime contract; TypeScript generics are never treated as schemas. */
+export function createFlowToolManifest(value) {
+    const content = Object.freeze({ manifestVersion: 1, schemaDialect: FLOW_TOOL_SCHEMA_DIALECT, ...declaration(value) });
+    return snapshotJsonValue({ ...content, digest: `sha256:${sha256(canonicalize(content))}` }, 'flow tool manifest', FLOW_TOOL_LIMITS);
+}
+/** Verify untrusted JSON and optionally bind it to a caller-trusted catalog digest. */
+export function parseFlowToolManifest(value, expectedDigest) {
+    const data = record(snapshotJsonValue(value, 'flow tool manifest', FLOW_TOOL_LIMITS), [...FIELDS, 'manifestVersion', 'schemaDialect', 'digest'], 'flow tool manifest');
+    if (data.manifestVersion !== 1 || data.schemaDialect !== FLOW_TOOL_SCHEMA_DIALECT) {
+        throw new TypeError('flow tool manifest: unsupported manifest version or schema dialect');
+    }
+    // Identity verification must never trim, case-fold or otherwise normalize metadata.
+    const parsed = createFlowToolManifest(Object.fromEntries(FIELDS.map(key => [key, data[key]])));
+    if (data.digest !== parsed.digest || (expectedDigest !== undefined && parsed.digest !== expectedDigest)) {
+        throw new TypeError('flow tool manifest: digest mismatch');
+    }
+    return parsed;
+}
+export function canonicalFlowToolManifest(value) {
+    return canonicalize(parseFlowToolManifest(value));
+}
+function validate(value, schema, at) {
+    const snapshot = snapshotJsonValue(value, at, FLOW_TOOL_LIMITS);
+    const validator = compileFlowToolSchema(schema);
+    if (!validator(snapshot)) {
+        // Report only the keyword: instance paths can contain sensitive caller keys.
+        throw new TypeError(`${at}: schema validation failed (${validator.errors?.[0]?.keyword ?? 'invalid'})`);
+    }
+    return snapshot;
+}
+export function validateFlowToolInput(manifest, input) {
+    return validate(input, parseFlowToolManifest(manifest).inputSchema, 'flow tool input');
+}
+/** Validates structure only, not business truth or successful execution. */
+export function validateFlowToolResult(manifest, result) {
+    return validate(result, parseFlowToolManifest(manifest).resultSchema, 'flow tool result');
+}
+//# sourceMappingURL=flow-tool-manifest.js.map

package/dist/flow-tool-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-tool-manifest.js","sourceRoot":"","sources":["../src/flow-tool-manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAkB,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAmB1H,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,cAAc,CAAC,CAAC;AAC9E,MAAM,MAAM,GAAG,uBAAuB,CAAC;AACvC,MAAM,OAAO,GAAG,2HAA2H,CAAC;AAE5I,SAAS,MAAM,CAAC,KAAgB,EAAE,MAAyB,EAAE,EAAU;IACrE,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,sBAAsB,CAAC,CAAC;IAC1H,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;QAC5G,iFAAiF;QACjF,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,6BAA6B,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,MAAM,IAAI,GAAG,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,gBAAgB,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAClG,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,gCAAgC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACvF,MAAM,IAAI,SAAS,CAAC,uEAAuE,CAAC,CAAC;IAC/F,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;QACvG,MAAM,IAAI,SAAS,CAAC,oFAAoF,CAAC,CAAC;IAC5G,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAK,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,gBAAgB,CAAC,CAAC;IACjF,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,oCAAoC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3F,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;WAC3F,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QACxG,MAAM,IAAI,SAAS,CAAC,qDAAqD,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,oEAAoE,CAAC,CAAC;IAC5J,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW;QAC9C,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAwB,EAAE,CAAC;QACtG,WAAW,EAAE,cAAc,CAAC,IAAI,CAAC,WAAW,EAAE,uBAAuB,CAAC;QACtE,YAAY,EAAE,cAAc,CAAC,IAAI,CAAC,YAAY,EAAE,wBAAwB,CAAC;KAC1E,CAAC,CAAC;AACL,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,sBAAsB,CAAC,KAA4B;IACjE,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,CAAU,EAAE,aAAa,EAAE,wBAAwB,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC/H,OAAO,iBAAiB,CAAC,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,UAAU,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EACxF,oBAAoB,EAAE,gBAAgB,CAAkC,CAAC;AAC7E,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,qBAAqB,CAAC,KAAc,EAAE,cAA+B;IACnF,MAAM,IAAI,GAAG,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,CAAC,EAClF,CAAC,GAAG,MAAM,EAAE,iBAAiB,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,oBAAoB,CAAC,CAAC;IACnF,IAAI,IAAI,CAAC,eAAe,KAAK,CAAC,IAAI,IAAI,CAAC,aAAa,KAAK,wBAAwB,EAAE,CAAC;QAClF,MAAM,IAAI,SAAS,CAAC,oEAAoE,CAAC,CAAC;IAC5F,CAAC;IACD,oFAAoF;IACpF,MAAM,MAAM,GAAG,sBAAsB,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAqC,CAAC,CAAC;IACnI,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,IAAI,CAAC,cAAc,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,cAAc,CAAC,EAAE,CAAC;QACxG,MAAM,IAAI,SAAS,CAAC,qCAAqC,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAAyB;IACjE,OAAO,YAAY,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc,EAAE,MAA4B,EAAE,EAAU;IACxE,MAAM,QAAQ,GAAG,iBAAiB,CAAC,KAAK,EAAE,EAAE,EAAE,gBAAgB,CAAC,CAAC;IAChE,MAAM,SAAS,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAChD,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,6EAA6E;QAC7E,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,+BAA+B,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,SAAS,GAAG,CAAC,CAAC;IAC1G,CAAC;IACD,OAAO,QAAkD,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,QAA4B,EAAE,KAAc;IAChF,OAAO,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC;AACzF,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,sBAAsB,CAAC,QAA4B,EAAE,MAAe;IAClF,OAAO,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC,YAAY,EAAE,kBAAkB,CAAC,CAAC;AAC5F,CAAC"}

package/dist/flow-tool-schema.d.ts

@@ -0,0 +1,15 @@
+export declare const FLOW_TOOL_SCHEMA_DIALECT: "https://json-schema.org/draft/2020-12/schema";
+export type FlowToolJson = null | boolean | number | string | readonly FlowToolJson[] | {
+    readonly [key: string]: FlowToolJson;
+};
+export type FlowToolObjectSchema = Readonly<Record<string, FlowToolJson>> & {
+    readonly type: 'object';
+};
+export declare const FLOW_TOOL_LIMITS: Readonly<{
+    maxDepth: 64;
+    maxNodes: 4096;
+    maxBytes: 262144;
+}>;
+export declare function compileFlowToolSchema(schema: FlowToolObjectSchema): import("ajv").ValidateFunction<unknown>;
+export declare function flowToolSchema(value: unknown, at: string): FlowToolObjectSchema;
+//# sourceMappingURL=flow-tool-schema.d.ts.map

package/dist/flow-tool-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-tool-schema.d.ts","sourceRoot":"","sources":["../src/flow-tool-schema.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,wBAAwB,EAAG,8CAAuD,CAAC;AAChG,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,YAAY,EAAE,GACjF;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAAA;CAAE,CAAC;AAC7C,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AACxG,eAAO,MAAM,gBAAgB;;;;EAAoE,CAAC;AAqClG,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,oBAAoB,2CAMjE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,oBAAoB,CAY/E"}

package/dist/flow-tool-schema.js

@@ -0,0 +1,70 @@
+import Ajv2020 from 'ajv/dist/2020.js';
+import { jsonSchemaBoundError } from './json-schema-bound.js';
+import { snapshotJsonValue } from './json-value.js';
+export const FLOW_TOOL_SCHEMA_DIALECT = 'https://json-schema.org/draft/2020-12/schema';
+export const FLOW_TOOL_LIMITS = Object.freeze({ maxDepth: 64, maxNodes: 4096, maxBytes: 262144 });
+// A deliberately explicit portable v1 profile, not silently ignored JSON Schema.
+const KEYWORDS = new Set([
+    '$schema', '$defs', '$ref', 'title', 'description', 'type', 'enum', 'const',
+    'properties', 'required', 'additionalProperties', 'items', 'minItems', 'maxItems',
+    'uniqueItems', 'minLength', 'maxLength', 'minimum', 'maximum', 'exclusiveMinimum',
+    'exclusiveMaximum', 'multipleOf', 'minProperties', 'maxProperties', 'anyOf', 'oneOf', 'allOf', 'not',
+]);
+function inspect(schema, at) {
+    if (typeof schema === 'boolean')
+        return;
+    if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) {
+        throw new TypeError(`${at}: expected a JSON Schema object or boolean`);
+    }
+    for (const [key, value] of Object.entries(schema)) {
+        if (!KEYWORDS.has(key))
+            throw new TypeError(`${at}: unsupported v1 schema keyword ${key}`);
+        if (key === '$schema' && value !== FLOW_TOOL_SCHEMA_DIALECT) {
+            throw new TypeError(`${at}: expected JSON Schema 2020-12`);
+        }
+        if (key === '$ref' && (typeof value !== 'string' || !value.startsWith('#/'))) {
+            throw new TypeError(`${at}: only document-local JSON Pointer references are supported`);
+        }
+        if (key === 'properties' || key === '$defs') {
+            if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+                throw new TypeError(`${at}.${key}: expected an object`);
+            }
+            for (const [name, child] of Object.entries(value))
+                inspect(child, `${at}.${key}.${name}`);
+        }
+        else if (key === 'items' || key === 'additionalProperties' || key === 'not') {
+            inspect(value, `${at}.${key}`);
+        }
+        else if (key === 'anyOf' || key === 'oneOf' || key === 'allOf') {
+            if (!Array.isArray(value))
+                throw new TypeError(`${at}.${key}: expected an array`);
+            value.forEach((child, i) => inspect(child, `${at}.${key}[${i}]`));
+        }
+    }
+}
+export function compileFlowToolSchema(schema) {
+    // No coercion, defaults, removal of extras, network retrieval, or ignored formats.
+    // Deliberately revalidate each supplied manifest; no unbounded global schema cache.
+    // A future admitted catalog may own a bounded compiled-validator lifecycle.
+    return new Ajv2020({ strict: true, strictRequired: true, allowUnionTypes: true, allErrors: false })
+        .compile(schema);
+}
+export function flowToolSchema(value, at) {
+    const snapshot = snapshotJsonValue(value, at, FLOW_TOOL_LIMITS);
+    inspect(snapshot, at);
+    if (snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot) || snapshot.type !== 'object') {
+        throw new TypeError(`${at}: tool schemas must explicitly have type "object"`);
+    }
+    const bounded = jsonSchemaBoundError(snapshot);
+    if (bounded !== undefined)
+        throw new TypeError(`${at}: ${bounded}`);
+    const schema = snapshot;
+    try {
+        compileFlowToolSchema(schema);
+    }
+    catch {
+        throw new TypeError(`${at}: invalid or unsupported JSON Schema`);
+    }
+    return schema;
+}
+//# sourceMappingURL=flow-tool-schema.js.map

package/dist/flow-tool-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-tool-schema.js","sourceRoot":"","sources":["../src/flow-tool-schema.ts"],"names":[],"mappings":"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"}

package/dist/flow-tool-wire.d.ts

@@ -0,0 +1,26 @@
+import { type FlowToolDigest } from './flow-tool-manifest.js';
+import { type FlowToolCatalogV1, type FlowToolCatalogEntryV1, type FlowToolRunV1, type FlowToolEventV1, type FlowToolEvidenceV1, type FlowToolInvokeRequestV1 } from './flow-tool-contract.js';
+export declare const FLOW_TOOL_ENVELOPE_LIMITS: Readonly<{
+    maxDepth: 64;
+    maxNodes: number;
+    maxBytes: number;
+}>;
+export declare function toolId(value: unknown): asserts value is string;
+export declare function flowToolInputDigest(value: unknown): FlowToolDigest;
+export declare function parseFlowToolCatalog(value: unknown): FlowToolCatalogV1;
+export declare function parseFlowToolEntry(value: unknown): FlowToolCatalogEntryV1;
+/** Stable discovery serialization independent of input key or catalog ordering. */
+export declare function canonicalFlowToolCatalog(value: unknown): string;
+/** Shared admission validation; this proves a contract binding, not authorization. */
+export declare function parseFlowToolInvocation(value: unknown, selected: FlowToolCatalogEntryV1): FlowToolInvokeRequestV1;
+export declare function parseFlowToolEvidence(value: unknown, flowDigest: FlowToolDigest): FlowToolEvidenceV1;
+export declare function flowToolRunLinks(runId: string): {
+    status_url: string;
+    events_url: string;
+    evidence_url: string;
+    cancel_url: string;
+    resume_url: string;
+};
+export declare function parseFlowToolRun(value: unknown, selected: FlowToolCatalogEntryV1, previous?: FlowToolRunV1): FlowToolRunV1;
+export declare function parseFlowToolEvent(value: unknown, run: FlowToolRunV1, cursor: number): FlowToolEventV1;
+//# sourceMappingURL=flow-tool-wire.d.ts.map

package/dist/flow-tool-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-tool-wire.d.ts","sourceRoot":"","sources":["../src/flow-tool-wire.ts"],"names":[],"mappings":"AAIA,OAAO,EAAwE,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACpI,OAAO,EAEL,KAAK,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,KAAK,kBAAkB,EAAE,KAAK,uBAAuB,EACrJ,MAAM,yBAAyB,CAAC;AAUjC,eAAO,MAAM,yBAAyB;;;;EAIpC,CAAC;AASH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAE9D;AAOD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAElE;AACD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAkBtE;AACD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB,CAEzE;AACD,mFAAmF;AACnF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAI/D;AACD,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,GAAG,uBAAuB,CAUjH;AACD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,cAAc,GAAG,kBAAkB,CAYpG;AACD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM;;;;;;EAI7C;AACD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,aAAa,CAmC1H;AACD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,CActG"}

package/dist/flow-tool-wire.js

@@ -0,0 +1,195 @@
+import { canonicalize } from './canonical.js';
+import { sha256 } from './bundle.js';
+import { snapshotJsonValue } from './json-value.js';
+import { compileFlowToolSchema, FLOW_TOOL_LIMITS } from './flow-tool-schema.js';
+import { parseFlowToolManifest, validateFlowToolInput, validateFlowToolResult } from './flow-tool-manifest.js';
+import { FlowToolError, FLOW_TOOL_CATALOG_SCHEMA, FLOW_TOOL_RUN_SCHEMA, FLOW_TOOL_EVIDENCE_SCHEMA, FLOW_TOOL_EVENT_SCHEMA, FLOW_TOOL_INVOKE_SCHEMA, } from './flow-tool-contract.js';
+// Compile only our fixed protocol schemas; never cache caller-controlled schemas globally.
+const validators = new Map([FLOW_TOOL_CATALOG_SCHEMA, FLOW_TOOL_RUN_SCHEMA, FLOW_TOOL_EVIDENCE_SCHEMA, FLOW_TOOL_EVENT_SCHEMA, FLOW_TOOL_INVOKE_SCHEMA]
+    .map(schema => [schema, compileFlowToolSchema(schema)]));
+// FLOW_TOOL_LIMITS bounds one manifest, input, or result. A catalog holds up
+// to 64 of those documents, and a run or invoke envelope wraps one of them.
+// Snapshotting the envelope with the single-document budget rejects a valid
+// catalog or a near-limit result before that document is checked on its own.
+const CATALOG_TOOL_CAP = 64;
+export const FLOW_TOOL_ENVELOPE_LIMITS = Object.freeze({
+    maxDepth: FLOW_TOOL_LIMITS.maxDepth,
+    maxNodes: FLOW_TOOL_LIMITS.maxNodes * CATALOG_TOOL_CAP + FLOW_TOOL_LIMITS.maxNodes,
+    maxBytes: FLOW_TOOL_LIMITS.maxBytes * CATALOG_TOOL_CAP + FLOW_TOOL_LIMITS.maxBytes,
+});
+const ENVELOPE_SCHEMAS = new Set([FLOW_TOOL_CATALOG_SCHEMA, FLOW_TOOL_RUN_SCHEMA, FLOW_TOOL_INVOKE_SCHEMA]);
+function wire(value, schema) {
+    try {
+        const snapshot = snapshotJsonValue(value, 'flow tool protocol', ENVELOPE_SCHEMAS.has(schema) ? FLOW_TOOL_ENVELOPE_LIMITS : FLOW_TOOL_LIMITS);
+        if (!validators.get(schema)(snapshot))
+            throw new FlowToolError('invalid_contract');
+        return snapshot;
+    }
+    catch {
+        throw new FlowToolError('invalid_contract');
+    }
+}
+export function toolId(value) {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/.test(value))
+        throw new FlowToolError('invalid_contract');
+}
+function digest(value) {
+    if (typeof value !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(value))
+        throw new FlowToolError('invalid_contract');
+}
+function decimal(value) {
+    if (!/^(0|[1-9][0-9]*)(\.[0-9]+)?$/.test(value))
+        throw new FlowToolError('invalid_contract');
+}
+export function flowToolInputDigest(value) {
+    return `sha256:${sha256(canonicalize(snapshotJsonValue(value, 'flow tool input', FLOW_TOOL_LIMITS)))}`;
+}
+export function parseFlowToolCatalog(value) {
+    const catalog = wire(value, FLOW_TOOL_CATALOG_SCHEMA);
+    const names = new Set();
+    for (const entry of catalog.tools) {
+        try {
+            parseFlowToolManifest(entry.manifest);
+        }
+        catch {
+            throw new FlowToolError('invalid_contract');
+        }
+        toolId(entry.deployment_id);
+        if (names.has(entry.manifest.name))
+            throw new FlowToolError('invalid_contract');
+        names.add(entry.manifest.name);
+        for (const name of [...entry.business_verdicts, ...entry.requires_human])
+            toolId(name);
+        // Policy labels are not enforcement. The server must also bind read_only to
+        // effective capabilities; this v1 client will not accept a write-enabled entry.
+        if (entry.effects.some(effect => !/^[a-z][a-z0-9_-]*:read$/.test(effect)))
+            throw new FlowToolError('invalid_contract');
+        if (entry.budget.max_dollars !== null) {
+            if (entry.budget.max_dollars.length > 128)
+                throw new FlowToolError('invalid_contract');
+            decimal(entry.budget.max_dollars);
+        }
+    }
+    return catalog;
+}
+export function parseFlowToolEntry(value) {
+    return parseFlowToolCatalog({ api_version: 1, tools: [value] }).tools[0];
+}
+/** Stable discovery serialization independent of input key or catalog ordering. */
+export function canonicalFlowToolCatalog(value) {
+    const catalog = parseFlowToolCatalog(value);
+    return canonicalize({ api_version: 1, tools: [...catalog.tools].sort((a, b) => a.manifest.name < b.manifest.name ? -1 : a.manifest.name > b.manifest.name ? 1 : 0) });
+}
+/** Shared admission validation; this proves a contract binding, not authorization. */
+export function parseFlowToolInvocation(value, selected) {
+    const entry = parseFlowToolEntry(selected);
+    const request = wire(value, FLOW_TOOL_INVOKE_SCHEMA);
+    if (request.flow !== `${entry.manifest.flow.name}@${entry.manifest.flow.digest}`
+        || request.deployment_id !== entry.deployment_id || request.manifest_digest !== entry.manifest.digest
+        || (request.mode === 'async' && request.wait_ms !== 0))
+        throw new FlowToolError('invalid_contract');
+    let input;
+    try {
+        input = validateFlowToolInput(entry.manifest, request.input);
+    }
+    catch {
+        throw new FlowToolError('invalid_contract');
+    }
+    if (flowToolInputDigest(input) !== request.input_digest)
+        throw new FlowToolError('invalid_contract');
+    return request;
+}
+export function parseFlowToolEvidence(value, flowDigest) {
+    const evidence = wire(value, FLOW_TOOL_EVIDENCE_SCHEMA);
+    digest(evidence.journal_digest);
+    if (evidence.flow_digest !== flowDigest)
+        throw new FlowToolError('invalid_contract');
+    const refs = new Set();
+    for (const artifact of evidence.artifacts) {
+        toolId(artifact.name);
+        toolId(artifact.ref);
+        if (refs.has(artifact.ref) || !/^[a-z0-9.+-]+\/[a-z0-9.+-]+$/.test(artifact.media_type))
+            throw new FlowToolError('invalid_contract');
+        refs.add(artifact.ref);
+    }
+    evidence.redacted_transcript_refs.forEach(toolId);
+    return evidence;
+}
+export function flowToolRunLinks(runId) {
+    toolId(runId);
+    const path = `/api/v1/flow-runs/${runId}`;
+    return { status_url: path, events_url: `${path}/events`, evidence_url: `${path}/evidence`, cancel_url: `${path}/cancel`, resume_url: `${path}/resume` };
+}
+export function parseFlowToolRun(value, selected, previous) {
+    const run = wire(value, FLOW_TOOL_RUN_SCHEMA);
+    toolId(run.run_id);
+    digest(run.input_digest);
+    if (run.tool_name !== selected.manifest.name || run.deployment_id !== selected.deployment_id
+        || run.manifest_digest !== selected.manifest.digest || run.flow_digest !== selected.manifest.flow.digest)
+        throw new FlowToolError('invalid_contract');
+    for (const [key, url] of Object.entries(flowToolRunLinks(run.run_id))) {
+        if (run[key] !== url)
+            throw new FlowToolError('invalid_contract');
+    }
+    const terminal = ['completed', 'failed', 'cancelled'].includes(run.state);
+    if (terminal !== (run.terminal !== null))
+        throw new FlowToolError('invalid_contract');
+    if (run.terminal !== null) {
+        const result = run.terminal;
+        const success = result.terminal_reason === 'success';
+        if (success !== (run.state === 'completed') || (run.state === 'cancelled') !== (result.terminal_reason === 'canceled'))
+            throw new FlowToolError('invalid_contract');
+        if (success) {
+            if (result.business_verdict === null || !selected.business_verdicts.includes(result.business_verdict) || result.result === null)
+                throw new FlowToolError('invalid_contract');
+            try {
+                validateFlowToolResult(selected.manifest, result.result);
+            }
+            catch {
+                throw new FlowToolError('invalid_contract');
+            }
+        }
+        else if (result.business_verdict !== null || result.result !== null)
+            throw new FlowToolError('invalid_contract');
+        const evidence = parseFlowToolEvidence(result.evidence, run.flow_digest);
+        const refs = new Set(evidence.artifacts.map(artifact => artifact.ref));
+        const gateNames = new Set();
+        for (const gate of result.gates) {
+            toolId(gate.name);
+            toolId(gate.evidence_ref);
+            if (!refs.has(gate.evidence_ref) || gateNames.has(gate.name))
+                throw new FlowToolError('invalid_contract');
+            gateNames.add(gate.name);
+        }
+        decimal(result.spend.dollars);
+        if (selected.budget.max_dollars !== null && result.spend.dollars_unmetered)
+            throw new FlowToolError('invalid_contract');
+    }
+    if (previous !== undefined) {
+        if (run.run_id !== previous.run_id || run.input_digest !== previous.input_digest || run.sequence < previous.sequence
+            || (run.sequence === previous.sequence && canonicalize(run) !== canonicalize(previous))
+            || (previous.terminal !== null && canonicalize(run) !== canonicalize(previous)))
+            throw new FlowToolError('invalid_contract');
+    }
+    return run;
+}
+export function parseFlowToolEvent(value, run, cursor) {
+    const event = wire(value, FLOW_TOOL_EVENT_SCHEMA);
+    if (event.run_id !== run.run_id || event.flow_digest !== run.flow_digest || event.sequence <= cursor)
+        throw new FlowToolError('invalid_contract');
+    if (event.step_id !== undefined)
+        toolId(event.step_id);
+    if (event.wait_id !== undefined)
+        toolId(event.wait_id);
+    const terminal = ['completed', 'failed', 'cancelled'].includes(event.state);
+    if ((event.type === 'run.terminal') !== terminal || terminal !== (event.terminal_reason !== undefined)
+        || (event.type === 'run.accepted' && event.state !== 'accepted')
+        || (event.type !== 'human.required' && event.wait_id !== undefined)
+        || (event.type === 'human.required' && (event.wait_id === undefined || event.state !== 'parked'))
+        || (event.type === 'step.completed' && event.step_id === undefined)
+        || (terminal && ((event.state === 'completed') !== (event.terminal_reason === 'success')
+            || (event.state === 'cancelled') !== (event.terminal_reason === 'canceled'))))
+        throw new FlowToolError('invalid_contract');
+    return event;
+}
+//# sourceMappingURL=flow-tool-wire.js.map

package/dist/flow-tool-wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-tool-wire.js","sourceRoot":"","sources":["../src/flow-tool-wire.ts"],"names":[],"mappings":"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"}

package/dist/helper-park.d.ts

@@ -0,0 +1,14 @@
+import type { JournalClient } from './journal-client.js';
+import type { StepDispatchEvent } from './protocol.js';
+import { HelperWritebackPending } from './helper-receipt.js';
+export declare function helperReceiptWaitId(stepId: string, attempt: number): string;
+/** Journal a human-wait park before the worker connection closes.
+ * Closing without this is a transport failure, and the default budget is one
+ * extra retry: two receipt timeouts then fail the accepted write.
+ */
+export declare function parkHelperReceipt(client: JournalClient, dispatch: StepDispatchEvent, error: HelperWritebackPending): Promise<void>;
+/** Resume continues the same accepted write. Answering the park redispatches
+ * the attempt; it does not submit another provider draft.
+ */
+export declare function releaseHelperReceiptWaits(client: JournalClient, runId: string): Promise<void>;
+//# sourceMappingURL=helper-park.d.ts.map

package/dist/helper-park.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-park.d.ts","sourceRoot":"","sources":["../src/helper-park.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,sBAAsB,GAChF,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBnG"}

package/dist/helper-park.js

@@ -0,0 +1,40 @@
+export function helperReceiptWaitId(stepId, attempt) {
+    return `helper-receipt:${stepId}:${attempt}`;
+}
+/** Journal a human-wait park before the worker connection closes.
+ * Closing without this is a transport failure, and the default budget is one
+ * extra retry: two receipt timeouts then fail the accepted write.
+ */
+export async function parkHelperReceipt(client, dispatch, error) {
+    await client.stepWait(dispatch.run_id, dispatch.step_id, dispatch.attempt, dispatch.idempotency_key, {
+        wait_id: helperReceiptWaitId(dispatch.step_id, dispatch.attempt),
+        prompt: error.message,
+        requested_of: 'relayfile-receipt',
+        options: ['resume'],
+    });
+}
+/** Resume continues the same accepted write. Answering the park redispatches
+ * the attempt; it does not submit another provider draft.
+ */
+export async function releaseHelperReceiptWaits(client, runId) {
+    const entries = [];
+    let from = 1;
+    for (;;) {
+        const page = (await client.journalRead(runId, from, 1000)).entries;
+        if (page.length === 0)
+            break;
+        entries.push(...page);
+        const last = page[page.length - 1]?.seq;
+        if (last === undefined || page.length < 1000)
+            break;
+        from = last + 1;
+    }
+    const closed = new Set(entries.filter(entry => entry.entry_type === 'wait.completed').map(entry => entry.payload?.wait_id));
+    for (const entry of entries) {
+        const waitId = entry.payload?.wait_id;
+        if (entry.entry_type !== 'wait.human' || waitId === undefined || !waitId.startsWith('helper-receipt:') || closed.has(waitId))
+            continue;
+        await client.eventEmit(runId, waitId, { answer: 'resume', answeredBy: 'flows-resume' });
+    }
+}
+//# sourceMappingURL=helper-park.js.map

package/dist/helper-park.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-park.js","sourceRoot":"","sources":["../src/helper-park.ts"],"names":[],"mappings":"AAIA,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,OAAe;IACjE,OAAO,kBAAkB,MAAM,IAAI,OAAO,EAAE,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAqB,EAAE,QAA2B,EAAE,KAA6B;IAEjF,MAAM,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,eAAe,EAAE;QACnG,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC;QAChE,MAAM,EAAE,KAAK,CAAC,OAAO;QACrB,YAAY,EAAE,mBAAmB;QACjC,OAAO,EAAE,CAAC,QAAQ,CAAC;KACpB,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,MAAqB,EAAE,KAAa;IAElF,MAAM,OAAO,GAAgB,EAAE,CAAC;IAChC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,CAAC,MAAM,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,OAAsB,CAAC;QAClF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM;QAC7B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACtB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC;QACxC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI;YAAE,MAAM;QACpD,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,UAAU,KAAK,gBAAgB,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5H,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC;QACtC,IAAI,KAAK,CAAC,UAAU,KAAK,YAAY,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,iBAAiB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,SAAS;QACvI,MAAM,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,CAAC,CAAC;IAC1F,CAAC;AACH,CAAC"}

package/dist/helper-receipt.d.ts

@@ -0,0 +1,11 @@
+import { type WritebackResult } from '@relayfile/adapter-core/vfs-client';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+export declare class HelperWritebackPending extends AuthoredFlowExecutionError {
+    readonly writeId: string;
+    readonly path: string;
+    constructor(writeId: string, path: string, runId: string);
+}
+export declare function helperReceiptTimeoutMs(): number;
+/** Persist intent before mount I/O: an interrupted submission is never blindly repeated. */
+export declare function writeHelperDraft(mount: string, provider: string, operation: string, path: string, body: Record<string, unknown>, dataDir: string, runId: string, stepId: string, signal: AbortSignal): Promise<WritebackResult>;
+//# sourceMappingURL=helper-receipt.d.ts.map

package/dist/helper-receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-receipt.d.ts","sourceRoot":"","sources":["../src/helper-receipt.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwC,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAEhH,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAEtE,qBAAa,sBAAuB,SAAQ,0BAA0B;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAtC,OAAO,EAAE,MAAM,EAAW,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAG3E;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAM/C;AAED,4FAA4F;AAC5F,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EACvF,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAC3F,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAqC/C"}

package/dist/helper-receipt.js

@@ -0,0 +1,100 @@
+import { readFile } from 'node:fs/promises';
+import { resolve, relative, isAbsolute } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { writeJsonFile } from '@relayfile/adapter-core/vfs-client';
+import { atomicJson, receiptPath, readHelperReceipt } from './helper-storage.js';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+export class HelperWritebackPending extends AuthoredFlowExecutionError {
+    writeId;
+    path;
+    constructor(writeId, path, runId) {
+        super('helper_writeback_pending', `write ${writeId} accepted or submission interrupted; delivery receipt pending at ${path}. Resume to wait; do not re-issue the write.`, undefined, runId);
+        this.writeId = writeId;
+        this.path = path;
+    }
+}
+export function helperReceiptTimeoutMs() {
+    const value = process.env.RELAYFLOW_HELPER_RECEIPT_TIMEOUT_MS;
+    if (value === undefined || value.trim() === '')
+        return 60_000;
+    const timeout = Number(value);
+    if (!Number.isSafeInteger(timeout) || timeout <= 0)
+        throw new Error('RELAYFLOW_HELPER_RECEIPT_TIMEOUT_MS must be a positive integer');
+    return timeout;
+}
+/** Persist intent before mount I/O: an interrupted submission is never blindly repeated. */
+export async function writeHelperDraft(mount, provider, operation, path, body, dataDir, runId, stepId, signal) {
+    const timeout = helperReceiptTimeoutMs();
+    const writeId = `${runId}:${stepId}`;
+    const file = receiptPath(dataDir, runId, stepId) + '.pending';
+    let intent;
+    try {
+        intent = await readHelperReceipt(file);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        const absolutePath = resolve(mount, path.replace(/^\/+/, ''));
+        const inside = relative(mount, absolutePath);
+        if (inside === '..' || inside.startsWith('../') || isAbsolute(inside))
+            throw new Error('Helper path escapes mount root');
+        intent = { path, absolutePath, body };
+        await atomicJson(file, intent);
+        signal.throwIfAborted();
+        const submitted = await writeJsonFile({ relayfileMountRoot: mount, writebackTimeoutMs: 0 }, provider, operation, path, body);
+        if (providerReceipt(submitted.receipt, intent.body)) {
+            return { ...submitted, deliveryStatus: 'confirmed', receipt: stringReceipt(submitted.receipt) };
+        }
+    }
+    const deadline = Date.now() + timeout;
+    do {
+        signal.throwIfAborted();
+        let receipt;
+        try {
+            receipt = JSON.parse(await readFile(intent.absolutePath, 'utf8'));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT' && !(error instanceof SyntaxError))
+                throw error;
+        }
+        // Identity fields only. A path, timestamp, or error object written while
+        // the adapter is still flushing is not a provider delivery.
+        if (providerReceipt(receipt, intent.body)) {
+            return { path: intent.path, absolutePath: intent.absolutePath, deliveryStatus: 'confirmed', receipt: stringReceipt(receipt) };
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        await delay(Math.min(250, remaining), undefined, { signal });
+    } while (Date.now() <= deadline);
+    throw new HelperWritebackPending(writeId, intent.path, runId);
+}
+/** A provider id the draft did not already carry. Path and created are not delivery. */
+function providerReceipt(receipt, draft) {
+    if (receipt === undefined || typeof receipt !== 'object' || Array.isArray(receipt))
+        return false;
+    return ['id', 'externalId', 'ts'].some(key => {
+        const value = receiptIdentity(receipt[key]);
+        return value !== undefined && value !== receiptIdentity(draft[key]);
+    });
+}
+/** GitHub mount files store comment and issue ids as JSON numbers. */
+function receiptIdentity(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    if (typeof value === 'number' && Number.isSafeInteger(value))
+        return String(value);
+    return undefined;
+}
+function stringReceipt(receipt) {
+    const next = { ...receipt };
+    for (const key of ['id', 'externalId', 'ts']) {
+        const value = receiptIdentity(receipt[key]);
+        if (value !== undefined)
+            next[key] = value;
+    }
+    return next;
+}
+//# sourceMappingURL=helper-receipt.js.map

package/dist/helper-receipt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-receipt.js","sourceRoot":"","sources":["../src/helper-receipt.ts"],"names":[],"mappings":"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"}