@relayflows/sdk 2.0.33 → 2.0.35

package/src/cloud-mirror-step.ts

@@ -152,6 +152,8 @@ export interface MirroredJournal {
   children: string[];
   /** Authored graph hints by step id, from an authored root's step index. */
   hints: Map<string, { label?: string; after?: string[] }>;
+  /** Authored completion receipts are durable evidence, not graph nodes. */
+  hidden: string[];
 }
 
 type Payload = Record<string, unknown>;
@@ -507,6 +509,7 @@ export function mirrorJournal(
     transcripts,
     children: index.children,
     hints: index.hints,
+    hidden: index.hidden,
   };
 }
 
@@ -522,7 +525,11 @@ export function mirrorJournal(
 function authoredIndex(
   events: readonly JournalEvent[],
   env: NodeJS.ProcessEnv,
-): { children: string[]; hints: Map<string, { label?: string; after?: string[] }> } {
+): {
+  children: string[];
+  hints: Map<string, { label?: string; after?: string[] }>;
+  hidden: string[];
+} {
   const messages: unknown[] = [];
   for (const event of events) {
     if (event.entry_type !== 'stream.appended') continue;
@@ -531,8 +538,15 @@ function authoredIndex(
   }
   const children: string[] = [];
   const hints = new Map<string, { label?: string; after?: string[] }>();
+  const hidden: string[] = [];
   for (const entry of foldAuthoredStepRecords(messages).values()) {
     if (/^[A-Za-z0-9][A-Za-z0-9_-]*$/u.test(entry.runId)) children.push(entry.runId);
+    // This is the executor's durable verdict receipt, not an authored unit of
+    // work. Only an entry in the authored root index can be hidden here, so a
+    // declarative step coincidentally named `complete-N` remains visible.
+    if (/(?:^|--)complete-[1-9][0-9]*$/.test(entry.step)) {
+      hidden.push(`${entry.runId}/${entry.step}`);
+    }
     const name = label(entry.label, env);
     const after = entry.after === undefined
       ? undefined
@@ -546,7 +560,7 @@ function authoredIndex(
       ...(after === undefined ? {} : { after }),
     });
   }
-  return { children, hints };
+  return { children, hints, hidden };
 }
 
 /**

package/src/cloud-mirror.ts

@@ -287,6 +287,7 @@ export function createRunMirror(options: RunMirrorOptions): RunMirror {
   const finals = new Map<string, { journalRunId: string; row: FinalStep }>();
   const transcripts = new Map<string, { stepName: string; attempts: Array<{ attempt: number; path: string }> }>();
   const hints = new Map<string, { label?: string; after?: string[] }>();
+  const hidden = new Set<string>();
   /** Live steps the cache cap dropped, by identity, so a capped view owns up to it. */
   const evicted = new Set<string>();
   /** Finished steps past the report cap, by identity. Counted, never sent. */
@@ -318,6 +319,7 @@ export function createRunMirror(options: RunMirrorOptions): RunMirror {
 
   const remember = (journalRunId: string, step: SnapshotStep, order: number): void => {
     const key = `${journalRunId}/${step.stepName}`;
+    if (hidden.has(key)) return;
     const existing = steps.get(key);
     const changed = existing === undefined || fingerprint(existing.step) !== fingerprint(step);
     steps.set(key, { step, order, changedAt: changed ? now() : existing!.changedAt });
@@ -365,19 +367,30 @@ export function createRunMirror(options: RunMirrorOptions): RunMirror {
         continue;
       }
       for (const child of folded.children) admit(child);
+      for (const key of folded.hidden) {
+        hidden.add(key);
+        steps.delete(key);
+        finals.delete(key);
+        transcripts.delete(key);
+      }
       for (const [key, hint] of folded.hints) {
         // Merge, never replace: a completion record can omit a label or an
         // edge the admission carried, and the view must not lose a step's
         // name between them.
         const existing = hints.get(key);
         hints.set(key, {
-          ...(hint.label ?? existing?.label ? { label: hint.label ?? existing?.label } : {}),
-          ...(hint.after ?? existing?.after ? { after: hint.after ?? existing?.after } : {}),
+          // The root's authored index is scanned before the child journal and
+          // carries causal edges across child runs. A child spec only knows
+          // its own single-step graph (`depends_on: []`), so it may fill a
+          // missing field but must never erase the root's richer answer.
+          ...(existing?.label ?? hint.label ? { label: existing?.label ?? hint.label } : {}),
+          ...(existing?.after ?? hint.after ? { after: existing?.after ?? hint.after } : {}),
         });
       }
       folded.steps.forEach((step, order) => remember(runId, step, order));
       for (const row of folded.finals) {
         const key = `${runId}/${row.stepName}`;
+        if (hidden.has(key)) continue;
         // The report cap bounds what this process holds, not just what it
         // sends: a run with ten thousand steps must not grow its own mirror.
         // Steps past it are counted by identity, so a step read twice is one

package/src/communication/environment.ts

@@ -4,19 +4,26 @@ import { wrapperEnvironment } from '../wrapper-runtime.js';
 const terminalNames = ['TERM', 'COLORTERM', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME'];
 const relayNames = ['RELAY_API_KEY', 'RELAY_WORKSPACE_KEY', 'AGENT_RELAY_WORKSPACE_KEY',
   'RELAY_BROKER_API_KEY', 'RELAY_AGENT_TOKEN', 'RELAY_NODE_TOKEN', 'RELAY_WORKSPACES_JSON'];
-const providerNames: Record<string, string[]> = {
+// Multi-provider CLIs select their provider in their own configuration.
+const multiProvider = ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'ANTHROPIC_API_KEY', 'ANTHROPIC_BASE_URL',
+  'GEMINI_API_KEY', 'GOOGLE_API_KEY', 'OPENROUTER_API_KEY'] as const;
+const providerNames: Readonly<Record<string, readonly string[]>> = {
   claude: ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_BASE_URL', 'CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CONFIG_DIR'],
   codex: ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'CODEX_HOME'],
   gemini: ['GEMINI_API_KEY', 'GOOGLE_API_KEY', 'GOOGLE_APPLICATION_CREDENTIALS', 'GOOGLE_CLOUD_PROJECT', 'GOOGLE_CLOUD_LOCATION'],
-  'cursor-agent': ['CURSOR_API_KEY'],
+  // AgentWorkforce/cloud#4026 passes both endpoint names unchanged as aliases
+  // for one run-scoped House proxy base. Dropping either can let a compatible
+  // Cursor version fall back to its provider default and bypass the House route.
+  'cursor-agent': ['CURSOR_API_KEY', 'CURSOR_API_ENDPOINT', 'CURSOR_API_BASE_URL'],
   droid: ['FACTORY_API_KEY'],
-  grok: ['XAI_API_KEY'],
+  // AgentWorkforce/cloud#4026's house-provider run contract gives Grok an
+  // isolated home plus an xAI-compatible base URL. These remain Grok-scoped.
+  grok: ['XAI_API_KEY', 'GROK_XAI_API_BASE_URL', 'GROK_HOME'],
+  ...Object.fromEntries(['opencode', 'aider', 'goose', 'pi', 'deepagents'].map(cli => [cli, multiProvider])),
 };
-// Multi-provider CLIs select their provider in their own configuration.
-const multiProvider = ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'ANTHROPIC_API_KEY', 'ANTHROPIC_BASE_URL',
-  'GEMINI_API_KEY', 'GOOGLE_API_KEY', 'OPENROUTER_API_KEY'];
-for (const cli of ['opencode', 'aider', 'goose', 'pi', 'deepagents']) providerNames[cli] = multiProvider;
-function selected(source: NodeJS.ProcessEnv, names: string[]) {
+/** @internal Names-only test seam; credential lists remain private. */
+export function providerEnvironmentCliNames(): readonly string[] { return Object.keys(providerNames); }
+function selected(source: NodeJS.ProcessEnv, names: readonly string[]) {
   return Object.fromEntries(names.filter(name => source[name] !== undefined).map(name => [name, source[name]]));
 }
 export function brokerEnvironment(source: NodeJS.ProcessEnv): NodeJS.ProcessEnv {

package/src/flow-extension-compat.ts

@@ -42,7 +42,9 @@ function assertRuntimeRange(
  */
 export function assertBaseCompatible(manifest: FlowExtensionManifest, base: { readonly name: string; readonly version?: string }): void {
   let entry: FlowExtensionManifest['compat']['base'][number] | undefined;
-  for (let index = 0; index < manifest.compat.base.length; index += 1) {
+  // First match, as `.find()` did before the intrinsic-capture rewrite: a
+  // later duplicate name must not widen or narrow the range that decides.
+  for (let index = 0; index < manifest.compat.base.length && entry === undefined; index += 1) {
     if (manifest.compat.base[index]!.name === base.name) entry = manifest.compat.base[index];
   }
   if (entry === undefined) {

package/src/hosted-extension-declarations.ts

@@ -67,6 +67,9 @@ const STRING_STARTS_WITH = Function.prototype.call.bind(
 ) as (value: string, search: string) => boolean;
 const LOCK_HEX64 = /^[0-9a-f]{64}$/;
 const LOCK_SHA = /^[0-9a-f]{40}$/;
+// `name` reaches pluginStoreDirectory as a path segment, so it stays one
+// lowercase kebab-case component: no separators, no `.`/`..`, no traversal.
+const LOCK_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const LOCK_OWNER = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
 const LOCK_REPO = /^[A-Za-z0-9_.-]{1,100}$/;
 const HTTPS_GITHUB = /^https:\/\/github\.com\//;
@@ -240,6 +243,7 @@ function parseHostedPluginLock(input: unknown): {
       ]) ||
       entry.kind !== "flow-extension" ||
       typeof entry.name !== "string" ||
+      !REGEXP_TEST(LOCK_NAME, entry.name) ||
       typeof entry.version !== "string" ||
       typeof entry.digest !== "string" ||
       !REGEXP_TEST(LOCK_HEX64, entry.digest) ||

package/src/hosted-extension-isolation.ts

@@ -10,6 +10,7 @@ import {
 import {
   assertHostedInstallationAuthority,
   assertHostedRuntimeAuthority,
+  loadHostedExtensionRuntime,
   type HostedExtensionArtifact,
   type HostedExtensionBase,
   type HostedExtensionInstallation,
@@ -104,8 +105,42 @@ export interface RunHostedExtensionOptions {
   readonly prlimitPath?: string;
 }
 
+export interface RunHostedSoftwareGardenBabysitterOptions
+  extends Omit<RunHostedExtensionOptions, 'installation' | 'base'> {
+  /** Exact reviewed Software Garden source inside its lock-backed project. */
+  readonly flowPath: string;
+}
+
 export type HostedExtensionResult = HostedExtensionProtocolResult;
 
+/**
+ * Compose the canonical Software Garden base with its installed native
+ * Babysitter and execute one host-verified delivery. Base source, extension
+ * declarations, lock entries and stored bytes are captured as one opaque
+ * generation; the capability runner rechecks that generation immediately
+ * before the isolated process starts.
+ *
+ * Hosted callers use this entrypoint instead of the ordinary authored loader,
+ * which imports extension JavaScript in the host and therefore keeps refusing
+ * matched hosted handlers.
+ */
+export async function runHostedSoftwareGardenBabysitter(
+  options: RunHostedSoftwareGardenBabysitterOptions,
+): Promise<HostedExtensionResult> {
+  const runtime = await loadHostedExtensionRuntime(options.flowPath);
+  return await runHostedCapabilityExtension({
+    installation: runtime.installation,
+    base: runtime.base,
+    dispatch: options.dispatch,
+    input: options.input,
+    babysitterTurn: options.babysitterTurn,
+    ...(OBJECT_HAS_OWN(options, 'timeoutMs') ? { timeoutMs: options.timeoutMs } : {}),
+    ...(OBJECT_HAS_OWN(options, 'bubblewrapPath') ? { bubblewrapPath: options.bubblewrapPath } : {}),
+    ...(OBJECT_HAS_OWN(options, 'nodePath') ? { nodePath: options.nodePath } : {}),
+    ...(OBJECT_HAS_OWN(options, 'prlimitPath') ? { prlimitPath: options.prlimitPath } : {}),
+  });
+}
+
 /**
  * Execute a capability-only hosted extension in a Linux mount/PID/network/user
  * namespace. The extension is first imported inside that namespace. It sees
@@ -114,8 +149,9 @@ export type HostedExtensionResult = HostedExtensionProtocolResult;
  * authenticated capability adapter and passes the original branded dispatch
  * authority to that adapter out of band.
  *
- * This is deliberately not wired into executeAuthoredFlow yet. #549's refusal
- * remains the rollout gate until the Cloud adapter and independent review land.
+ * The ordinary authored executor deliberately stays refused: it imports
+ * extension JavaScript in the host. `runHostedSoftwareGardenBabysitter` is the
+ * canonical composition boundary for a hosted Software Garden delivery.
  */
 export async function runHostedCapabilityExtension(
   options: RunHostedExtensionOptions,

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 = 'b97a3466c2affabb61afa655d4b2f726942d753c0466740b64ba26a78da359c6';
+const SOFTWARE_FACTORY_SHA256 = '8bbcf0e42f47d6bc6491a129935f96b791be03c8a5ed5b73d651c4e77913e2d7';
 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>(
@@ -243,7 +243,7 @@ async function baseAt(origin: string, generation: RuntimeGeneration): Promise<Ho
     }
     const value = frozenHostedPromiseValue({
       name: 'software-factory',
-      version: '2.0.22',
+      version: '2.0.23',
     });
     WEAK_SET_ADD(BASE_AUTHORITY, value);
     WEAK_MAP_SET(BASE_GENERATION, value, generation);

package/src/hosted-extension-sandbox.ts

@@ -53,6 +53,22 @@ const PATH_RESOLVE = resolve;
 const SPAWN = spawn;
 const PROCESS_EXEC_PATH = process.execPath;
 const PROCESS_NODE_VERSION = process.versions.node;
+
+/**
+ * The host's own `@relayflows/surface` entry, resolved once while this module
+ * initializes. `require.resolve` consults `Module._resolveFilename`, which is
+ * writable: resolving lazily would run after authored flow code has had a
+ * chance to replace it and could hand the sandbox a different package. The
+ * lookup therefore happens before any authored module can load, and a failure
+ * is reported when a caller actually needs the root.
+ */
+const SURFACE_ENTRY: string | undefined = (() => {
+  try { return REALPATH_SYNC(CREATE_REQUIRE(import.meta.url).resolve('@relayflows/surface')); }
+  catch { return undefined; }
+})();
+
+/** @internal Seam for the regression that pins initialization-time capture. */
+export function capturedSurfaceEntry(): string | undefined { return SURFACE_ENTRY; }
 const PROCESS_PLATFORM = process.platform;
 const PROMISE = Promise;
 const EVENT_ON = Function.prototype.call.bind(EventEmitter.prototype.on) as (
@@ -250,9 +266,8 @@ export async function runHostedExtensionSandbox(
 
 async function resolveSurfaceRoot(expectedVersion: string, override?: string): Promise<string> {
   if (override !== undefined) return await checkedSurfaceRoot(override, expectedVersion);
-  let resolved: string;
-  try { resolved = REALPATH_SYNC(CREATE_REQUIRE(import.meta.url).resolve('@relayflows/surface')); }
-  catch { return unsupported('hosted extension cannot resolve @relayflows/surface'); }
+  const resolved = SURFACE_ENTRY;
+  if (resolved === undefined) return unsupported('hosted extension cannot resolve @relayflows/surface');
   let directory = PATH_DIRNAME(resolved);
   const root = PATH_PARSE(directory).root;
   while (directory !== root) {

package/src/index.ts

@@ -61,6 +61,7 @@ export type { StepSpend } from './protocol.js';
 export { SPEC_SCHEMA_VERSION } from './spec.js';
 
 export {
+  runHostedSoftwareGardenBabysitter,
   runHostedCapabilityExtension,
   loadHostedExtensionRuntime,
   type HostedExtensionArtifact,
@@ -70,6 +71,7 @@ export {
   type HostedCapabilityAuthority,
   type HostedBabysitterCapability,
   type RunHostedExtensionOptions,
+  type RunHostedSoftwareGardenBabysitterOptions,
   type HostedExtensionResult,
 } from './hosted-extension-isolation.js';
 export {

package/src/worker-slots.ts

@@ -7,6 +7,16 @@ export function isAgentCapacity(value: unknown): value is number {
   return Number.isInteger(value) && (value as number) >= 1 && (value as number) <= MAX_LOCAL_AGENT_CAPACITY;
 }
 
+export interface WorkerSlotScope {
+  run<T>(work: () => Promise<T>): Promise<T>;
+  /** Refuse this flow's queued/future work without closing the shared pool. */
+  close(reason: unknown): void;
+}
+
+interface ScopeState {
+  closed?: { readonly reason: unknown };
+}
+
 /**
  * First-come admission to a worker that holds `capacity` dispatches at once.
  *
@@ -19,7 +29,11 @@ export function isAgentCapacity(value: unknown): value is number {
  */
 export class WorkerSlots {
   private held = 0;
-  private readonly waiting: Array<{ resolve: () => void; reject: (reason: unknown) => void }> = [];
+  private readonly waiting: Array<{
+    resolve: () => void;
+    reject: (reason: unknown) => void;
+    scope?: ScopeState;
+  }> = [];
   private closed: { readonly reason: unknown } | undefined;
 
   constructor(readonly capacity: number) {
@@ -27,18 +41,37 @@ export class WorkerSlots {
   }
 
   async run<T>(work: () => Promise<T>): Promise<T> {
+    return this.runInScope(work);
+  }
+
+  /** One independently closable admission scope over this shared capacity. */
+  scope(): WorkerSlotScope {
+    const scope: ScopeState = {};
+    return Object.freeze({
+      run: <T>(work: () => Promise<T>) => this.runInScope(work, scope),
+      close: (reason: unknown) => this.closeScope(scope, reason),
+    });
+  }
+
+  private async runInScope<T>(work: () => Promise<T>, scope?: ScopeState): Promise<T> {
     if (this.closed !== undefined) throw this.closed.reason;
+    if (scope?.closed !== undefined) throw scope.closed.reason;
     if (this.held < this.capacity) this.held++;
     // A released slot is handed straight to the next waiter, so `held` never
     // dips below capacity while anyone is queued and no later caller can jump it.
     else {
-      await new Promise<void>((resolve, reject) => this.waiting.push({ resolve, reject }));
+      await new Promise<void>((resolve, reject) => this.waiting.push({ resolve, reject, scope }));
       // Woken with the slot, but the body may have failed in between (see release).
       const closed = this.closedReason();
       if (closed !== undefined) {
         this.release();
         throw closed.reason;
       }
+      const scopeClosed = scopeClosedReason(scope);
+      if (scopeClosed !== undefined) {
+        this.release();
+        throw scopeClosed.reason;
+      }
     }
     try {
       return await work();
@@ -66,17 +99,28 @@ export class WorkerSlots {
       return;
     }
     setImmediate(() => {
-      if (this.closed === undefined) {
+      if (this.closed === undefined && next.scope?.closed === undefined) {
         next.resolve();
         return;
       }
       // Closed meanwhile. `close` could not see this waiter (already taken off
       // the queue), so refuse it here, and pass the slot on instead of leaking it.
-      next.reject(this.closed.reason);
+      next.reject(this.closed?.reason ?? next.scope!.closed!.reason);
       this.release();
     });
   }
 
+  private closeScope(scope: ScopeState, reason: unknown): void {
+    if (scope.closed !== undefined) return;
+    scope.closed = { reason };
+    for (let index = this.waiting.length - 1; index >= 0; index--) {
+      const waiter = this.waiting[index]!;
+      if (waiter.scope !== scope) continue;
+      this.waiting.splice(index, 1);
+      waiter.reject(reason);
+    }
+  }
+
   /**
    * Refuse every queued and future admission with `reason`; work already
    * holding a slot is not interrupted. The authored body calls this when it
@@ -90,3 +134,18 @@ export class WorkerSlots {
     for (const waiter of this.waiting.splice(0)) waiter.reject(reason);
   }
 }
+
+/** Read through a call so a check after an `await` is not narrowed away. */
+function scopeClosedReason(scope?: ScopeState): { readonly reason: unknown } | undefined {
+  return scope?.closed;
+}
+
+/** One run-tree-wide capacity pool, shared by parent and child flows. */
+export interface AuthoredWorkerSlots {
+  readonly agent: WorkerSlots;
+  readonly llm: WorkerSlots;
+}
+
+export function authoredWorkerSlots(capacity: number): AuthoredWorkerSlots {
+  return Object.freeze({ agent: new WorkerSlots(capacity), llm: new WorkerSlots(capacity) });
+}