@relayflows/sdk 2.0.9 → 2.0.10

package/dist/named-gates.d.ts

@@ -0,0 +1,10 @@
+import type { NamedDataGate, VerificationSpec } from './spec.js';
+export declare const NAMED_GATE_FAILURE_KINDS: readonly ["unknown_gate_kind", "gate_pattern_invalid", "gate_command_missing", "gate_bound_invalid"];
+export type NamedGateFailureKind = typeof NAMED_GATE_FAILURE_KINDS[number];
+export declare const NAMED_GATE_KEYS: Record<NamedDataGate['type'], readonly string[]>;
+export declare function isNamedGate(gate: VerificationSpec | undefined): gate is NamedDataGate;
+export declare function regexFlags(flags: string): number;
+/** Called only on snapshotted data, including by the public validator. */
+export declare function namedGateErrors(gate: Record<string, unknown>, input: unknown, at: string): string[];
+export declare function namedGateFailure(errors: readonly string[]): NamedGateFailureKind | undefined;
+//# sourceMappingURL=named-gates.d.ts.map

package/dist/named-gates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"named-gates.d.ts","sourceRoot":"","sources":["../src/named-gates.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAEjE,eAAO,MAAM,wBAAwB,sGAE3B,CAAC;AACX,MAAM,MAAM,oBAAoB,GAAG,OAAO,wBAAwB,CAAC,MAAM,CAAC,CAAC;AAE3E,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAK5E,CAAC;AAEF,wBAAgB,WAAW,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,GAAG,IAAI,IAAI,aAAa,CAErF;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CA6CnG;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,oBAAoB,GAAG,SAAS,CAE5F"}

package/dist/named-gates.js

@@ -0,0 +1,69 @@
+import { RE2JS } from 're2js';
+export const NAMED_GATE_FAILURE_KINDS = [
+    'unknown_gate_kind', 'gate_pattern_invalid', 'gate_command_missing', 'gate_bound_invalid',
+];
+export const NAMED_GATE_KEYS = {
+    references_input: ['type', 'input_key', 'in_output_at'],
+    subprocess_gate: ['type', 'command', 'from_output'],
+    word_count_bounds: ['type', 'min', 'max'],
+    regex_match: ['type', 'pattern', 'in_output_at', 'flags'],
+};
+export function isNamedGate(gate) {
+    return gate !== undefined && Object.hasOwn(NAMED_GATE_KEYS, gate.type);
+}
+export function regexFlags(flags) {
+    return (flags.includes('i') ? RE2JS.CASE_INSENSITIVE : 0)
+        | (flags.includes('m') ? RE2JS.MULTILINE : 0)
+        | (flags.includes('s') ? RE2JS.DOTALL : 0);
+}
+/** Called only on snapshotted data, including by the public validator. */
+export function namedGateErrors(gate, input, at) {
+    const errors = [];
+    for (const key of ['in_output_at', 'from_output']) {
+        const path = gate[key];
+        if (path !== undefined && (!Array.isArray(path) || !path.every(segment => typeof segment === 'string' || (Number.isSafeInteger(segment) && segment >= 0)))) {
+            errors.push(`${at}.${key}: expected an array of object keys or non-negative integer indices`);
+        }
+    }
+    switch (gate.type) {
+        case 'references_input':
+            if (typeof gate.input_key !== 'string' || !gate.input_key.trim()
+                || input === null || typeof input !== 'object' || !Object.hasOwn(input, gate.input_key)) {
+                errors.push(`${at}.input_key: must name a declared input binding`);
+            }
+            break;
+        case 'subprocess_gate':
+            if (typeof gate.command !== 'string' || !gate.command.trim() || gate.command.includes('\0')) {
+                errors.push(`${at}.command: gate_command_missing: expected a non-empty shell command`);
+            }
+            break;
+        case 'word_count_bounds': {
+            const { min, max } = gate;
+            if ([min, max].some(n => n !== undefined && (!Number.isSafeInteger(n) || n < 0))
+                || (typeof min === 'number' && typeof max === 'number' && min > max)) {
+                errors.push(`${at}: gate_bound_invalid: min and max must be non-negative safe integers with min <= max`);
+            }
+            break;
+        }
+        case 'regex_match':
+            try {
+                if (typeof gate.pattern !== 'string' || gate.pattern.length > 8192) {
+                    throw new Error('pattern must be a string of at most 8192 characters');
+                }
+                const flags = gate.flags ?? '';
+                if (typeof flags !== 'string' || !/^(?!.*(.).*\1)[ims]*$/.test(flags)) {
+                    throw new Error('flags must be a non-repeating subset of i, m, s');
+                }
+                RE2JS.compile(gate.pattern, regexFlags(flags));
+            }
+            catch (error) {
+                errors.push(`${at}: gate_pattern_invalid: ${error instanceof Error ? error.message : 'invalid RE2 pattern'}`);
+            }
+            break;
+    }
+    return errors;
+}
+export function namedGateFailure(errors) {
+    return NAMED_GATE_FAILURE_KINDS.find(kind => errors.some(error => error.includes(`${kind}:`)));
+}
+//# sourceMappingURL=named-gates.js.map

