@relayflows/sdk 2.0.9 → 2.0.11

package/src/yaml-helper-effect.ts

@@ -0,0 +1,78 @@
+import { createHash } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeJsonFile } from '@relayfile/adapter-core/vfs-client';
+import type { RelayTransport } from '@relayfile/relay-helpers';
+import type { JournalClient } from './journal-client.js';
+import type { StepDispatchEvent } from './protocol.js';
+import { atomicJson, readSlackReceipt, receiptPath, slackWriteback } from './slack-writeback.js';
+import { invokeHelper, type HelperCall } from './yaml-helpers.js';
+import { withWorkerLease } from './worker-lease.js';
+
+export function helperMount(provider: string, env = process.env): string | undefined {
+  const root = [env.RELAYFILE_MOUNT_PATH, env.WORKSPACE_ROOT, env.WORKFORCE_SANDBOX_ROOT,
+    env.RELAYFILE_MOUNT_ROOT, env.RELAYFILE_ROOT].find(value => value?.trim());
+  if (!root) return undefined;
+  try { return statSync(join(root, provider)).isDirectory() ? root : undefined; }
+  catch { return undefined; }
+}
+
+export function helperReady(provider: string): boolean {
+  return (provider === 'slack' && process.env.RELAYFLOWS_SLACK_MOCK === '1') || helperMount(provider) !== undefined;
+}
+
+async function writeback(call: HelperCall, dataDir: string, runId: string, stepId: string, signal: AbortSignal) {
+  // Exactly the TS surface's client, transport, idempotency stamp and receipt checks.
+  if (call.provider === 'slack') return slackWriteback(call, dataDir, runId, stepId, signal);
+  const mount = helperMount(call.provider);
+  if (mount === undefined) throw new Error(`${call.provider} helper requires a relayfile mount`);
+  const idempotencyKey = `${runId}:${stepId}`;
+  const transport: RelayTransport = {
+    async read() { throw new Error('Helper effect transport is write-only'); },
+    async list() { throw new Error('Helper effect transport is write-only'); },
+    async write(request) {
+      signal.throwIfAborted();
+      const body = { ...request.body as Record<string, unknown>, idempotencyKey };
+      // 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);
+      if (result.deliveryStatus !== 'confirmed' || !result.receipt) {
+        throw new Error(`${call.provider} writeback is pending; no delivery receipt`);
+      }
+      signal.throwIfAborted();
+      return result;
+    },
+  };
+  return invokeHelper(call, transport);
+}
+
+/** Existing lease/effect election protocol; provider verbs never enter the kernel. */
+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 => {
+    const file = receiptPath(dataDir, dispatch.run_id, dispatch.step_id);
+    let receipt: unknown;
+    await client.performEffect({
+      runId: dispatch.run_id, stepId: dispatch.step_id, attempt: dispatch.attempt,
+      idempotencyKey: dispatch.idempotency_key, surfacePath,
+      revisionBefore: 'pending', revisionAfter: `${dispatch.run_id}:${dispatch.step_id}`,
+    }, async () => {
+      try { receipt = await readSlackReceipt(file); }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+        receipt = await writeback(call, dataDir, dispatch.run_id, dispatch.step_id, signal);
+        await atomicJson(file, receipt);
+      }
+      signal.throwIfAborted();
+    });
+    if (receipt === undefined) receipt = await readSlackReceipt(file);
+    return { ...call, idempotencyKey: `${dispatch.run_id}:${dispatch.step_id}`, receipt };
+  });
+  await client.stepComplete(dispatch.run_id, dispatch.step_id, dispatch.attempt,
+    dispatch.idempotency_key, 'success', { output, started_pins: dispatch.pins, end_pins: dispatch.pins,
+      effects: [{ surface_path: surfacePath, idempotency_key: dispatch.idempotency_key }] });
+}

package/src/yaml-helpers.ts

