@relayflows/sdk 2.0.45 → 2.0.46

package/src/helper-park.ts

@@ -0,0 +1,45 @@
+import type { JournalClient } from './journal-client.js';
+import type { StepDispatchEvent } from './protocol.js';
+import { HelperWritebackPending } from './helper-receipt.js';
+
+export function helperReceiptWaitId(stepId: string, attempt: number): string {
+  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: JournalClient, dispatch: StepDispatchEvent, error: HelperWritebackPending,
+): Promise<void> {
+  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: JournalClient, runId: string): Promise<void> {
+  type WaitEntry = { seq?: number; entry_type: string; payload?: { wait_id?: string } };
+  const entries: WaitEntry[] = [];
+  let from = 1;
+  for (;;) {
+    const page = (await client.journalRead(runId, from, 1000)).entries as WaitEntry[];
+    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' });
+  }
+}

package/src/helper-receipt.ts

@@ -0,0 +1,90 @@
+import { readFile } from 'node:fs/promises';
+import { resolve, relative, isAbsolute } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { writeJsonFile, type WritebackReceipt, type WritebackResult } 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 {
+  constructor(readonly writeId: string, readonly path: string, runId: string) {
+    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);
+  }
+}
+
+export function helperReceiptTimeoutMs(): number {
+  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: string, provider: string, operation: string,
+  path: string, body: Record<string, unknown>, dataDir: string, runId: string, stepId: string,
+  signal: AbortSignal): Promise<WritebackResult> {
+  const timeout = helperReceiptTimeoutMs();
+  const writeId = `${runId}:${stepId}`;
+  const file = receiptPath(dataDir, runId, stepId) + '.pending';
+  let intent: { path: string; absolutePath: string; body: Record<string, unknown> };
+  try { intent = await readHelperReceipt(file) as typeof intent; }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).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: WritebackReceipt | undefined;
+    try { receipt = JSON.parse(await readFile(intent.absolutePath, 'utf8')) as WritebackReceipt; }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).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: WritebackReceipt | undefined, draft: Record<string, unknown>): receipt is WritebackReceipt {
+  if (receipt === undefined || typeof receipt !== 'object' || Array.isArray(receipt)) return false;
+  return (['id', 'externalId', 'ts'] as const).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: unknown): string | undefined {
+  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: WritebackReceipt): WritebackReceipt {
+  const next: WritebackReceipt = { ...receipt };
+  for (const key of ['id', 'externalId', 'ts'] as const) {
+    const value = receiptIdentity(receipt[key]);
+    if (value !== undefined) next[key] = value;
+  }
+  return next;
+}

package/src/helper-writeback.ts

@@ -1,11 +1,12 @@
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
-import { writeJsonFile, readJsonFile, listJsonFiles, type WritebackResult } from '@relayfile/adapter-core/vfs-client';
+import { readJsonFile, listJsonFiles, type WritebackResult } from '@relayfile/adapter-core/vfs-client';
 import type { RelayTransport, RelayTransportRequest } from '@relayfile/relay-helpers/transport';
 import { helperClients, helperProviders, invokeHelper, type HelperCall } from '@relayflows/surface/runtime';
 import { providerMount } from './slack-preflight.js';
 import { atomicJson } from './helper-storage.js';
 import type { SlackCall } from './slack-writeback.js';
+import { writeHelperDraft, HelperWritebackPending } from './helper-receipt.js';
 
 export class HelperDeliveryError extends Error {}
 
@@ -14,7 +15,10 @@ export async function helperWriteback(call: HelperCall, dataDir: string, runId:
   if (!factory) throw new Error(`No writeback client for ${call.provider}`);
   const { transport } = helperTransport(call, dataDir, runId, stepId, signal);
   try { return await invokeHelper(factory, call, transport); }
-  catch (cause) { throw new HelperDeliveryError(cause instanceof Error ? cause.message : String(cause), { cause }); }
+  catch (cause) {
+    if (cause instanceof HelperWritebackPending) throw cause;
+    throw new HelperDeliveryError(cause instanceof Error ? cause.message : String(cause), { cause });
+  }
 }
 
 /** One transport for every provider, including Slack. Only confirmed writes succeed. */