package/dist/named-gates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"named-gates.js","sourceRoot":"","sources":["../src/named-gates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAG9B,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,mBAAmB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,oBAAoB;CACjF,CAAC;AAGX,MAAM,CAAC,MAAM,eAAe,GAAqD;IAC/E,gBAAgB,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,CAAC;IACvD,eAAe,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC;IACnD,iBAAiB,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC;IACzC,WAAW,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,CAAC;CAC1D,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,IAAkC;IAC5D,OAAO,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;UACrD,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;UAC3C,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,eAAe,CAAC,IAA6B,EAAE,KAAc,EAAE,EAAU;IACvF,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,aAAa,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CACvE,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAK,OAAkB,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/F,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,GAAG,oEAAoE,CAAC,CAAC;QAChG,CAAC;IACH,CAAC;IACD,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,kBAAkB;YACrB,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE;mBAC3D,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC1F,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,gDAAgD,CAAC,CAAC;YACrE,CAAC;YACD,MAAM;QACR,KAAK,iBAAiB;YACpB,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5F,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,oEAAoE,CAAC,CAAC;YACzF,CAAC;YACD,MAAM;QACR,KAAK,mBAAmB,CAAC,CAAC,CAAC;YACzB,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;YAC1B,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,IAAK,CAAY,GAAG,CAAC,CAAC,CAAC;mBACvF,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC;gBACvE,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,sFAAsF,CAAC,CAAC;YAC3G,CAAC;YACD,MAAM;QACR,CAAC;QACD,KAAK,aAAa;YAChB,IAAI,CAAC;gBACH,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;oBACnE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;gBACzE,CAAC;gBACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;gBAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;oBACtE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;gBACrE,CAAC;gBACD,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;YACjD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,2BAA2B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,qBAAqB,EAAE,CAAC,CAAC;YAChH,CAAC;YACD,MAAM;IACV,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAyB;IACxD,OAAO,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;AACjG,CAAC"}

