@relayflows/sdk 2.0.9 → 2.0.10

package/src/cli/serve-webhook.ts

@@ -0,0 +1,246 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, rename, unlink, lstat } from 'node:fs/promises';
+import { createServer, type Server, type ServerResponse } from 'node:http';
+import { join, resolve } from 'node:path';
+import { TextDecoder } from 'node:util';
+import type { CliIo } from '../cli.js';
+import { providerInboxEvent } from '../trigger-executor.js';
+import { verifySignature, schemeFor } from '../webhook-signature.js';
+import { TokenBucketLimiter, keyFor, type RateLimitConfig } from '../webhook-rate-limit.js';
+
+const MAX_BODY_BYTES = 1024 * 1024;
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+
+const DEFAULT_RATE_LIMIT: RateLimitConfig = { ratePerSecond: 20, burst: 60 };
+
+export function parseWebhookArgs(args: readonly string[]): {
+  command: 'serve-webhook'; dataDir: string; port: number; admitted?: readonly string[];
+} | undefined {
+  const values = new Map<string, string>();
+  for (let i = 0; i < args.length; i += 2) {
+    const flag = args[i]!;
+    const value = args[i + 1];
+    if (!['--data-dir', '--port', '--allow'].includes(flag) || values.has(flag)
+      || !value || value.startsWith('-')) return undefined;
+    values.set(flag, value);
+  }
+  const dataDir = values.get('--data-dir');
+  const portText = values.get('--port');
+  if (!dataDir || !portText || !/^\d+$/.test(portText)) return undefined;
+  const port = Number(portText);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) return undefined;
+  const allow = values.get('--allow');
+  // --allow is comma-separated. Empty list is not admitted (would refuse everything);
+  // treat as parse failure so the author sees the typo rather than a mute receiver.
+  const admitted = allow === undefined ? undefined
+    : allow.split(',').map(entry => entry.trim());
+  if (admitted !== undefined && (admitted.length === 0 || admitted.some(entry => !NAME.test(entry)))) {
+    return undefined;
+  }
+  return admitted === undefined
+    ? { command: 'serve-webhook', dataDir, port }
+    : { command: 'serve-webhook', dataDir, port, admitted };
+}
+
+function reply(response: ServerResponse, status: number, body: object): void {
+  response.writeHead(status, { 'content-type': 'application/json' });
+  response.end(JSON.stringify(body));
+}
+
+/**
+ * Look up the shared secret for a provider from the process environment.
+ *
+ * `WEBHOOK_SECRET_<PROVIDER_UPPER>` (e.g. `WEBHOOK_SECRET_GITHUB`) is the
+ * canonical env var. When unset, the receiver runs unsigned — this is
+ * documented in #301 as the local-development posture.
+ */
+export function providerSecret(provider: string | undefined, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  if (!provider) return env.WEBHOOK_SECRET_DEFAULT;
+  const upper = provider.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+  return env[`WEBHOOK_SECRET_${upper}`];
+}
+
+export interface WebhookServerOptions {
+  /**
+   * When set, unknown names refuse with `webhook_flow_unknown`. Closes the
+   * "any-name" ingress opened by slice E (#333) so the receiver only accepts
+   * inbox writes for triggers whose flows have been explicitly loaded — the
+   * loaded-flow admission half of #303. Durable handler execution against
+   * the journal is deferred; per #303 that half depends on kernel authored-
+   * handler registration + resume protocol.
+   */
+  admittedNames?: ReadonlySet<string>;
+  /** Optional rate limit config; defaults to 20/s with 60 burst per key. */
+  rateLimit?: RateLimitConfig;
+  /** Injectable env lookup for tests. */
+  env?: NodeJS.ProcessEnv;
+}
+
+/** POST /<name> accepts JSON; /providers/<provider> accepts typed event envelopes. */
+export async function startWebhookServer(
+  dataDir: string,
+  port: number,
+  options: WebhookServerOptions = {},
+): Promise<Server> {
+  const inbox = join(resolve(dataDir), 'inbox');
+  await directory(inbox);
+  const admitted = options.admittedNames;
+  const env = options.env ?? process.env;
+  const limiter = new TokenBucketLimiter(options.rateLimit ?? DEFAULT_RATE_LIMIT);
+  // TODO https://github.com/AgentWorkforce/flows/issues/301: provider signatures,
+  // public ingress and Cloud mount provisioning belong to the deployment slice.
+  const server = createServer(async (request, response) => {
+    if (request.method !== 'POST') {
+      request.resume();
+      response.setHeader('allow', 'POST');
+      reply(response, 405, { error: 'method_not_allowed' });
+      return;
+    }
+    const providerRoute = request.url?.startsWith('/providers/') ?? false;
+    const name = request.url?.slice(providerRoute ? '/providers/'.length : 1);
+    if (!name || !NAME.test(name)) {
+      request.resume();
+      reply(response, 404, { error: 'invalid_webhook_name' });
+      return;
+    }
+    // Loaded-flow admission (#303) runs FIRST: refuse unknown names before
+    // spending any body-read or rate-limit budget. A rogue POST can't
+    // accumulate events in an inbox the daemon will never drain, and can't
+    // steal from the honest ratelimit token bucket.
+    if (admitted !== undefined && !admitted.has(name)) {
+      request.resume();
+      reply(response, 404, { error: 'webhook_flow_unknown', name });
+      return;
+    }
+    // #304 rate limiting — key by provider+name+source so an abusive caller
+    // cannot starve every route. Loopback callers share 127.0.0.1 as the
+    // source key by design (single-process, single-tenant).
+    const sourceAddress = request.socket.remoteAddress ?? '127.0.0.1';
+    const provider = providerRoute ? name : undefined;
+    const rateKey = keyFor(provider, name, sourceAddress);
+    const decision = limiter.consume(rateKey);
+    if (!decision.allowed) {
+      request.resume();
+      const retryAfterSeconds = Math.max(1, Math.ceil(decision.retryAfterMs / 1000));
+      response.setHeader('retry-after', String(retryAfterSeconds));
+      reply(response, 429, { error: 'webhook_rate_limited', retryAfterMs: decision.retryAfterMs });
+      return;
+    }
+    let temporary: string | undefined;
+    try {
+      let bytes = 0;
+      const chunks: Buffer[] = [];
+      for await (const chunk of request) {
+        const buffer = Buffer.from(chunk as Uint8Array);
+        bytes += buffer.length;
+        if (bytes > MAX_BODY_BYTES) {
+          reply(response, 413, { error: 'payload_too_large' });
+          return;
+        }
+        chunks.push(buffer);
+      }
+      const rawBody = Buffer.concat(chunks);
+      // #304 signature verification — only enforced when a secret is
+      // configured for this provider/name. Absent secret = development mode.
+      const secret = providerSecret(provider, env);
+      if (secret) {
+        const scheme = schemeFor(provider);
+        const headerValue = request.headers[scheme.header];
+        const suppliedHeader = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+        const verdict = verifySignature(provider, rawBody, suppliedHeader, secret);
+        if (!verdict.ok) {
+          reply(response, 401, { error: 'webhook_signature_invalid', reason: verdict.reason });
+          return;
+        }
+      }
+      let payload: unknown;
+      try {
+        payload = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(rawBody), (_key, value: unknown) => {
+          if (typeof value === 'number' && !Number.isFinite(value)) throw new Error('non-finite JSON number');
+          return value;
+        });
+      } catch {
+        reply(response, 400, { error: 'invalid_json' });
+        return;
+      }
+      if (providerRoute) {
+        try {
+          payload = providerInboxEvent(name, payload);
+        } catch (error) {
+          // #304 payload-shape rejection: providers declare a closed event
+          // vocabulary; anything else is `webhook_payload_invalid`.
+          reply(response, 400, { error: 'webhook_payload_invalid',
+            message: error instanceof Error ? error.message : 'invalid provider event' });
+          return;
+        }
+      }
+      const target = join(inbox, name);
+      await directory(target);
+      const id = randomUUID();
+      temporary = join(target, `.${id}.tmp`);
+      const file = await open(temporary, 'wx', 0o600);
+      try {
+        await file.writeFile(JSON.stringify(payload));
+        await file.sync();
+      } finally {
+        await file.close();
+      }
+      await rename(temporary, join(target, `${id}.json`));
+      temporary = undefined;
+      const dir = await open(target, 'r');
+      try { await dir.sync(); } finally { await dir.close(); }
+      reply(response, 202, { accepted: true, id });
+    } catch {
+      if (temporary) await unlink(temporary).catch(() => undefined);
+      if (!response.headersSent) reply(response, 500, { error: 'inbox_write_failed' });
+      else response.destroy();
+    }
+  });
+  server.requestTimeout = 30_000;
+  server.headersTimeout = 10_000;
+  await new Promise<void>((accept, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+      server.off('error', reject);
+      accept();
+    });
+  });
+  return server;
+}
+
+async function directory(path: string): Promise<void> {
+  await mkdir(path, { recursive: true });
+  if (!(await lstat(path)).isDirectory()) throw new Error('inbox directory must not be a symlink');
+}
+
+export async function runServeWebhook(
+  options: { dataDir: string; port: number; admitted?: readonly string[] }, io: CliIo,
+): Promise<0 | 1> {
+  try {
+    const admittedNames = options.admitted === undefined ? undefined : new Set(options.admitted);
+    const server = await startWebhookServer(options.dataDir, options.port, { admittedNames });
+    const address = server.address();
+    const port = typeof address === 'object' && address ? address.port : options.port;
+    io.stdout(`WEBHOOK http://127.0.0.1:${port}`);
+    if (admittedNames !== undefined) {
+      io.stdout(`ADMITTED ${[...admittedNames].sort().join(',')}`);
+    }
+    await new Promise<void>((accept, reject) => {
+      const stop = (): void => {
+        server.close(error => error ? reject(error) : accept());
+        server.closeAllConnections();
+      };
+      server.once('error', reject);
+      process.once('SIGINT', stop);
+      process.once('SIGTERM', stop);
+      server.once('close', () => {
+        process.off('SIGINT', stop);
+        process.off('SIGTERM', stop);
+      });
+    });
+    return 0;
+  } catch (error) {
+    io.stderr(`FAILED [webhook_server] ${error instanceof Error ? error.message : 'receiver failed'}`);
+    return 1;
+  }
+}