@@ -0,0 +1,131 @@
+import Ajv from 'ajv';
+import { githubClient, linearClient, slackClient, type RelayTransport } from '@relayfile/relay-helpers';
+import type { AgentStepSpec, KernelAgentStep, YamlHelperParams } from './spec.js';
+import { canonicalize } from './canonical.js';
+import { unknownKeyErrors } from './unknown-keys.js';
+
+const string = { type: 'string', minLength: 1 };
+const text = { type: 'string' };
+const strings = { type: 'array', items: string };
+const object = (properties: Record<string, unknown>, required = Object.keys(properties)) =>
+  ({ type: 'object', properties, required, additionalProperties: false });
+const target = object({ owner: string, repo: string, number: { type: 'integer', minimum: 1 } });
+const issueChanges = { title: string, description: text, assigneeId: string, stateId: string,
+  projectId: string, labelIds: strings, addedLabelIds: strings, removedLabelIds: strings };
+const ajv = new Ajv({ allErrors: true });
+
+function verb<P>(schema: object, invoke: (params: P, transport: RelayTransport) => Promise<unknown>) {
+  const validate = ajv.compile(schema);
+  return { validate, invoke: (params: unknown, transport: RelayTransport) => invoke(params as P, transport) };
+}
+
+/** Closed catalog: only write verbs with a declared argument schema can execute. */
+const helpers = {
+  slack: {
+    post: verb<YamlHelperParams['slack']['post']>(object({ channel: string, text,
+      opts: object({ replyTo: string }, []) }, ['channel', 'text']),
+    (p, transport) => slackClient({ transport }).post(p.channel, p.text as string, p.opts as { replyTo?: string } | undefined)),
+    dm: verb<YamlHelperParams['slack']['dm']>(object({ user: string, text }),
+      (p, transport) => slackClient({ transport }).dm(p.user, p.text)),
+    reply: verb<YamlHelperParams['slack']['reply']>(object({ channel: string, threadTs: string, text }),
+      (p, transport) => slackClient({ transport }).reply(p.channel, p.threadTs, p.text)),
+    react: verb<YamlHelperParams['slack']['react']>(object({ channel: string, messageTs: string, emoji: string }),
+      (p, transport) => slackClient({ transport }).react(p.channel, p.messageTs, p.emoji)),
+  },
+  github: {
+    comment: verb<YamlHelperParams['github']['comment']>(object({ target, body: text }),
+      (p, transport) => githubClient({ transport }).comment(p.target, p.body)),
+    createIssue: verb<YamlHelperParams['github']['createIssue']>(object({ owner: string, repo: string,
+      title: string, body: text, labels: strings }, ['owner', 'repo', 'title', 'body']),
+    (p, transport) => githubClient({ transport }).createIssue(p)),
+    createPullRequest: verb<YamlHelperParams['github']['createPullRequest']>(object({ owner: string,
+      repo: string, title: string, head: string, base: string, body: text, draft: { type: 'boolean' },
+      author: { enum: ['app', 'user'] } }, ['owner', 'repo', 'title', 'head', 'base']),
+    (p, transport) => githubClient({ transport }).createPullRequest(p)),
+    closePullRequest: verb<YamlHelperParams['github']['closePullRequest']>(target,
+      (p, transport) => githubClient({ transport }).closePullRequest(p)),
+  },
+  linear: {
+    comment: verb<YamlHelperParams['linear']['comment']>(object({ issueId: string, body: text }),
+      (p, transport) => linearClient({ transport }).comment(p.issueId, p.body)),
+    createIssue: verb<YamlHelperParams['linear']['createIssue']>(object({ teamId: string, title: string,
+      description: text, assigneeId: string, labelIds: strings, projectId: string, stateId: string }, ['teamId', 'title']),
+    (p, transport) => linearClient({ transport }).createIssue(p)),
+    updateIssue: verb<YamlHelperParams['linear']['updateIssue']>(object({ issueId: string,
+      args: object(issueChanges, []) }),
+    (p, transport) => linearClient({ transport }).updateIssue(p.issueId, p.args)),
+  },
+};
+
+export type HelperCall = { [P in keyof YamlHelperParams]: { [V in keyof YamlHelperParams[P]]:
+  { type: 'effect'; provider: P; verb: V; params: YamlHelperParams[P][V] }
+}[keyof YamlHelperParams[P]] }[keyof YamlHelperParams];
+
+const prefix = 'relayflows:helper:v1\n';
+const commonFields = ['id', 'dependsOn', 'maxIterations', 'verification', 'output'] as const;
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function descriptor(provider: string, name: string) {
+  if (!Object.hasOwn(helpers, provider)) throw new Error(`unknown helper provider "${provider}"`);
+  const verbs = helpers[provider as keyof typeof helpers];
+  if (!Object.hasOwn(verbs, name)) throw new Error(`unknown ${provider} helper verb "${name}"`);
+  return (verbs as Record<string, ReturnType<typeof verb>>)[name]!;
+}
+
+function validateCall(value: unknown): HelperCall {
+  if (!isObject(value) || value.type !== 'effect' || typeof value.provider !== 'string' || typeof value.verb !== 'string') {
+    throw new Error('expected a helper effect call');
+  }
+  const extra = unknownKeyErrors(value, ['type', 'provider', 'verb', 'params'], 'helper');
+  if (extra.length) throw new Error(extra.join('; '));
+  const entry = descriptor(value.provider, value.verb);
+  if (!entry.validate(value.params)) {
+    throw new Error(`${value.provider}.${value.verb}: ${ajv.errorsText(entry.validate.errors)}`);
+  }
+  return value as HelperCall;
+}
+
+/** Runs on the inert JSON snapshot, before ordinary step validation. */
+export function expandYamlHelpers(spec: unknown): unknown {
+  if (!isObject(spec) || !Array.isArray(spec.steps)) return spec;
+  return { ...spec, steps: spec.steps.map((step, index) => {
+    if (!isObject(step)) return step;
+    const providers = Object.keys(helpers).filter(provider => Object.hasOwn(step, provider));
+    if (!providers.length) {
+      // Recompiling a canonical envelope must fail with the same compile error
+      // contract as authoring it, before preflight or workers see it.
+      helperCall(step);
+      return step;
+    }
+    const at = `spec.steps[${index}]`;
+    try {
+      if (providers.length !== 1) throw new Error('expected exactly one helper provider per step');
+      const provider = providers[0]!;
+      const errors = unknownKeyErrors(step, [...commonFields, provider], at);
+      if (errors.length) throw new Error(errors.join('; '));
+      const verbs = step[provider];
+      if (!isObject(verbs) || Object.keys(verbs).length !== 1) throw new Error(`${provider}: expected exactly one helper verb`);
+      const name = Object.keys(verbs)[0]!;
+      const call = validateCall({ type: 'effect', provider, verb: name, params: verbs[name] });
+      const { [provider]: _, ...base } = step;
+      return { ...base, type: 'agent', instruction: prefix + canonicalize(call),
+        recoveryMode: 'reset', surfaces: { external: [`/${provider}`] } };
+    } catch (error) {
+      throw new Error(`${at}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }) };
+}
+
+/** The versioned instruction envelope survives canonical specs and journal resume. */
+export function helperCall(step: Partial<AgentStepSpec | KernelAgentStep>): HelperCall | undefined {
+  if (step.type !== 'agent' || typeof step.instruction !== 'string' || !step.instruction.startsWith(prefix)) return undefined;
+  const call = validateCall(JSON.parse(step.instruction.slice(prefix.length)));
+  if (!step.surfaces?.external?.includes(`/${call.provider}`)) throw new Error('helper effect is missing its declared external surface');
+  return call;
+}
+
+export async function invokeHelper(call: HelperCall, transport: RelayTransport): Promise<unknown> {
+  const validated = validateCall(call);
+  return (await descriptor(validated.provider, validated.verb).invoke(validated.params, transport)) ?? null;
+}