@relayflows/sdk 2.0.30 → 2.0.32

package/src/helper-reference.ts

@@ -0,0 +1,130 @@
+import { parse, parseExpressionAt } from 'acorn';
+
+/**
+ * Which `f.<namespace>` helpers a flow body actually USES.
+ *
+ * Read from a parse, not from the text. A helper merely NAMED in a string, a
+ * comment, a template quasi or a regex is not used, and declaring a
+ * requirement from one refuses a flow for a mount it never touches:
+ * `f.run("echo f.gitlab")`, an agent prompt naming `f.slack`, or a PR title in
+ * a commit message were each enough to demand a GitLab mount.
+ *
+ * This was first written as a lexer that blanked comments, strings and
+ * regexes. That is the wrong tool: `/` is a regex or a division depending on
+ * whether the preceding token ends an expression, which is not decidable
+ * without parse context, and the two shapes that ambiguity broke —
+ * interpolations (`${await f.gitlab…}`) and a quote inside a regex (`/'/`) —
+ * both HID real helper use, deploying a flow without its mount to fail at
+ * runtime. A parser settles every one of those by construction.
+ *
+ * What a parser still cannot see is indirection: `const p = 'gitlab';
+ * f[p].issues…` is invisible to any static reading, because it needs value
+ * tracking. This scan is therefore a convenience for the literal case, never
+ * the authority — `header.tools[namespace] === true` is the declaration that
+ * is, and it short-circuits this entirely.
+ */
+export function helperNamespacesUsed(body: string, root: string): ReadonlySet<string> {
+  const program = parseFlowBody(body);
+  if (program === null) return textFallback(body, root);
+  const used = new Set<string>();
+  walk(program, (node) => {
+    if (node.type !== 'MemberExpression') return;
+    const object = node.object as AstNode | undefined;
+    if (object?.type !== 'Identifier' || object.name !== root) return;
+    const namespace = memberName(node);
+    if (namespace !== undefined) used.add(namespace);
+  });
+  return used;
+}
+
+/** `f.slack`, `f["slack"]`, `f?.slack` — but not `f[variable]`, which is unknowable. */
+function memberName(node: AstNode): string | undefined {
+  const property = node.property as AstNode | undefined;
+  if (property === undefined) return undefined;
+  if (node.computed !== true) return property.type === 'Identifier' ? property.name : undefined;
+  return property.type === 'Literal' && typeof property.value === 'string' ? property.value : undefined;
+}
+
+/**
+ * Parse whatever `Function.prototype.toString()` produced.
+ *
+ * It can be an arrow, a function expression, an async method shorthand from an
+ * object literal, or a declaration — only some of which are expressions, so
+ * each shape gets a try. Types are already stripped by the time a body reaches
+ * here (Node strips before evaluating, and bundlers transpile), so this is
+ * plain JavaScript.
+ */
+function parseFlowBody(body: string): AstNode | null {
+  const options = { ecmaVersion: 'latest' as const, allowAwaitOutsideFunction: true, allowReturnOutsideFunction: true };
+  // `parseExpressionAt` stops at the end of the first expression and does not
+  // object to what follows, so `async post(f) { … }` parses as the identifier
+  // `async` and reports success having read three characters. Every attempt
+  // must therefore consume the whole source, or a method body would be walked
+  // as its own name and declare no helpers at all.
+  const whole = (source: string, node: AstNode): AstNode => {
+    const end = typeof node.end === 'number' ? node.end : -1;
+    if (end < 0 || source.slice(end).trim() !== '') throw new SyntaxError('unconsumed input');
+    return node;
+  };
+  for (const attempt of [
+    () => whole(body, parseExpressionAt(body, 0, options) as unknown as AstNode),
+    () => whole(`(${body})`, parseExpressionAt(`(${body})`, 0, options) as unknown as AstNode),
+    () => parse(body, options) as unknown as AstNode,
+    // An object-literal method (`async post(f) { … }`) is neither expression
+    // nor statement on its own; it only parses inside an object.
+    () => whole(`({${body}})`, parseExpressionAt(`({${body}})`, 0, options) as unknown as AstNode),
+  ]) {
+    try {
+      return attempt();
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Last resort when nothing parses: match the text.
+ *
+ * Deliberately the permissive direction. An unparseable body is a shape this
+ * code does not understand, and under-reporting would deploy a flow without a
+ * mount it needs and fail at the call; over-reporting only asks for a mount
+ * that may go unused. Reaching here at all is a bug worth hearing about.
+ */
+function textFallback(body: string, root: string): ReadonlySet<string> {
+  const used = new Set<string>();
+  const escaped = root.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+  const pattern = new RegExp(`(?:^|[^\\w$.])${escaped}\\s*(?:\\.\\s*([\\w$]+)|\\[\\s*['"]([^'"]+)['"]\\s*\\])`, 'gu');
+  for (const match of body.matchAll(pattern)) {
+    const namespace = match[1] ?? match[2];
+    if (namespace !== undefined) used.add(namespace);
+  }
+  return used;
+}
+
+type AstNode = {
+  type: string;
+  end?: number;
+  name?: string;
+  value?: unknown;
+  computed?: boolean;
+  [key: string]: unknown;
+};
+
+/** Depth-first over every child node, without pulling in a second package. */
+function walk(node: AstNode, visit: (node: AstNode) => void): void {
+  visit(node);
+  for (const key of Object.keys(node)) {
+    if (key === 'type' || key === 'start' || key === 'end' || key === 'loc') continue;
+    const child = node[key];
+    if (Array.isArray(child)) {
+      for (const entry of child) if (isNode(entry)) walk(entry, visit);
+    } else if (isNode(child)) {
+      walk(child, visit);
+    }
+  }
+}
+
+function isNode(value: unknown): value is AstNode {
+  return typeof value === 'object' && value !== null && typeof (value as { type?: unknown }).type === 'string';
+}

package/src/hosted-extension-runtime.ts

@@ -26,7 +26,7 @@ const REALPATH = realpath;
 const PATH_DIRNAME = dirname;
 const PATH_JOIN = join;
 const PATH_RESOLVE = resolve;
-const SOFTWARE_FACTORY_SHA256 = '49c993220b9c34fab2d4b0e51911656f62b8b657f534d988691960d45bb9d9b6';
+const SOFTWARE_FACTORY_SHA256 = 'b97a3466c2affabb61afa655d4b2f726942d753c0466740b64ba26a78da359c6';
 const ARRAY_IS_ARRAY = Array.isArray;
 const OBJECT_FREEZE = Object.freeze;
 const WEAK_MAP_GET = Function.prototype.call.bind(WeakMap.prototype.get) as <K extends object, V>(

package/src/index.ts

@@ -34,6 +34,8 @@ export type {
   LlmStepSpec,
   NamedAgentSpec,
   NamedDataGate,
+  OnNonZero,
+  StepsGreenGate,
   ReferencesInputGate,
   SubprocessGate,
   WordCountBoundsGate,

package/src/journal-client.ts

@@ -51,6 +51,7 @@ interface Pending {
 /** A structured rejection returned by relayflowd over the journal protocol. */
 export class JournalProtocolError extends Error {
   readonly code: string;
+  verb?: string;
 
   constructor(code: string, message: string) {
     super(`${code}: ${message}`);
@@ -223,12 +224,19 @@ export class JournalClient extends EventEmitter {
    * Validate a compiled kernel-dialect spec (zero-agent flows legal), create
    * the run file, and append `run.spawned`. Authoring specs must be compiled
    * with `toKernelSpec` before crossing this journal-protocol boundary.
+   * `watch` streams the run's entries as `'entry'` events while it runs.
    */
-  runStart(spec: KernelRunSpec, reuseFromRunId?: string, admissionKey?: string): Promise<VerbContract['run.start']['result']> {
+  runStart(
+    spec: KernelRunSpec,
+    reuseFromRunId?: string,
+    admissionKey?: string,
+    watch = false,
+  ): Promise<VerbContract['run.start']['result']> {
     return this.request('run.start', {
       spec,
       ...(reuseFromRunId === undefined ? {} : { reuse_from_run_id: reuseFromRunId }),
       ...(admissionKey === undefined ? {} : { admission_key: admissionKey }),
+      ...(watch ? { watch: true } : {}),
     }, null);
   }
 
@@ -370,6 +378,9 @@ export class JournalClient extends EventEmitter {
       step_id: stepId,
       attempt,
       lease_id: leaseId,
+    }).catch(error => {
+      if (error instanceof JournalProtocolError) error.verb = 'step.heartbeat';
+      throw error;
     });
   }
 
@@ -401,7 +412,10 @@ export class JournalClient extends EventEmitter {
       idempotency_key: idempotencyKey,
       completionReason,
       ...extra,
-    }, null);
+    }, null).catch(error => {
+      if (error instanceof JournalProtocolError) error.verb = 'step.complete';
+      throw error;
+    });
   }
 
   /** Satisfy `wait.event`; a human response arrives here too. */
@@ -422,6 +436,9 @@ export class JournalClient extends EventEmitter {
       attempt,
       idempotency_key: idempotencyKey,
       ...wait,
+    }).catch(error => {
+      if (error instanceof JournalProtocolError) error.verb = 'step.wait';
+      throw error;
     });
   }
 

package/src/journal-projection.ts

@@ -0,0 +1,106 @@
+/**
+ * Fold a run's journal entries, as `run.start {watch}` or `run.watch` pushes
+ * them, into a `RunProjection`: `run.spawned` opens it with the declared step
+ * graph, attempt starts and completions become step transitions, and
+ * `run.completed` closes it. Entries journaled before `liveSinceMs` (a resume
+ * replaying history) update the snapshot without publishing a message each.
+ */
+
+import type { JournalEvent } from './journal-reader.js';
+import type { ProgressEvent } from './progress.js';
+import type { DeclaredStep, RunProjection, RunSnapshot } from './run-projection.js';
+import type { StepType } from './spec.js';
+
+export type OpenProjection = (run: { runId: string; flow: string; steps: DeclaredStep[] }) => RunProjection;
+
+export function createJournalProjector(open: OpenProjection, liveSinceMs = 0): (entry: JournalEvent) => void {
+  let projection: RunProjection | undefined;
+  const types = new Map<string, StepType>();
+  const started = new Map<string, number>();
+  const parked = new Set<string>();
+
+  return entry => {
+    const payload = (entry.payload ?? {}) as Record<string, unknown>;
+    const live = entry.at_ms >= liveSinceMs;
+    if (entry.entry_type === 'run.spawned') {
+      if (projection !== undefined) return;
+      const spec = (payload['spec'] ?? {}) as { name?: unknown; steps?: unknown };
+      const steps = (Array.isArray(spec.steps) ? spec.steps : []).flatMap(declaredStep);
+      for (const step of steps) types.set(step.id, step.type);
+      projection = open({ runId: entry.run_id, flow: typeof spec.name === 'string' ? spec.name : 'flow', steps });
+      return;
+    }
+    if (projection === undefined) return;
+    if (entry.entry_type === 'epoch.summary') {
+      started.clear();
+      parked.clear();
+      const done = (payload['steps_done'] ?? {}) as Record<string, { completionReason?: string }>;
+      const pending = (payload['steps_open'] ?? {}) as Record<string, { state?: string; attempt?: number }>;
+      projection.epoch([
+        ...Object.entries(done).map(([id, value]) => ({ id,
+          state: value.completionReason === 'success' ? 'completed' as const : 'failed' as const,
+          completionReason: value.completionReason })),
+        ...Object.entries(pending).map(([id, value]) => ({ id, attempt: value.attempt,
+          state: value.state === 'running' ? 'running' as const : value.state === 'needs_human' ? 'parked' as const : 'pending' as const })),
+      ], live);
+      return;
+    }
+    if (entry.step_id === null && entry.entry_type !== 'run.completed') return;
+    const stepId = entry.step_id ?? '';
+    const stepType = types.get(stepId) ?? 'deterministic';
+    const attempt = entry.attempt ?? undefined;
+    const key = `${stepId}#${attempt ?? 0}`;
+    const event = (type: ProgressEvent['type'], completionReason?: string): void => {
+      const elapsedMs = type === 'step.started' ? 0 : entry.at_ms - (started.get(key) ?? entry.at_ms);
+      projection!.step({
+        type, stepId, stepType, elapsedMs,
+        ...(attempt === undefined ? {} : { attempt }),
+        ...(completionReason === undefined ? {} : { completionReason: completionReason as never }),
+      }, live);
+    };
+    switch (entry.entry_type) {
+      case 'step.attempt.started':
+        parked.delete(key);
+        started.set(key, entry.at_ms);
+        event('step.started');
+        return;
+      case 'wait.human':
+        if (parked.has(key)) return;
+        parked.add(key);
+        event('step.parked');
+        return;
+      case 'step.completed': {
+        const reason = typeof payload['completionReason'] === 'string' ? payload['completionReason'] : undefined;
+        const isParked = payload['disposition'] === 'park';
+        if (isParked && parked.has(key)) return;
+        if (isParked) parked.add(key);
+        event(isParked ? 'step.parked' : reason === 'success' ? 'step.completed' : 'step.failed', reason);
+        return;
+      }
+      case 'run.completed': {
+        // Historical outcomes belong to earlier epochs. The current resume's
+        // report closes the projection if no new terminal entry is appended.
+        if (!live) return;
+        const reason = typeof payload['completionReason'] === 'string' ? payload['completionReason'] : undefined;
+        projection.finish({ status: runStatus(reason), ...(reason === undefined ? {} : { completionReason: reason }) });
+        return;
+      }
+    }
+  };
+}
+
+function declaredStep(value: unknown): DeclaredStep[] {
+  if (typeof value !== 'object' || value === null) return [];
+  const step = value as { id?: unknown; type?: unknown; depends_on?: unknown };
+  if (typeof step.id !== 'string') return [];
+  const type = step.type === 'llm' || step.type === 'agent' ? step.type : 'deterministic';
+  const dependsOn = Array.isArray(step.depends_on)
+    ? step.depends_on.filter((id): id is string => typeof id === 'string') : [];
+  return [{ id: step.id, type, dependsOn }];
+}
+
+function runStatus(reason: string | undefined): RunSnapshot['status'] {
+  if (reason === 'success') return 'completed';
+  if (reason === 'canceled') return 'canceled';
+  return 'failed';
+}

package/src/llm-worker.ts

@@ -46,7 +46,7 @@ export class LlmWorker extends EventEmitter {
 
   private readonly onDispatch = (dispatch: StepDispatchEvent): void => {
     if (this.closing || dispatch.step_type !== 'llm') return;
-    const running = this.execute(dispatch).catch(error => { this.emit('error', error); });
+    const running = this.execute(dispatch).catch(error => { this.emit('error', error, dispatch); });
     this.inFlight.add(running);
     void running.finally(() => { this.inFlight.delete(running); });
   };

package/src/local-agent.ts

@@ -1,3 +1,4 @@
+import { onWorkerFailure } from './worker-lease.js';
 import { randomUUID } from 'node:crypto';
 import type { JournalClient } from './journal-client.js';
 import { AgentWorker } from './worker.js';
@@ -10,6 +11,7 @@ export async function attachLocalAgent(
   onPtyReady?: (path: string) => void,
   requestedStream?: string,
   capacity: number = DEFAULT_LOCAL_AGENT_CAPACITY,
+  runRoot?: string,
 ): Promise<{
   stream: string;
   readonly failure: unknown;
@@ -24,12 +26,12 @@ export async function attachLocalAgent(
     // second parking behind the first. Authored bodies size their admission to
     // this same number (worker-slots.ts), so they never ask for more.
     capacity,
-    dataDir, onPtyReady,
+    dataDir, onPtyReady, runRoot,
     pins: { workspace: [], streams: [{ stream, read_offset: 0 }] },
   });
   let failure: unknown;
   // The cause travels with the close, so the flow's next request names it.
-  worker.on('error', error => { failure = error; client.close(error); });
+  worker.on('error', onWorkerFailure('local-agent', error => { failure = error; client.close(error); }));
   await worker.attach();
   return {
     stream,

package/src/named-gate-lowering.ts

@@ -71,19 +71,33 @@ process.exit(artifacts.includes(${JSON.stringify(gate.path)})?0:1);`)}`;
   }
   const path = gate.type === 'subprocess_gate' ? gate.from_output
     : gate.type === 'word_count_bounds' ? undefined : gate.in_output_at;
+  const pathKey = gate.type === 'subprocess_gate' ? 'from_output' : 'in_output_at';
   // Only compiler-owned code is serialized. Author strings are JSON literals;
   // upstream output travels exclusively through FLOWS_INPUT, never shell text.
+  //
+  // `fail` answers a gate that exits 1 having said nothing. Every exit that is
+  // NOT the author's own predicate or command verdict goes through it: a
+  // selection that missed, input the child cannot carry, a child that never
+  // started, a child killed by a signal. It writes ONE bounded line to fd 2
+  // and nothing to fd 1 — `references_input` and `word_count_bounds` verify
+  // against stdout, so a stray byte there would change a verdict.
+  //
+  // `writeSync` rather than `process.stderr.write`: on a pipe the latter is
+  // asynchronous, and the `process.exit` on the same line would drop the
+  // diagnostic exactly when it is the only account of the failure there is.
   const setup = `const cp=require('node:child_process');
+const fail=m=>{require('node:fs').writeSync(2,${JSON.stringify(`${gate.type}: `)}+m.replace(/[\\r\\n]+/g,' ').slice(0,400)+'\\n');process.exit(1);};
 const input=JSON.parse(process.env.FLOWS_INPUT);
 let value=input.output;
 const path=${JSON.stringify(path ?? null)};
 if(path!==null){for(const key of path){
 if(value===null||typeof value!=='object'||!Object.hasOwn(value,key)||
-(typeof key==='number'?!Array.isArray(value):Array.isArray(value)))process.exit(1);
+(typeof key==='number'?!Array.isArray(value):Array.isArray(value)))
+fail(${JSON.stringify(`${pathKey} ${JSON.stringify(path ?? null)} selected nothing: no `)}+JSON.stringify(key)+' at that position in the producer output');
 value=value[key];
 }}else if(${deterministic})value=value.stdout_tail;
 const text=typeof value==='string'?value:JSON.stringify(value);
-if(typeof text!=='string')process.exit(1);
+if(typeof text!=='string')fail('the selected value could not be read as text');
 `;
   let body: string;
   switch (gate.type) {
@@ -93,16 +107,32 @@ if(typeof reference!=='string'||reference.length===0||!text.includes(reference))
 process.stdout.write('references_input:pass');`;
       break;
     case 'subprocess_gate':
-      body = `if(text.includes('\\0'))process.exit(1);
+      // `stdio: 'inherit'` hands the child the gate step's own stdout/stderr,
+      // which ARE the kernel's capture pipes (relayflowd/src/exec_det.rs:78),
+      // so the command's output is journaled as it is produced — including
+      // whatever it wrote before a timeout killed the process group. Buffering
+      // it for a post-wait flush would lose exactly that. What was missing is
+      // below: `status` is null for every outcome that is not an exit, and all
+      // of them used to collapse into an indistinguishable bare `exit 1`.
+      body = `if(text.includes('\\0'))fail('the selected text contains a NUL byte and cannot be passed to the gate command');
 const result=cp.spawnSync('/bin/sh',['-c',${JSON.stringify(gate.command)}],{
 env:{...process.env,INPUT:text},stdio:'inherit'});
+if(result.error)fail('could not run the gate command: '+(result.error.code||result.error.message)+' (the selected input was '+Buffer.byteLength(text)+' bytes)');
+if(result.signal)fail('the gate command was terminated by '+result.signal);
 process.exit(result.status===0?0:1);`;
       break;
     case 'word_count_bounds':
+      // The other gate that spawns a child. Its `wc` stderr was piped and then
+      // discarded, so a broken or absent `wc` was reported as a word count out
+      // of bounds. A bounded suffix of what it said travels with the cause.
       body = `const result=cp.spawnSync('wc',['-w'],{input:text,encoding:'utf8',env:{...process.env,LC_ALL:'C'}});
-if(result.status!==0)process.exit(1);
+const noise=(result.stderr||'').trim().slice(-200);
+const said=noise===''?'':': '+noise;
+if(result.error)fail('could not run wc -w: '+(result.error.code||result.error.message)+said);
+if(result.signal)fail('wc -w was terminated by '+result.signal+said);
+if(result.status!==0)fail('wc -w exited '+result.status+said);
 const count=result.stdout.trim();
-if(!/^[0-9]+$/.test(count))process.exit(1);
+if(!/^[0-9]+$/.test(count))fail('wc -w printed '+JSON.stringify(count.slice(0,80))+' instead of a word count'+said);
 process.stdout.write(BigInt(count).toString());`;
       break;
     case 'regex_match':

package/src/named-gate-preflight.ts

@@ -0,0 +1,47 @@
+import { unscannedArtifactPrefix } from './artifact-scan-policy.js';
+import { isNamedGate } from './named-gates.js';
+import type { StepSpec } from './spec.js';
+import type { PreflightWarning } from './preflight.js';
+
+/**
+ * Static named-gate scan coverage, decided from the compiled snapshot alone.
+ *
+ * An `artifact_exists` gate lowers to a deterministic step that asks whether
+ * the producer's journaled `output.artifacts` list contains the literal path
+ * (`named-gate-lowering.ts`). One writer of that list is the bundled agent
+ * worker's filesystem scan, which walks the step's cwd under the policy in
+ * `artifact-scan-policy.ts` and records nothing under a dot-named or
+ * `node_modules` entry. A path inside one of those prefixes can never come
+ * from that scan, on any host, in any environment.
+ *
+ * A warning rather than a refusal, because the scan is not the only writer.
+ * The same bundled worker promotes object-shaped JSON stdout — and a completed
+ * Relay task's output — straight to the journaled `output` (`worker.ts`), so
+ * an agent that reports its own `artifacts` array makes a hidden path pass;
+ * the journal protocol lets a custom worker do the same. Which of those an
+ * `agent` step will take is not decidable from the spec, so this reports the
+ * scan's limitation and leaves the verdict to the run rather than declaring a
+ * satisfiable gate impossible.
+ *
+ * Temporary: this describes #513. When the scan stops excluding these paths,
+ * delete this module and its call site.
+ */
+export function namedGateScanCoverageDiagnostics(step: StepSpec): PreflightWarning[] {
+  const gate = step.verification;
+  if (!isNamedGate(gate) || gate.type !== 'artifact_exists') return [];
+  // A malformed path is already `gate_path_invalid` from compilation; only
+  // validated relative POSIX paths reach here.
+  const prefix = unscannedArtifactPrefix(gate.path);
+  if (prefix === undefined) return [];
+  return [{
+    severity: 'warning',
+    kind: 'gate_path_unscanned',
+    stepId: step.id,
+    message: `Step "${step.id}" gates on artifact_exists path "${gate.path}", but the bundled agent worker's `
+      + `artifact scan records nothing under "${prefix}": it skips entries named `
+      + '".git", ".relayflowd" and "node_modules". The gate reads the journaled output.artifacts and never the disk, so '
+      + 'writing the file is not enough: the step has to report the path itself — as object-shaped JSON stdout '
+      + 'carrying its own "artifacts" array, as a completed Relay task output, or from a custom worker. If the '
+      + 'gate is meant to rest on the scan, write the artifact to a path the scan records.',
+  }];
+}

package/src/named-gates.ts

@@ -3,6 +3,9 @@ import type { NamedDataGate, VerificationSpec } from './spec.js';
 
 export const NAMED_GATE_FAILURE_KINDS = [
   'unknown_gate_kind', 'gate_pattern_invalid', 'gate_command_missing', 'gate_bound_invalid', 'gate_path_invalid',
+  // steps_green refusals: the gate is declarative like the named gates above,
+  // so it reports through the same kind channel a caller already switches on.
+  'gate_host_unsupported', 'gate_ids_invalid', 'gate_source_unsupported',
 ] as const;
 export type NamedGateFailureKind = typeof NAMED_GATE_FAILURE_KINDS[number];
 

package/src/observer-link.ts

@@ -238,6 +238,13 @@ export interface MintObserverOptions {
    * (default `https://agentrelay.com`). Separate axis from `baseUrl` — the
    * mint API lives on a different subdomain from the dashboard. */
   dashboardUrl?: string;
+  /**
+   * Scope the token to this one channel, so the dashboard opens on it — the
+   * run's `wf-<runId>` channel — rather than on whichever channel the
+   * workspace lists first. DMs are excluded: a run projects its
+   * conversation into that channel. Omitted: the whole workspace.
+   */
+  channel?: string;
   fetch?: ObserverFetch;
   now?: () => number;
   /** Called for the token's uniquely-suffixed name; injectable for tests. */
@@ -299,7 +306,9 @@ export async function mintObserverUrl(
     name: `flows-run-${uuid}`,
     description: 'Auto-minted by `flows run` for the observer dashboard link.',
     scopes: OBSERVER_SCOPES,
-    filters: { include_dms: true },
+    filters: options.channel === undefined
+      ? { include_dms: true }
+      : { channel_names: [options.channel], include_dms: false },
     expires_at: new Date(now() + OBSERVER_TOKEN_TTL_MS).toISOString(),
   };
 

package/src/package-version.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * Read the installed SDK package version from the manifest beside this module.
+ *
+ * The same relative URL works from `src/` during development and `dist/` in a
+ * built or npm-installed package. Reading the manifest at runtime keeps the
+ * CLI output tied to the bytes that are actually installed instead of a
+ * hardcoded release value that can drift between package files.
+ */
+export function packageVersion(): string {
+  try {
+    const manifest: unknown = JSON.parse(
+      readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+    );
+    const version = (manifest as { version?: unknown }).version;
+    return typeof version === 'string' && version.length > 0 ? version : '0.0.0';
+  } catch {
+    // Version display is cosmetic. Keep the CLI usable if a host strips the
+    // manifest from an otherwise runnable package artifact.
+    return '0.0.0';
+  }
+}