package/src/cli/tick-runner.ts

@@ -37,6 +37,7 @@
 
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { socketPathFor } from '../daemon-connection.js';
 import { JournalClient } from '../journal-client.js';
 import {
   DEFAULT_MAX_CATCH_UP,
@@ -269,7 +270,7 @@ export async function runTickRunner(args: TickRunnerArgs, io: CliIo): Promise<nu
   const resuming = state.lastEmittedSlot !== undefined;
   const cursor: TickCursor = resuming ? { lastEmittedSlot: state.lastEmittedSlot } : {};
 
-  const socketPath = join(args.dataDir, 'relayflowd.sock');
+  const socketPath = socketPathFor(args.dataDir);
   let client: TickRunnerClient;
   try {
     client = args.connectClient

package/src/cli-adapter.ts

@@ -1,50 +1,40 @@
-import { basename } from 'node:path';
-
-export type CliAdapterKind = 'claude' | 'codex' | 'relayflows-wrapper-v1';
-
-export interface CliInvocation {
-  args: string[];
-  timeoutMs: number;
-  /** Set only for wrapper readiness probes; raw providers receive a model flag. */
-  modelEnv?: string;
-}
+/**
+ * Legacy dispatch surface — retained so existing callers (`worker-cli.ts`,
+ * `cli/check.ts`, real-cli-adapters tests) compile unchanged. The per-CLI
+ * knowledge now lives in `./adapters/{claude,codex,wrapper}.ts` behind the
+ * `HeadlessAdapter` interface (flows#141). New CLIs implement the interface
+ * and register in `./adapters/index.ts`; this file no longer needs edits.
+ */
+import {
+  resolveAdapterKind,
+  registeredAdapters,
+} from './adapters/index.js';
+import type { CliAdapterKind } from './adapters/index.js';
+import type { CliInvocation, CliAdapterIdentification } from './adapters/base.js';
 
-export interface CliAdapterIdentification {
-  invocation: CliInvocation;
-  expectedStdout?: string;
-}
+export type { CliAdapterKind } from './adapters/index.js';
+export type { CliInvocation, CliAdapterIdentification, HeadlessAdapter } from './adapters/base.js';
 
-export const WRAPPER_IDENTIFY_ARG = '--relayflows-adapter-v1';
-export const WRAPPER_IDENTIFY_TOKEN = 'relayflows-agent-cli-v1';
-export const WRAPPER_EXECUTE_TOKEN = 'relayflows-agent-cli-v1-execute';
+export {
+  WRAPPER_IDENTIFY_ARG,
+  WRAPPER_IDENTIFY_TOKEN,
+  WRAPPER_EXECUTE_TOKEN,
+} from './adapters/wrapper.js';
 
-const MODEL_PROBE_PROMPT = 'Reply with exactly RELAYFLOWS_MODEL_READY and nothing else.';
+export { resolveAdapter, resolveAdapterKind, registeredAdapters } from './adapters/index.js';
 
 /** Select a closed adapter from the resolved executable's basename. */
 export function cliAdapterKind(executable: string): CliAdapterKind {
-  const name = basename(executable).replace(/\.exe$/i, '');
-  if (name === 'claude') return 'claude';
-  if (name === 'codex') return 'codex';
-  return 'relayflows-wrapper-v1';
+  return resolveAdapterKind(executable);
 }
 
 /** Prove the adapter command shape before classifying an auth failure. */
 export function adapterIdentification(kind: CliAdapterKind): CliAdapterIdentification {
-  if (kind === 'claude') {
-    return { invocation: { args: ['auth', 'status', '--help'], timeoutMs: 10_000 } };
-  }
-  if (kind === 'codex') {
-    return { invocation: { args: ['login', 'status', '--help'], timeoutMs: 10_000 } };
-  }
-  return {
-    invocation: { args: [WRAPPER_IDENTIFY_ARG], timeoutMs: 10_000 },
-    expectedStdout: WRAPPER_IDENTIFY_TOKEN,
-  };
+  return registeredAdapters()[kind].buildIdentification();
 }
 
 export function authenticationProbe(kind: CliAdapterKind): CliInvocation {
-  if (kind === 'codex') return { args: ['login', 'status'], timeoutMs: 10_000 };
-  return { args: ['auth', 'status'], timeoutMs: 10_000 };
+  return registeredAdapters()[kind].buildAuthProbe();
 }
 
 /**
@@ -53,29 +43,7 @@ export function authenticationProbe(kind: CliAdapterKind): CliInvocation {
  * exact model through its explicitly identified environment contract.
  */
 export function modelReadinessProbe(kind: CliAdapterKind, model: string): CliInvocation {
-  if (kind === 'claude') {
-    return {
-      args: [
-        '-p', '--model', model, '--tools', '', '--no-session-persistence',
-        MODEL_PROBE_PROMPT,
-      ],
-      timeoutMs: 60_000,
-    };
-  }
-  if (kind === 'codex') {
-    return {
-      args: [
-        'exec', '--ephemeral', '--sandbox', 'read-only', '--skip-git-repo-check',
-        '--model', model, MODEL_PROBE_PROMPT,
-      ],
-      timeoutMs: 60_000,
-    };
-  }
-  return {
-    args: ['auth', 'status'],
-    timeoutMs: 60_000,
-    modelEnv: model,
-  };
+  return registeredAdapters()[kind].buildModelReadinessProbe(model);
 }
 
 /** Build the actual worker argv; this is shared contract, not probe-only lore. */
@@ -84,23 +52,12 @@ export function agentExecution(
   instruction: string,
   model?: string,
 ): CliInvocation {
-  if (kind === 'claude') {
-    return {
-      args: ['-p', ...(model === undefined ? [] : ['--model', model]), instruction],
-      timeoutMs: 0,
-    };
-  }
-  if (kind === 'codex') {
-    return {
-      args: [
-        'exec', '--ephemeral', '--skip-git-repo-check',
-        ...(model === undefined ? [] : ['--model', model]),
-        instruction,
-      ],
-      timeoutMs: 0,
-    };
-  }
-  throw new Error('custom wrapper execution requires the runAgentCli same-process session');
+  return registeredAdapters()[kind].buildAgentInvocation(instruction, model);
+}
+
+/** Reuse the workspace-free model probe's provider flags for a real LLM call. */
+export function llmExecution(kind: CliAdapterKind, prompt: string, model?: string): CliInvocation {
+  return registeredAdapters()[kind].buildLlmInvocation(prompt, model);
 }
 
 export function displayInvocation(cli: string, invocation: CliInvocation): string {

package/src/cli-watch.ts

@@ -0,0 +1,174 @@
+import { spawn } from 'node:child_process';
+import { accessSync, constants, existsSync, readFileSync, watch, type FSWatcher } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+import type { CliIo } from './cli.js';
+
+const DEBOUNCE_MS = 150;
+type ExitCode = 0 | 1 | 2 | 3;
+
+/** A runner around the ordinary CLI, with a fresh module cache for every check. */
+export async function watchCheck(path: string, json: boolean, io: CliIo): Promise<ExitCode> {
+  const controller = new AbortController();
+  const stop = (): void => controller.abort();
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+  try {
+    return await watchChecks({
+      path,
+      signal: controller.signal,
+      check: () => checkOnce(path, json, io),
+      clear: () => { if (!json) io.stdout('\x1b[2J\x1b[H'); },
+    });
+  } catch (error) {
+    io.stderr(`REFUSED [input_unreadable] Could not watch "${path}": ${error instanceof Error ? error.message : String(error)}`);
+    return 2;
+  } finally {
+    process.off('SIGINT', stop);
+    process.off('SIGTERM', stop);
+  }
+}
+
+/** Inject the check and cancellation, just as the SDK pollers inject their I/O. */
+export async function watchChecks(options: {
+  path: string;
+  signal: AbortSignal;
+  check: () => Promise<ExitCode>;
+  clear: () => void;
+}): Promise<ExitCode> {
+  const watchers = new Map<string, FSWatcher>();
+  const imports = new Map<string, string[]>();
+  let paths = new Set<string>();
+  let lastCode: ExitCode = 0;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let pending = false;
+  let stopped = options.signal.aborted;
+  let wake: (() => void) | undefined;
+  let watchError: Error | undefined;
+
+  const changed = (): void => {
+    if (stopped) return;
+    pending = true;
+    clearTimeout(timer);
+    timer = setTimeout(() => { timer = undefined; wake?.(); }, DEBOUNCE_MS);
+  };
+  const stop = (): void => {
+    stopped = true;
+    clearTimeout(timer);
+    timer = undefined;
+    wake?.();
+  };
+  const refresh = (): void => {
+    paths = discoverWatchPaths(options.path, imports);
+    const directories = new Set<string>();
+    for (const path of paths) {
+      let directory = dirname(path);
+      while (!existsSync(directory) && dirname(directory) !== directory) directory = dirname(directory);
+      directories.add(directory);
+      if (watchers.has(directory)) continue;
+      // Watch directories so atomic editor saves and delete/recreate keep working.
+      const watcher = watch(directory, (_event, filename) => {
+        const changedPath = filename === null ? undefined : resolve(directory, filename.toString());
+        if (changedPath === undefined || [...paths].some((target) =>
+          target === changedPath || target.startsWith(`${changedPath}${sep}`))) changed();
+      });
+      watcher.on('error', (error) => { watchError = error; stop(); });
+      watchers.set(directory, watcher);
+    }
+    for (const [directory, watcher] of watchers) {
+      if (!directories.has(directory)) { watcher.close(); watchers.delete(directory); }
+    }
+  };
+
+  options.signal.addEventListener('abort', stop, { once: true });
+  try {
+    refresh();
+    let first = true;
+    while (!stopped) {
+      if (!first && (!pending || timer !== undefined)) {
+        await new Promise<void>((resolveWake) => { wake = resolveWake; });
+        wake = undefined;
+        continue;
+      }
+      pending = false;
+      refresh();
+      if (!first) options.clear();
+      first = false;
+      lastCode = await options.check();
+      // A change while checking remains pending. Never overlap checks or lose
+      // a save merely because its debounce deadline elapsed during a check.
+      if (!stopped) refresh();
+    }
+    if (watchError !== undefined) throw watchError;
+    return lastCode;
+  } finally {
+    options.signal.removeEventListener('abort', stop);
+    clearTimeout(timer);
+    for (const watcher of watchers.values()) watcher.close();
+  }
+}
+
+function discoverWatchPaths(path: string, imports: Map<string, string[]>): Set<string> {
+  const paths = new Set<string>();
+  const visit = (file: string): void => {
+    if (paths.has(file)) return;
+    paths.add(file);
+    try {
+      const value: unknown = parseYaml(readFileSync(file, 'utf8'));
+      const use = typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? (value as Record<string, unknown>)['use'] : undefined;
+      imports.set(file, Array.isArray(use) ? use.filter((entry): entry is string =>
+        typeof entry === 'string' && (entry.startsWith('./') || entry.startsWith('../'))) : []);
+    } catch {
+      // Keep the previous graph while an editor has left this file incomplete.
+      // The ordinary check owns all parse and validation diagnostics.
+    }
+    for (const dependency of imports.get(file) ?? []) visit(resolve(dirname(file), dependency));
+  };
+  visit(resolve(path));
+  for (const file of imports.keys()) { if (!paths.has(file)) imports.delete(file); }
+  let directory = dirname(resolve(path));
+  while (true) {
+    const candidate = join(directory, 'flows.json');
+    paths.add(candidate);
+    try { accessSync(candidate, constants.R_OK); break; }
+    catch { /* Match check's nearest-readable-config discovery. */ }
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  return paths;
+}
+
+function checkOnce(path: string, json: boolean, io: CliIo): Promise<ExitCode> {
+  // Importing an authored TS file in this process again would return its stale
+  // cached definition (including transitive imports). A fresh CLI process uses
+  // precisely the same check pipeline and reporting as a one-shot invocation.
+  const entry = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? './cli.ts' : './cli.js', import.meta.url));
+  return new Promise((resolveCode, reject) => {
+    const child = spawn(process.execPath, [...process.execArgv, entry, 'check', ...(json ? ['--json'] : []), path], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      // Ctrl-C belongs to the watcher; let an active check finish so its report
+      // and exit status remain a pair, then release all resources.
+      detached: true,
+    });
+    const forward = (stream: NodeJS.ReadableStream, write: (line: string) => void): void => {
+      let pending = '';
+      stream.setEncoding('utf8');
+      stream.on('data', (chunk: string) => {
+        pending += chunk;
+        let end: number;
+        while ((end = pending.indexOf('\n')) >= 0) {
+          write(pending.slice(0, end));
+          pending = pending.slice(end + 1);
+        }
+      });
+      stream.on('end', () => { if (pending) write(pending); });
+    };
+    forward(child.stdout, io.stdout);
+    forward(child.stderr, io.stderr);
+    child.once('error', reject);
+    child.once('close', (code) => resolveCode(code === 0 || code === 2 || code === 3 ? code : 1));
+  });
+}