@relayflows/sdk 2.0.19 → 2.0.21

package/dist/worker-usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker-usage.d.ts","sourceRoot":"","sources":["../src/worker-usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAoBvD,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,eAAe,CAUvG;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAK5E;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,eAAe,CAM3F"}
+{"version":3,"file":"worker-usage.d.ts","sourceRoot":"","sources":["../src/worker-usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAoBvD,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,eAAe,CAUvG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAMjF;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAK5E;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,eAAe,CAM3F"}

package/dist/worker-usage.js

@@ -31,6 +31,25 @@ export function decodeProviderResult(result, kind) {
         .flatMap(f => f.type === 'item.completed' && record(f.item) && f.item.type === 'agent_message' && typeof f.item.text === 'string' ? [f.item.text] : []).join('\n');
     return usageResult(result, terminal.usage, text);
 }
+/**
+ * Claude's terminal `stream-json` frame, recognised line by line as it
+ * streams. `failed` mirrors the exit status Claude gives that result: an
+ * error flag or a non-success subtype is a failed run.
+ */
+export function claudeResultOutcome(line) {
+    if (!line.includes('"result"'))
+        return undefined;
+    let frame;
+    try {
+        frame = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (!record(frame) || frame.type !== 'result')
+        return undefined;
+    return { failed: frame.is_error === true || (typeof frame.subtype === 'string' && frame.subtype !== 'success') };
+}
 /** Optional wrapper result envelope; existing opaque text output stays valid. */
 export function decodeWrapperResult(result) {
     let value;

package/dist/worker-usage.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayflows/sdk",
-  "version": "2.0.19",
+  "version": "2.0.21",
   "description": "TypeScript-first authoring SDK for Relayflows. Compiles specs; speaks the journal protocol.",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,7 +49,7 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@relayfile/adapter-core": "0.5.26",
     "@relayfile/relay-helpers": "0.4.11",
-    "@relayflows/surface": "2.0.19",
+    "@relayflows/surface": "2.0.21",
     "@types/js-yaml": "^4.0.9",
     "ai-hist": "0.4.1",
     "ajv": "^8.17.1",

package/src/agent-reaper.ts

@@ -0,0 +1,52 @@
+import type { ChildStop } from './child-stop.js';
+
+/**
+ * An agent CLI runs in a process group of its own, so nothing that ends this
+ * process reaches it by default: a signal to our pid, or to our group, leaves
+ * it running, reparented to init. That is how a `claude` outlived a Cloud run
+ * that was killed at its deadline, for hours. While any agent is live this
+ * module kills every live agent tree on the way out:
+ *
+ * - on `'exit'`, which covers normal exit and `process.exit()`;
+ * - on SIGINT, SIGTERM and SIGHUP, but only where the default action would
+ *   have ended the process anyway — this listener is the only one. It then
+ *   removes itself and re-raises the signal, so the process still dies of it.
+ *   A host that installed its own listener owns that signal; it aborts the
+ *   lease signal, and the abort already stops the tree.
+ *
+ * Nothing survives a SIGKILL of this process; that needs a supervisor.
+ */
+const live = new Set<ChildStop>();
+const FATAL_SIGNALS: readonly NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+
+function killAll(): void {
+  for (const stop of live) stop.kill();
+  live.clear();
+}
+
+function onFatalSignal(signal: NodeJS.Signals): void {
+  if (process.listenerCount(signal) !== 1) return;
+  killAll();
+  uninstall();
+  process.kill(process.pid, signal);
+}
+
+function install(): void {
+  process.on('exit', killAll);
+  for (const signal of FATAL_SIGNALS) process.on(signal, onFatalSignal);
+}
+
+function uninstall(): void {
+  process.off('exit', killAll);
+  for (const signal of FATAL_SIGNALS) process.off(signal, onFatalSignal);
+}
+
+/** Kill this agent tree if the process ends first. Returns the release. */
+export function reapOnExit(stop: ChildStop): () => void {
+  if (live.size === 0) install();
+  live.add(stop);
+  return () => {
+    if (!live.delete(stop)) return;
+    if (live.size === 0) uninstall();
+  };
+}

package/src/authored-flow-error.ts

@@ -1,3 +1,4 @@
+import type { HumanRecipient } from './human-to.js';
 import type {
   CompletionReason as ProtocolCompletionReason,
   RunCompletionReason as ProtocolRunCompletionReason,
@@ -28,6 +29,8 @@ export type AuthoredFlowExecutionErrorCode =
   | 'human_parked'
   /** A recorded answer to `f.human` was not `{ answer: boolean }`. */
   | 'human_answer_invalid'
+  /** `f.human`'s `to` is not one of the documented recipient forms (human-to.ts). */
+  | 'human_to_invalid'
   | 'unsupported_header'
   | 'unsettled_derived_work'
   | 'unsupported_promise_lifecycle'
@@ -52,6 +55,8 @@ export interface AuthoredHumanWait {
   readonly waitId: string;
   readonly question: string;
   readonly to: string;
+  /** `to` parsed into its delivery form (human-to.ts); Cloud delivers by it. */
+  readonly recipient?: HumanRecipient;
 }
 
 /**

package/src/authored-flow-executor.ts

@@ -36,6 +36,7 @@ import {
   type AuthoredFlowExecutionErrorCode,
 } from './authored-flow-error.js';
 import { readHumanAnswer } from './authored-human.js';
+import { parseHumanTo } from './human-to.js';
 import {
   AuthoredFlowOperation,
   stopAuthoredOperations,
@@ -431,6 +432,13 @@ export async function executeAuthoredFlow<Input = undefined>(
       if (typeof humanOptions?.to !== 'string' || humanOptions.to.trim() === '') {
         throw new AuthoredFlowExecutionError('human_answer_invalid', 'f.human requires { to } naming who answers');
       }
+      // Refused before an ordinal is consumed or anything is journaled: a
+      // malformed `to` would otherwise park the run on a question Cloud can
+      // deliver to no one (docs/SURFACE.md §5 lists the four forms).
+      const parsedTo = parseHumanTo(humanOptions.to);
+      if (!parsedTo.ok) {
+        throw new AuthoredFlowExecutionError('human_to_invalid', `f.human to ${parsedTo.reason}`);
+      }
       const id = `human-${nextStep++}`;
       const to = humanOptions.to;
       // Hoisted like `llmOp`/`runOp`: the start closure reads the caller's

package/src/child-stop.ts

@@ -1,4 +1,4 @@
-import type { ChildProcess } from 'node:child_process';
+import { execFileSync, type ChildProcess } from 'node:child_process';
 
 /**
  * Grace between the graceful signal and the force kill. A tree that ignores
@@ -78,25 +78,40 @@ export function childStop(
     if (forceTimer !== undefined) clearTimeout(forceTimer);
     forceTimer = undefined;
   };
-  /** Whether anything is still in the group. See `maySettleOnChildExit`. */
+  // Descendants that moved into process groups of their own, captured at the
+  // first stop. Claude Code runs a `run_in_background` Bash command that way,
+  // so a group signal alone leaves it running after the agent is gone. They
+  // must be found while the direct child is still their ancestor: once it
+  // dies they are reparented and no longer traceable to this spawn.
+  let escapedGroups: readonly number[] | undefined;
+  /**
+   * Whether anything the stop reaches is still alive: the child's own group or
+   * any group a descendant escaped into. See `maySettleOnChildExit`.
+   */
   const groupAnswers = (): boolean => {
     // With no group of our own a stop never reached past the direct child, so
     // that child's exit IS the whole of our reach and there is nothing left to
     // ask about.
     if (!ownsGroup || pid === undefined) return false;
-    try {
-      process.kill(-pid, 0);
-      return true;
-    } catch (error) {
-      // Only `ESRCH` proves the group is empty. `EPERM` proves the opposite —
-      // something is in there that we may not signal — and any other errno
-      // proves nothing at all, so both must read as alive: an unproven group is
-      // not a reason to spare a survivor.
-      return (error as NodeJS.ErrnoException).code !== 'ESRCH';
-    }
+    return [pid, ...(escapedGroups ?? [])].some(group => {
+      try {
+        process.kill(-group, 0);
+        return true;
+      } catch (error) {
+        // Only `ESRCH` proves the group is empty. `EPERM` proves the opposite
+        // — something is in there that we may not signal — and any other
+        // errno proves nothing at all, so both must read as alive: an unproven
+        // group is not a reason to spare a survivor.
+        return (error as NodeJS.ErrnoException).code !== 'ESRCH';
+      }
+    });
   };
   const signalTree = (name: NodeJS.Signals): void => {
     if (ownsGroup && pid !== undefined) {
+      escapedGroups ??= descendantGroups(pid);
+      for (const group of escapedGroups) {
+        try { process.kill(-group, name); } catch { /* already gone */ }
+      }
       // `-pid` addresses the group this detached child leads, which is every
       // descendant that has not left it. It throws only once the whole group
       // is gone — the outcome we were asking for — so fall through and let the
@@ -136,3 +151,38 @@ export function childStop(
     },
   };
 }
+
+/**
+ * Process groups, other than `rootPid`'s own and this process's, that hold a
+ * descendant of `rootPid`. Reads `ps` for pid, parent and group only — never a
+ * command line. Where `ps` cannot answer, the answer is none: the group signal
+ * still reaches everything that stayed in the group.
+ */
+function descendantGroups(rootPid: number): number[] {
+  let table: string;
+  try {
+    table = execFileSync('ps', ['-A', '-o', 'pid=,ppid=,pgid='], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2_000,
+    });
+  } catch {
+    return [];
+  }
+  const children = new Map<number, number[]>();
+  const groupOf = new Map<number, number>();
+  for (const line of table.split('\n')) {
+    const fields = line.trim().split(/\s+/).map(Number);
+    if (fields.length !== 3 || !fields.every(Number.isSafeInteger)) continue;
+    const [row, parent, group] = fields as [number, number, number];
+    groupOf.set(row, group);
+    children.set(parent, [...(children.get(parent) ?? []), row]);
+  }
+  const spared = new Set([rootPid, groupOf.get(process.pid)]);
+  const groups = new Set<number>();
+  const pending = [...(children.get(rootPid) ?? [])];
+  for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+    const group = groupOf.get(next);
+    if (group !== undefined && group > 1 && !spared.has(group)) groups.add(group);
+    pending.push(...(children.get(next) ?? []));
+  }
+  return [...groups];
+}

package/src/cli/answer.ts

@@ -1,3 +1,4 @@
+import { parseHumanRecipient } from '../human-to.js';
 import { userInfo } from 'node:os';
 import { readAuthoredRootMetadata } from '../authored-root.js';
 import { HUMAN_WAIT_ID, humanAnswerPayload, readHumanAnswer, readOpenHumanWaits, resumeCommand } from '../authored-human.js';
@@ -75,7 +76,7 @@ export async function answerFlow(
       report: {
         ...base, ok: true, runId, socketPath, status: snapshot.status,
         answer: { waitId, answer, ...(options.note === undefined ? {} : { note: options.note }) },
-        humanWait: { waitId, question: wait.question, to: wait.to },
+        humanWait: { waitId, question: wait.question, to: wait.to, recipient: parseHumanRecipient(wait.to) },
         next: resumeCommand(runId, dataDir, root?.localAgentStream !== undefined),
         diagnostics: [],
       },

package/src/cli/run.ts

@@ -1,3 +1,4 @@
+import { parseHumanRecipient } from '../human-to.js';
 import { parseDigestReference } from '../bundle-transport.js';
 import { prepareDigestRun } from './run-digest.js';
 import { reuseSummary } from './reuse.js';
@@ -331,7 +332,7 @@ export function authoredHumanParked(
       socketPath,
       status: 'parked',
       parkedStep: { id: 'authored-root', type: 'agent' },
-      humanWait: error.wait,
+      humanWait: { ...error.wait, recipient: parseHumanRecipient(error.wait.to) },
       diagnostics: [...base.diagnostics, {
         severity: 'parked',
         kind: 'run_parked',

package/src/flow-requirements.ts

@@ -1,3 +1,4 @@
+import { humanRecipientProvider } from './human-to.js';
 import { helperProviders } from '@relayflows/surface/runtime';
 import type { TriggerSource } from '@relayflows/surface';
 import { providerDeclaration } from './provider-trigger-contract.js';
@@ -26,8 +27,8 @@ export interface FlowIntegrationRequirement {
   /** Cloud integration provider id (`slack`, `github`, `linear`, …). */
   provider: string;
   /** `tools`: a header declaration; `source`: a trigger or deploy target; `helper`: body use without a flag, or a YAML helper step. */
-  from: 'tools' | 'source' | 'helper';
-  /** The declaration that requires it, as a reader would name it: `tools.slack`, `--on github`, `f.slack`. */
+  from: 'tools' | 'source' | 'helper' | 'human';
+  /** The declaration that requires it, as a reader would name it: `tools.slack`, `--on github`, `f.slack`, `f.human to`. */
   detail: string;
 }
 
@@ -119,6 +120,14 @@ export function flowRequirements(
         if (helperReference(root, namespace).test(text)) declare({ provider, from: 'helper', detail: `f.${namespace}` });
       }
       for (const use of workerCalls(root, text)) need(use.cli === undefined ? fallback : harnessFromCli(use.cli), use.detail);
+      // `f.human(q, { to: "slack:#eng" })` is delivered by Cloud through that
+      // provider, so the deploy must have it connected. Only a literal `to`
+      // can be read here; a computed one (`input.approver`) is resolved by
+      // Cloud at park time against the run's own trigger channel.
+      for (const to of humanRecipients(root, text)) {
+        const provider = humanRecipientProvider(to);
+        if (provider !== undefined) declare({ provider, from: 'human', detail: 'f.human to' });
+      }
     }
   }
 
@@ -180,6 +189,138 @@ function helperReference(root: string, namespace: string): RegExp {
   return new RegExp(`(?:^|[^\\w$.])${root}\\s*(?:\\.\\s*${namespace}\\b|\\[\\s*['"]${namespace}['"]\\s*\\])`, 'u');
 }
 
+/**
+ * The literal `to` of each `f.human(question, { to: "…" })` call in the body.
+ *
+ * Bounded to the call's OWN argument list — the text between its `(` and the
+ * matching `)`, string- and nesting-aware — and within that to the top level
+ * of its options object, so a `to:` in a later call, in a nested object, in
+ * the question string, or in an unrelated `{ to }` of the surrounding code is
+ * never read as this call's recipient. Only a plain string literal counts; a
+ * template with interpolation or an identifier is a computed `to`, resolved
+ * by Cloud at park time.
+ */
+function humanRecipients(root: string, body: string): string[] {
+  const call = new RegExp(`(?:^|[^\\w$.])${root}\\s*\\.\\s*human\\s*\\(`, 'gu');
+  const found: string[] = [];
+  for (const match of body.matchAll(call)) {
+    const open = match.index! + match[0].length - 1;
+    const close = matchingClose(body, open);
+    if (close === -1) continue;
+    const args = body.slice(open + 1, close);
+    const options = secondArgumentObject(args);
+    if (options === undefined) continue;
+    const to = topLevelStringProperty(options, 'to');
+    if (to !== undefined) found.push(to);
+  }
+  return found;
+}
+
+/**
+ * Skip the comment or string starting at `i`, returning the index just past
+ * it; `i` itself when nothing skippable starts there; -1 when unterminated.
+ * Every walker below steps through this, so a `,`, `to:` or bracket inside a
+ * comment or string is never read as syntax.
+ */
+function skipCommentOrString(text: string, i: number): number {
+  const ch = text[i]!;
+  const next = text[i + 1];
+  if (ch === '/' && next === '/') { const end = text.indexOf('\n', i); return end === -1 ? text.length : end + 1; }
+  if (ch === '/' && next === '*') { const end = text.indexOf('*/', i + 2); return end === -1 ? -1 : end + 2; }
+  if (ch === '"' || ch === "'" || ch === '`') { const end = stringEnd(text, i); return end === -1 ? -1 : end + 1; }
+  return i;
+}
+
+/** Index of the `)`/`}`/`]` closing the bracket at `open`, skipping strings, templates and comments; -1 if unbalanced. */
+function matchingClose(text: string, open: number): number {
+  const pairs: Record<string, string> = { '(': ')', '{': '}', '[': ']' };
+  const stack: string[] = [pairs[text[open]!]!];
+  let i = open + 1;
+  while (i < text.length && stack.length > 0) {
+    const skipped = skipCommentOrString(text, i);
+    if (skipped === -1) return -1;
+    if (skipped !== i) { i = skipped; continue; }
+    const ch = text[i]!;
+    if (ch in pairs) stack.push(pairs[ch]!);
+    else if (ch === ')' || ch === '}' || ch === ']') { if (stack.pop() !== ch) return -1; }
+    i += 1;
+  }
+  return stack.length === 0 ? i - 1 : -1;
+}
+
+/** Index of the quote closing the string opening at `start` (template `${…}` skipped); -1 if unterminated. */
+function stringEnd(text: string, start: number): number {
+  const quote = text[start]!;
+  let i = start + 1;
+  while (i < text.length) {
+    const ch = text[i]!;
+    if (ch === '\\') { i += 2; continue; }
+    if (ch === quote) return i;
+    if (quote === '`' && ch === '$' && text[i + 1] === '{') {
+      const end = matchingClose(text, i + 1);
+      if (end === -1) return -1;
+      i = end + 1;
+      continue;
+    }
+    i += 1;
+  }
+  return -1;
+}
+
+/** The `{ … }` that is the call's second top-level argument, or undefined. */
+function secondArgumentObject(args: string): string | undefined {
+  let depth = 0;
+  let i = 0;
+  let commas = 0;
+  while (i < args.length) {
+    const skipped = skipCommentOrString(args, i);
+    if (skipped === -1) return undefined;
+    if (skipped !== i) { i = skipped; continue; }
+    const ch = args[i]!;
+    if (ch === '(' || ch === '{' || ch === '[') {
+      if (depth === 0 && commas === 1 && ch === '{') {
+        const close = matchingClose(args, i);
+        return close === -1 ? undefined : args.slice(i, close + 1);
+      }
+      depth += 1;
+    } else if (ch === ')' || ch === '}' || ch === ']') depth -= 1;
+    else if (ch === ',' && depth === 0) commas += 1;
+    i += 1;
+  }
+  return undefined;
+}
+
+/** The plain string literal value of `name:` at the top level of an object literal, else undefined. */
+function topLevelStringProperty(object: string, name: string): string | undefined {
+  const key = new RegExp(`^(?:${name}|'${name}'|"${name}")\\s*:\\s*`, 'u');
+  let depth = 0;
+  let i = 1; // past the opening brace
+  const end = object.length - 1;
+  while (i < end) {
+    const skipped = skipCommentOrString(object, i);
+    if (skipped === -1) return undefined;
+    if (skipped !== i) { i = skipped; continue; }
+    const ch = object[i]!;
+    if (ch === '(' || ch === '{' || ch === '[') { depth += 1; i += 1; continue; }
+    if (ch === ')' || ch === '}' || ch === ']') { depth -= 1; i += 1; continue; }
+    if (depth === 0 && (i === 1 || /[\s,{/]/u.test(object[i - 1]!))) {
+      const match = key.exec(object.slice(i));
+      if (match !== null) {
+        const valueStart = i + match[0].length;
+        const quote = object[valueStart];
+        if (quote !== '"' && quote !== "'" && quote !== '`') return undefined;
+        const valueEnd = stringEnd(object, valueStart);
+        if (valueEnd === -1) return undefined;
+        const raw = object.slice(valueStart + 1, valueEnd);
+        // An interpolated template is computed; a plain one is a literal.
+        return quote === '`' && /\$\{/u.test(raw) ? undefined : raw.replace(/\\(.)/gu, '$1');
+      }
+    }
+    i += 1;
+  }
+  return undefined;
+}
+
 interface WorkerCall { detail: string; cli?: string }
 
 /**

package/src/human-to.ts

@@ -0,0 +1,71 @@
+/**
+ * Who an `f.human(question, { to })` question is for, parsed from the
+ * author's `to` string. This is the delivery contract Cloud reads (the local
+ * kit records it, Cloud delivers it), so the forms are fixed here and
+ * documented in docs/SURFACE.md §5 Human gates:
+ *
+ *   "slack:#eng"        → post in the Slack channel; anyone there may answer
+ *   "slack:@khaliq"     → DM the Slack user; only they may answer
+ *   "github:@khaliq"    → comment on the triggering issue / pull request,
+ *                         mentioning the handle; only they may answer
+ *   "khaliq"            → the deploy's approver, on whichever channel the run
+ *                         was triggered from (Cloud resolves; the local kit
+ *                         only records it)
+ *
+ * Anything else — an unknown provider (`email:x`), a provider with no target
+ * (`slack:`), a GitHub channel (`github:#eng`), a target with whitespace or
+ * other characters no handle carries — is refused as `human_to_invalid`
+ * rather than turned into a delivery target that would silently reach no one.
+ */
+export type HumanRecipient =
+  | { readonly provider: 'slack'; readonly kind: 'channel' | 'user'; readonly target: string }
+  | { readonly provider: 'github'; readonly kind: 'user'; readonly target: string }
+  | { readonly provider: 'approver'; readonly kind: 'user'; readonly target: string };
+
+export type HumanRecipientParse =
+  | { readonly ok: true; readonly recipient: HumanRecipient }
+  | { readonly ok: false; readonly reason: string };
+
+/** A Slack channel name, or a Slack / GitHub / approver handle: one word, no spaces or quotes. */
+const TARGET = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/u;
+const PROVIDER_FORM = /^([A-Za-z][A-Za-z0-9_-]*)\s*:(.*)$/su;
+
+export function parseHumanTo(to: string): HumanRecipientParse {
+  const trimmed = to.trim();
+  if (trimmed === '') return { ok: false, reason: 'to is empty' };
+  const match = PROVIDER_FORM.exec(trimmed);
+  if (match === null) {
+    const target = trimmed.replace(/^@/u, '');
+    if (!TARGET.test(target)) return { ok: false, reason: `"${trimmed}" is not a handle (one word: letters, digits, . _ -)` };
+    return { ok: true, recipient: { provider: 'approver', kind: 'user', target } };
+  }
+  const provider = match[1]!.toLowerCase();
+  const rest = match[2]!.trim();
+  if (provider !== 'slack' && provider !== 'github') {
+    return { ok: false, reason: `"${provider}:" is not a delivery provider; use "slack:#channel", "slack:@user", "github:@user" or a bare approver handle` };
+  }
+  if (rest === '') return { ok: false, reason: `"${provider}:" names no ${provider === 'slack' ? 'channel or user' : 'user'}` };
+  if (rest.startsWith('#')) {
+    if (provider === 'github') return { ok: false, reason: `"${trimmed}": GitHub has no channels; use "github:@user"` };
+    const target = rest.slice(1);
+    if (!TARGET.test(target)) return { ok: false, reason: `"${trimmed}" is not a Slack channel name` };
+    return { ok: true, recipient: { provider: 'slack', kind: 'channel', target } };
+  }
+  const target = rest.replace(/^@/u, '');
+  if (!TARGET.test(target)) return { ok: false, reason: `"${trimmed}" is not a ${provider === 'slack' ? 'Slack' : 'GitHub'} handle` };
+  return { ok: true, recipient: { provider, kind: 'user', target } };
+}
+
+/** The parsed recipient of a `to` already accepted by `f.human` (`parseHumanTo` ok). */
+export function parseHumanRecipient(to: string): HumanRecipient {
+  const parsed = parseHumanTo(to);
+  if (!parsed.ok) throw new Error(`f.human to ${parsed.reason}`);
+  return parsed.recipient;
+}
+
+/** The Cloud integration a recipient needs connected: none for the approver, none for a malformed `to`. */
+export function humanRecipientProvider(to: string): 'slack' | 'github' | undefined {
+  const parsed = parseHumanTo(to);
+  if (!parsed.ok || parsed.recipient.provider === 'approver') return undefined;
+  return parsed.recipient.provider;
+}

package/src/index.ts

@@ -86,6 +86,7 @@ export {
   flowRequirements, describeFlowRequirements, harnessFromCli, FLOW_HARNESSES,
   type FlowRequirements, type FlowRequirementsContext, type FlowIntegrationRequirement, type FlowHarnessRequirement, type FlowHarness,
 } from './flow-requirements.js';
+export { parseHumanTo, parseHumanRecipient, humanRecipientProvider, type HumanRecipient, type HumanRecipientParse } from './human-to.js';
 
 export { canonicalize, specHash } from './canonical.js';
 export {