package/dist/observer-link.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Observer-link support for `flows run`: mint a scoped read-only observer token
+ * from a Relaycast workspace admin key, then print
+ * `Observer: <url>?key=<ot_live_...>` on stdout so an operator can drop into the
+ * Relaycast observer dashboard with the live-stream credential pre-filled.
+ *
+ * The workspace admin key (`rk_live_*`) is refused by the realtime endpoint —
+ * only an `ot_live_*` observer token with `stream:read` may open the workspace
+ * stream. So we do the same thing the Relaycast observer dashboard does when a
+ * workspace admin logs in with their admin key: mint a fresh, uniquely-named,
+ * scoped, short-lived observer token on their behalf and hand *that* to the
+ * URL. The workspace admin key never leaves the operator's machine.
+ *
+ * Everything here is best-effort. A missing workspace key means "no observer
+ * link, silently" — this is a parity feature relaying v1's convenience, not a
+ * requirement of a local run. A mint failure emits a labeled diagnostic to
+ * stderr and continues; a run must never fail because the observer link failed.
+ */
+export interface ObserverLinkEnv {
+    workspaceKey?: string;
+    /** Base URL for the mint API (`POST /v1/observer-tokens`). */
+    baseUrl?: string;
+    /** Base URL for the observer dashboard the emitted link points at. */
+    dashboardUrl?: string;
+    /** `FLOWS_NO_OBSERVER=1` suppresses the mint even when a key is present. */
+    suppressed: boolean;
+}
+/**
+ * Path to the `agent-relay` local workspace-key store. Structure:
+ * `{ active: string, workspaces: { [name]: { key: string } } }`. Written
+ * by `agent-relay workspace set_key` / `agent-relay workspace join`; the
+ * canonical file the `@agent-relay/cloud` package reads via
+ * `resolveActiveWorkspaceKey`. Verified against
+ * `packages/cloud/src/workspace-store.ts` in `AgentWorkforce/relay`.
+ *
+ * Respects `AGENT_RELAY_HOME` so a caller can point at a different store
+ * for tests without touching the real one. Falls back to
+ * `~/.agentworkforce/relay/workspaces.json` -- the same default that
+ * package uses.
+ */
+export declare function agentRelayWorkspaceStorePath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Read the active workspace key from the `agent-relay cloud login` /
+ * `agent-relay workspace set_key` store. Returns `undefined` on every
+ * failure mode -- file absent, unreadable, malformed JSON, no active
+ * workspace, active workspace has no key, key is empty -- so the caller
+ * can silently fall through to "no observer link" the same way an unset
+ * `RELAYCAST_WORKSPACE_KEY` does.
+ *
+ * A file-shape mismatch is INTENTIONALLY not a hard error: `agent-relay`
+ * may extend this file in future without warning, and refusing a flow
+ * because a fallback credential store looked odd would be strictly worse
+ * than falling back to the explicit env var (which is the primary path).
+ */
+export declare function readAgentRelayWorkspaceKey(env?: NodeJS.ProcessEnv, readFile?: (path: string) => string): string | undefined;
+/**
+ * Options controlling `resolveObserverLinkEnv`'s fallback behavior. The
+ * `readWorkspaceKey` seam is what the tests inject to simulate presence,
+ * absence, and malformed shapes of the on-disk store without touching the
+ * real home directory.
+ */
+export interface ResolveObserverLinkEnvOptions {
+    readWorkspaceKey?: (env: NodeJS.ProcessEnv) => string | undefined;
+}
+/**
+ * Env-first observer link resolution with an `agent-relay` cloud fallback.
+ *
+ * Priority (from the task spec, explicit beats implicit):
+ * 1. `RELAYCAST_WORKSPACE_KEY` if set and non-empty.
+ * 2. Active workspace key from `~/.agentworkforce/relay/workspaces.json`
+ *    (populated by `agent-relay cloud login` + `agent-relay workspace
+ *    set_key`), when readable.
+ * 3. Nothing -- silent skip, same as an unset primary env var.
+ *
+ * `FLOWS_NO_OBSERVER=1` still suppresses regardless of source.
+ */
+export declare function resolveObserverLinkEnv(env?: NodeJS.ProcessEnv, options?: ResolveObserverLinkEnvOptions): ObserverLinkEnv;
+/**
+ * Read the observer-link config from the environment. Both trims and
+ * emptiness-checks the workspace key so a `RELAYCAST_WORKSPACE_KEY=` with no
+ * value reads the same as unset (no observer link, silently).
+ */
+export declare function readObserverLinkEnv(env?: NodeJS.ProcessEnv): ObserverLinkEnv;
+/**
+ * Minimal `fetch` shape we depend on. Kept structural so tests can inject a
+ * mock without pulling in a fetch replacement library.
+ */
+export type ObserverFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+export interface MintObserverOptions {
+    workspaceKey: string;
+    /** Base URL of the mint API (default `https://cast.agentrelay.com`). */
+    baseUrl?: string;
+    /** Base URL of the observer dashboard the returned URL points at
+     * (default `https://agentrelay.com`). Separate axis from `baseUrl` — the
+     * mint API lives on a different subdomain from the dashboard. */
+    dashboardUrl?: string;
+    fetch?: ObserverFetch;
+    now?: () => number;
+    /** Called for the token's uniquely-suffixed name; injectable for tests. */
+    uuid?: () => string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface MintObserverOutcome {
+    observerUrl?: string;
+    /**
+     * A short diagnostic to log when mint failed. `undefined` on success or on
+     * "no observer link is possible" (missing key/suppressed) so the caller can
+     * distinguish silent-skip from "warn about the miss".
+     */
+    warning?: string;
+}
+/**
+ * Mint an `ot_live_*` observer token via `POST /v1/observer-tokens` and return
+ * the observer dashboard URL that pre-fills it. Any failure — 4xx/5xx from the
+ * engine, malformed response, network error, timeout — returns a `warning`
+ * string and no URL. The caller must not fail the run on `warning`.
+ */
+export declare function mintObserverUrl(options: MintObserverOptions): Promise<MintObserverOutcome>;
+//# sourceMappingURL=observer-link.d.ts.map

package/dist/observer-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer-link.d.ts","sourceRoot":"","sources":["../src/observer-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA6CH,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAGR;AAaD;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,QAAQ,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAwB,GACnD,MAAM,GAAG,SAAS,CAwBpB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B;IAC5C,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,MAAM,GAAG,SAAS,CAAC;CACnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,6BAAkC,GAC1C,eAAe,CAYjB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,eAAe,CAiBjB;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KACE,OAAO,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9B,CAAC,CAAC;AAEH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;qEAEiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CA0E9B"}

package/dist/observer-link.js

@@ -0,0 +1,274 @@
+/**
+ * Observer-link support for `flows run`: mint a scoped read-only observer token
+ * from a Relaycast workspace admin key, then print
+ * `Observer: <url>?key=<ot_live_...>` on stdout so an operator can drop into the
+ * Relaycast observer dashboard with the live-stream credential pre-filled.
+ *
+ * The workspace admin key (`rk_live_*`) is refused by the realtime endpoint —
+ * only an `ot_live_*` observer token with `stream:read` may open the workspace
+ * stream. So we do the same thing the Relaycast observer dashboard does when a
+ * workspace admin logs in with their admin key: mint a fresh, uniquely-named,
+ * scoped, short-lived observer token on their behalf and hand *that* to the
+ * URL. The workspace admin key never leaves the operator's machine.
+ *
+ * Everything here is best-effort. A missing workspace key means "no observer
+ * link, silently" — this is a parity feature relaying v1's convenience, not a
+ * requirement of a local run. A mint failure emits a labeled diagnostic to
+ * stderr and continues; a run must never fail because the observer link failed.
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** Scopes the minted token carries. Mirrors the observer dashboard's set. */
+const OBSERVER_SCOPES = [
+    'stream:read',
+    'messages:read',
+    'threads:read',
+    'dms:read',
+    'channels:read',
+    'search:read',
+    'agents:read',
+    'nodes:read',
+    'deliveries:read',
+    'activity:read',
+    'files:read',
+    'reactions:read',
+];
+/** Token lifetime for a `flows run` session. 24h is well past the longest run. */
+const OBSERVER_TOKEN_TTL_MS = 60 * 60 * 24 * 1000;
+/**
+ * Default hosts for the two axes of the observer link. They are DIFFERENT
+ * subdomains and must not be conflated (empirically verified 2026-09-10):
+ *
+ * - Mint API: `POST cast.agentrelay.com/v1/observer-tokens`. `agentrelay.com`
+ *   returns 404 for this path. Overridable via `RELAYCAST_API_URL`.
+ * - Observer dashboard: `agentrelay.com/observer?key=<ot_live_...>`.
+ *   `cast.agentrelay.com/observer` returns 404. Overridable via
+ *   `RELAYCAST_DASHBOARD_URL`.
+ *
+ * An earlier fix collapsed both to `cast.agentrelay.com` and closed #278 for
+ * the mint half only; a demo verification then landed on the 404 dashboard
+ * URL. Keep the two constants distinct.
+ */
+const DEFAULT_RELAYCAST_MINT_URL = 'https://cast.agentrelay.com';
+const DEFAULT_RELAYCAST_DASHBOARD_URL = 'https://agentrelay.com';
+/** Bounded so a stalled Relaycast API cannot delay the RUN summary. */
+const MINT_TIMEOUT_MS = 5_000;
+/**
+ * Path to the `agent-relay` local workspace-key store. Structure:
+ * `{ active: string, workspaces: { [name]: { key: string } } }`. Written
+ * by `agent-relay workspace set_key` / `agent-relay workspace join`; the
+ * canonical file the `@agent-relay/cloud` package reads via
+ * `resolveActiveWorkspaceKey`. Verified against
+ * `packages/cloud/src/workspace-store.ts` in `AgentWorkforce/relay`.
+ *
+ * Respects `AGENT_RELAY_HOME` so a caller can point at a different store
+ * for tests without touching the real one. Falls back to
+ * `~/.agentworkforce/relay/workspaces.json` -- the same default that
+ * package uses.
+ */
+export function agentRelayWorkspaceStorePath(env = process.env) {
+    const dir = env['AGENT_RELAY_HOME'] ?? join(homedir(), '.agentworkforce/relay');
+    return join(dir, 'workspaces.json');
+}
+/**
+ * Read the active workspace key from the `agent-relay cloud login` /
+ * `agent-relay workspace set_key` store. Returns `undefined` on every
+ * failure mode -- file absent, unreadable, malformed JSON, no active
+ * workspace, active workspace has no key, key is empty -- so the caller
+ * can silently fall through to "no observer link" the same way an unset
+ * `RELAYCAST_WORKSPACE_KEY` does.
+ *
+ * A file-shape mismatch is INTENTIONALLY not a hard error: `agent-relay`
+ * may extend this file in future without warning, and refusing a flow
+ * because a fallback credential store looked odd would be strictly worse
+ * than falling back to the explicit env var (which is the primary path).
+ */
+export function readAgentRelayWorkspaceKey(env = process.env, readFile = defaultReadFile) {
+    let raw;
+    try {
+        raw = readFile(agentRelayWorkspaceStorePath(env));
+    }
+    catch {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const activeName = parsed.active;
+    if (typeof activeName !== 'string' || activeName === '')
+        return undefined;
+    const workspaces = parsed.workspaces;
+    if (typeof workspaces !== 'object' || workspaces === null)
+        return undefined;
+    const entry = workspaces[activeName];
+    if (typeof entry !== 'object' || entry === null)
+        return undefined;
+    const key = entry.key;
+    if (typeof key !== 'string')
+        return undefined;
+    const trimmed = key.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+function defaultReadFile(filePath) {
+    return readFileSync(filePath, 'utf8');
+}
+/**
+ * Env-first observer link resolution with an `agent-relay` cloud fallback.
+ *
+ * Priority (from the task spec, explicit beats implicit):
+ * 1. `RELAYCAST_WORKSPACE_KEY` if set and non-empty.
+ * 2. Active workspace key from `~/.agentworkforce/relay/workspaces.json`
+ *    (populated by `agent-relay cloud login` + `agent-relay workspace
+ *    set_key`), when readable.
+ * 3. Nothing -- silent skip, same as an unset primary env var.
+ *
+ * `FLOWS_NO_OBSERVER=1` still suppresses regardless of source.
+ */
+export function resolveObserverLinkEnv(env = process.env, options = {}) {
+    const primary = readObserverLinkEnv(env);
+    if (primary.workspaceKey !== undefined || primary.suppressed) {
+        return primary;
+    }
+    const readWorkspaceKey = options.readWorkspaceKey ?? readAgentRelayWorkspaceKey;
+    const fallback = readWorkspaceKey(env);
+    if (fallback === undefined)
+        return primary;
+    return {
+        ...primary,
+        workspaceKey: fallback,
+    };
+}
+/**
+ * Read the observer-link config from the environment. Both trims and
+ * emptiness-checks the workspace key so a `RELAYCAST_WORKSPACE_KEY=` with no
+ * value reads the same as unset (no observer link, silently).
+ */
+export function readObserverLinkEnv(env = process.env) {
+    const rawKey = env['RELAYCAST_WORKSPACE_KEY'];
+    const workspaceKey = typeof rawKey === 'string' ? rawKey.trim() : '';
+    const rawApi = env['RELAYCAST_API_URL'];
+    const baseUrl = typeof rawApi === 'string' && rawApi.trim() !== ''
+        ? rawApi.trim()
+        : undefined;
+    const rawDashboard = env['RELAYCAST_DASHBOARD_URL'];
+    const dashboardUrl = typeof rawDashboard === 'string' && rawDashboard.trim() !== ''
+        ? rawDashboard.trim()
+        : undefined;
+    return {
+        ...(workspaceKey !== '' ? { workspaceKey } : {}),
+        ...(baseUrl !== undefined ? { baseUrl } : {}),
+        ...(dashboardUrl !== undefined ? { dashboardUrl } : {}),
+        suppressed: env['FLOWS_NO_OBSERVER'] === '1',
+    };
+}
+/**
+ * Mint an `ot_live_*` observer token via `POST /v1/observer-tokens` and return
+ * the observer dashboard URL that pre-fills it. Any failure — 4xx/5xx from the
+ * engine, malformed response, network error, timeout — returns a `warning`
+ * string and no URL. The caller must not fail the run on `warning`.
+ */
+export async function mintObserverUrl(options) {
+    const doFetch = options.fetch ?? (globalThis.fetch);
+    if (typeof doFetch !== 'function') {
+        return { warning: 'no fetch implementation available' };
+    }
+    const rawApi = options.baseUrl ?? DEFAULT_RELAYCAST_MINT_URL;
+    const rawDashboard = options.dashboardUrl ?? DEFAULT_RELAYCAST_DASHBOARD_URL;
+    let mintUrl;
+    let observerBase;
+    try {
+        mintUrl = new URL('/v1/observer-tokens', rawApi);
+    }
+    catch {
+        return { warning: `invalid RELAYCAST_API_URL "${rawApi}"` };
+    }
+    try {
+        observerBase = new URL('/observer', rawDashboard);
+    }
+    catch {
+        return { warning: `invalid RELAYCAST_DASHBOARD_URL "${rawDashboard}"` };
+    }
+    const uuid = (options.uuid ?? defaultUuid)();
+    const now = options.now ?? (() => Date.now());
+    const timeoutMs = options.timeoutMs ?? MINT_TIMEOUT_MS;
+    const deadline = AbortSignal.timeout(timeoutMs);
+    const signal = options.signal
+        ? AbortSignal.any([options.signal, deadline])
+        : deadline;
+    const payload = {
+        name: `flows-run-${uuid}`,
+        description: 'Auto-minted by `flows run` for the observer dashboard link.',
+        scopes: OBSERVER_SCOPES,
+        filters: { include_dms: true },
+        expires_at: new Date(now() + OBSERVER_TOKEN_TTL_MS).toISOString(),
+    };
+    let response;
+    try {
+        response = await doFetch(mintUrl.toString(), {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${options.workspaceKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(payload),
+            signal,
+        });
+    }
+    catch (error) {
+        return { warning: `network error: ${errorMessage(error)}` };
+    }
+    if (!response.ok) {
+        return { warning: `mint API returned HTTP ${response.status}` };
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        return { warning: `malformed response: ${errorMessage(error)}` };
+    }
+    const token = pickToken(body);
+    if (token === undefined) {
+        return { warning: 'mint API response missing ot_live_ token' };
+    }
+    // `URL.searchParams.set` percent-encodes any exotic characters the token
+    // could carry. It also collapses the leading `/observer` path correctly.
+    observerBase.searchParams.set('key', token);
+    return { observerUrl: observerBase.toString() };
+}
+/**
+ * Pick `data.token` from a `POST /v1/observer-tokens` response, refusing any
+ * shape that is not a plain `ot_live_*` string. Anything else is treated as
+ * "response too weird to trust" and produces no URL.
+ */
+function pickToken(body) {
+    if (typeof body !== 'object' || body === null)
+        return undefined;
+    const data = body['data'];
+    if (typeof data !== 'object' || data === null)
+        return undefined;
+    const token = data['token'];
+    if (typeof token !== 'string' || !token.startsWith('ot_live_'))
+        return undefined;
+    return token;
+}
+function defaultUuid() {
+    // `crypto.randomUUID()` is available on every Node 20+ target the SDK
+    // supports. The token name is not a security surface — it only has to be
+    // unique per (workspace, name) — so the fallback is a plain timestamp.
+    const c = globalThis.crypto;
+    return c?.randomUUID?.() ?? String(Date.now());
+}
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return 'unknown error';
+}
+//# sourceMappingURL=observer-link.js.map

package/dist/observer-link.js.map

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

package/dist/plugin-loader.d.ts

@@ -0,0 +1,13 @@
+import type { Step } from '@relayflows/surface';
+import { type PluginManifest, type PluginVerb } from './plugin-manifest.js';
+export interface LoadedPlugin {
+    readonly directory: string;
+    readonly manifest: PluginManifest;
+}
+export declare function findPluginProject(start: string): string | undefined;
+export declare function readPlugin(directory: string, packageName: string): LoadedPlugin;
+export declare function probePlugin(plugin: LoadedPlugin, env?: NodeJS.ProcessEnv): Promise<void>;
+export declare function loadPlugins(start: string): Promise<readonly LoadedPlugin[]>;
+export declare function pluginHelpers(plugins: readonly LoadedPlugin[], invoke: (plugin: LoadedPlugin, verb: PluginVerb, args: unknown) => Step<unknown>): Record<string, unknown>;
+export declare function invokePlugin(plugin: LoadedPlugin, verb: PluginVerb, args: unknown, idempotencyKey: string): Promise<unknown>;
+//# sourceMappingURL=plugin-loader.d.ts.map

package/dist/plugin-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-loader.d.ts","sourceRoot":"","sources":["../src/plugin-loader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAEhD,OAAO,EAAiF,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAE3J,MAAM,WAAW,YAAY;IAAG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;CAAE;AAC/F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQnE;AACD,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,YAAY,CAS/E;AACD,wBAAsB,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAW3G;AACD,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CA2BjF;AACD,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAczK;AACD,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAIlI"}

package/dist/plugin-loader.js

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { Ajv } from 'ajv';
+import { snapshotJsonValue } from './json-value.js';
+import { assertSupportedPlugin, PluginError, pluginPackageName, validatePluginManifest } from './plugin-manifest.js';
+export function findPluginProject(start) {
+    let current = resolve(start);
+    for (;;) {
+        if (existsSync(join(current, 'flows.json')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+export function readPlugin(directory, packageName) {
+    const path = join(directory, 'flows-plugin.json');
+    if (!existsSync(path))
+        throw new PluginError('plugin_manifest_missing', `${packageName} has no flows-plugin.json.`);
+    let input;
+    try {
+        input = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new PluginError('plugin_manifest_invalid', `${packageName} manifest is unreadable or invalid JSON.`);
+    }
+    const manifest = validatePluginManifest(input, packageName);
+    assertSupportedPlugin(manifest);
+    return Object.freeze({ directory, manifest });
+}
+export async function probePlugin(plugin, env = process.env) {
+    for (const credential of plugin.manifest.preflight.credentials) {
+        if (!env[credential]?.trim())
+            throw new PluginError('plugin_credential_missing', `${plugin.manifest.name} requires ${credential}.`);
+    }
+    for (const server of plugin.manifest.preflight.servers) {
+        try {
+            const response = await fetch(server, { method: 'HEAD', signal: AbortSignal.timeout(5000) });
+            await response.body?.cancel();
+            if (!response.ok)
+                throw new Error('unsuccessful response');
+        }
+        catch {
+            throw new PluginError('plugin_server_unreachable', `${plugin.manifest.name} cannot reach ${server}.`);
+        }
+    }
+}
+export async function loadPlugins(start) {
+    const root = findPluginProject(start);
+    if (root === undefined)
+        return Object.freeze([]);
+    let config;
+    try {
+        config = JSON.parse(readFileSync(join(root, 'flows.json'), 'utf8'));
+    }
+    catch {
+        throw new PluginError('plugin_manifest_invalid', 'Invalid flows.json.');
+    }
+    if (config === null || typeof config !== 'object' || (config.plugins !== undefined && (!Array.isArray(config.plugins) || !config.plugins.every(p => typeof p === 'string')))) {
+        throw new PluginError('plugin_manifest_invalid', 'flows.json plugins must be package names.');
+    }
+    const scope = join(root, 'node_modules/@flows');
+    const names = new Set(config.plugins?.map(pluginPackageName));
+    if (existsSync(scope))
+        for (const name of readdirSync(scope).sort()) {
+            if (name.startsWith('helper-') && !names.has(`@flows/${name}`)) {
+                throw new PluginError('plugin_unlisted', `@flows/${name} is installed but not declared in flows.json plugins. Run flows add ${name}.`);
+            }
+        }
+    const plugins = [...names].sort().map(name => readPlugin(join(root, 'node_modules', name), name));
+    const namespaces = new Set();
+    for (const plugin of plugins) {
+        for (const namespace of new Set(plugin.manifest.verbs.map(v => v.namespace))) {
+            if (namespaces.has(namespace))
+                throw new PluginError('plugin_manifest_invalid', `Duplicate plugin namespace ${namespace}.`);
+            namespaces.add(namespace);
+        }
+        await probePlugin(plugin);
+        if (!existsSync(join(plugin.directory, 'src/index.js')))
+            throw new PluginError('plugin_manifest_invalid', `${plugin.manifest.name} requires src/index.js.`);
+    }
+    return Object.freeze(plugins);
+}
+export function pluginHelpers(plugins, invoke) {
+    const helpers = Object.create(null);
+    const ajv = new Ajv({ strict: false });
+    for (const plugin of plugins)
+        for (const verb of plugin.manifest.verbs) {
+            const validate = ajv.compile(verb.args);
+            const namespace = helpers[verb.namespace] ??= Object.create(null);
+            namespace[verb.method] = args => {
+                const snapshot = snapshotJsonValue(args, `f.${verb.namespace}.${verb.method} arguments`);
+                if (!validate(snapshot))
+                    throw new PluginError('plugin_manifest_invalid', `Invalid arguments for ${verb.namespace}.${verb.method}: ${ajv.errorsText(validate.errors)}`);
+                return invoke(plugin, verb, snapshot);
+            };
+        }
+    for (const helper of Object.values(helpers))
+        Object.freeze(helper);
+    return Object.freeze(helpers);
+}
+export async function invokePlugin(plugin, verb, args, idempotencyKey) {
+    const module = await import(pathToFileURL(join(plugin.directory, 'src/index.js')).href);
+    if (typeof module.execute !== 'function')
+        throw new Error('plugin_runtime_invalid: expected execute export');
+    return snapshotJsonValue(await module.execute(verb.namespace, verb.method, args, Object.freeze({ idempotencyKey })), 'plugin output');
+}
+//# sourceMappingURL=plugin-loader.js.map