@@ -65,8 +69,9 @@ export function helperTransport(call: HelperCall | SlackCall, dataDir: string, r
           runId, stepId, request: { ...request, body }, receipt: result.receipt,
         });
       } else {
-        try { result = await writeJsonFile(options(), call.provider, `write.${request.resource}`, draft, body); }
+        try { result = await writeHelperDraft(options().relayfileMountRoot, call.provider, `write.${request.resource}`, draft, body, dataDir, runId, stepId, signal); }
         catch (cause) {
+          if (cause instanceof HelperWritebackPending) throw cause;
           // Upstream created() converts pending/terminal adapter errors into values.
           // A journal effect must fail instead of confirming an undelivered write.
           throw new Error(`${call.provider} writeback failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });

package/src/index.ts

@@ -131,6 +131,16 @@ export { localFlowEvalExecutor, type LocalFlowEvalExecutorOptions } from './flow
 export { cloudFlowEvalExecutor, type CloudFlowEvalExecutorOptions } from './flow-eval-cloud.js';
 
 export { canonicalize, specHash } from './canonical.js';
+export {
+  createFlowToolManifest, parseFlowToolManifest, canonicalFlowToolManifest,
+  validateFlowToolInput, validateFlowToolResult,
+  type FlowToolDeclarationV1, type FlowToolManifestV1, type FlowToolDigest,
+} from './flow-tool-manifest.js';
+export { FLOW_TOOL_SCHEMA_DIALECT, type FlowToolJson, type FlowToolObjectSchema } from './flow-tool-schema.js';
+export {
+  flowToolFunctionDefinition, flowToolMcpDefinition,
+  type FlowToolFunctionDefinition, type FlowToolMcpDefinition,
+} from './flow-tool-definitions.js';
 export {
   compileAndHash,
   compileSpec,
@@ -295,6 +305,17 @@ export {
 
 export { createFlow, type CreateFlowOptions, type CreatedFlow } from './create-flow.js';
 
+export * from './flow-tool-contract.js';
+export { parseFlowToolCatalog, canonicalFlowToolCatalog, parseFlowToolEntry, parseFlowToolRun, parseFlowToolEvent,
+  parseFlowToolEvidence, parseFlowToolInvocation, flowToolInputDigest, flowToolRunLinks } from './flow-tool-wire.js';
+export { FlowToolClient, type FlowToolTransport, type FlowToolRequest, type FlowToolInvocationOptions } from './flow-tool-client.js';
+export { createFlowToolHttpTransport, type FlowToolHttpOptions } from './flow-tool-http.js';
+export { createFlowToolAdapters } from './flow-tool-adapters.js';
+export {
+  createKernelFlowToolControlPlane, FLOW_TOOL_INPUT_PLACEHOLDER,
+  type KernelFlowToolDeployment, type KernelFlowToolControlPlaneOptions,
+} from './flow-tool-kernel.js';
+
 export { renderProgress, type ProgressEvent } from './progress.js';
 export { webhookTriggerSpec } from './trigger-executor.js';
 export { scheduleTriggerSpec, scheduleLowering, SCHEDULE_EXECUTOR, type ScheduleLowering } from './schedule-trigger.js';

package/src/yaml-helper-effect.ts

@@ -1,7 +1,8 @@
 import { createHash } from 'node:crypto';
 import { statSync } from 'node:fs';
 import { join } from 'node:path';
-import { writeJsonFile } from '@relayfile/adapter-core/vfs-client';
+import { HelperWritebackPending, writeHelperDraft } from './helper-receipt.js';
+import { parkHelperReceipt } from './helper-park.js';
 import type { RelayTransport } from '@relayfile/relay-helpers';
 import type { JournalClient } from './journal-client.js';
 import type { StepDispatchEvent } from './protocol.js';
@@ -37,8 +38,8 @@ async function writeback(call: HelperCall, dataDir: string, runId: string, stepI
       // Item updates keep the client's canonical path. Creates use a stable draft.
       const path = request.path.endsWith('.json') ? request.path
         : `${request.path}/draft-${createHash('sha256').update(idempotencyKey).digest('hex')}.json`;
-      const result = await writeJsonFile({ relayfileMountRoot: mount }, request.provider,
-        `write.${request.resource}`, path, body);
+      const result = await writeHelperDraft(mount, request.provider,
+        `write.${request.resource}`, path, body, dataDir, runId, stepId, signal);
       if (result.deliveryStatus !== 'confirmed' || !result.receipt) {
         throw new Error(`${call.provider} writeback is pending; no delivery receipt`);
       }
@@ -54,7 +55,9 @@ export async function completeHelperDispatch(
   client: JournalClient, dispatch: StepDispatchEvent, call: HelperCall, dataDir: string,
 ): Promise<void> {
   const surfacePath = `/${call.provider}`;
-  const output = await withWorkerLease(client, dispatch, async signal => {
+  let output: { idempotencyKey: string; receipt: unknown };
+  try {
+    output = await withWorkerLease(client, dispatch, async signal => {
     const file = receiptPath(dataDir, dispatch.run_id, dispatch.step_id);
     let receipt: unknown;
     await client.performEffect({
@@ -72,7 +75,11 @@ export async function completeHelperDispatch(
     });
     if (receipt === undefined) receipt = await readSlackReceipt(file);
     return { ...call, idempotencyKey: `${dispatch.run_id}:${dispatch.step_id}`, receipt };
-  });
+    });
+  } catch (error) {
+    if (error instanceof HelperWritebackPending) await parkHelperReceipt(client, dispatch, error);
+    throw error;
+  }
   await client.stepComplete(dispatch.run_id, dispatch.step_id, dispatch.attempt,
     dispatch.idempotency_key, 'success', { output, started_pins: dispatch.pins, end_pins: dispatch.pins, reported_cost: NO_MODEL_COST,
       effects: [{ surface_path: surfacePath, idempotency_key: dispatch.idempotency_key }] });