@relayflows/sdk 2.0.36 → 2.0.38

package/src/effect-channel.ts

@@ -4,6 +4,7 @@ import type { JournalClient } from './journal-client.js';
 import type { StepDispatchEvent } from './protocol.js';
 import { SPEC_SCHEMA_VERSION } from './spec.js';
 import { withWorkerLease } from './worker-lease.js';
+import { NO_MODEL_COST } from './reported-cost.js';
 import { snapshotJsonValue } from './json-value.js';
 
 /** Structural subset of Agent Relay's messages.dm; credentials stay in the client. */
@@ -93,5 +94,6 @@ export async function completeChannelPost(
         messageId, channel: call.channel, to: call.to, text: call.text },
       started_pins: dispatch.pins, end_pins: dispatch.pins,
       effects: [{ surface_path: surfacePath, idempotency_key: dispatch.idempotency_key }],
+      reported_cost: NO_MODEL_COST,
     });
 }

package/src/failure-kinds.ts

@@ -144,6 +144,12 @@ export const RUN_FAILURE_KINDS = [
    * attaches and before the resume touches the journal.
    */
   'local_agent_unavailable',
+  /**
+   * The authored root's worker lease was lost and the kernel's retry did not
+   * reach this process. The run is NOT failed (`status: running`): its
+   * completed steps are journaled and `flows resume <rootRunId>` continues it.
+   */
+  'root_lease_lost',
 ] as const;
 
 /**
@@ -271,6 +277,14 @@ export interface StepFailedDetails {
    * `retries_exhausted`.
    */
   maxIterations?: number;
+  /**
+   * Attempts before this one that died without a result -- the kernel
+   * journaled them `crashed` or `lease_expired` itself -- and so, by design,
+   * consumed none of `maxIterations` (relayflowd-core recovery.rs). Present
+   * only when non-zero. Without it `attempt` can exceed `maxIterations`
+   * (`attempt=2/1`) and read as the kernel overrunning its own budget.
+   */
+  unchargedAttempts?: number;
   exitCode?: number;
   /**
    * Terminal-safe UTF-8 excerpt of the captured stdout, at most

package/src/flow-extension-loader.ts

@@ -13,7 +13,18 @@ import { pluginStoreDirectory, readStoredPluginFiles } from './plugin-store.js';
 const JSON_PARSE = JSON.parse;
 const ARRAY_IS_ARRAY = Array.isArray;
 const JSON_STRINGIFY = JSON.stringify;
+const NUMBER = Number;
+const NUMBER_IS_FINITE = Number.isFinite.bind(Number);
+const NUMBER_IS_SAFE_INTEGER = Number.isSafeInteger.bind(Number);
+const NUMBER_TO_STRING = Function.prototype.call.bind(Number.prototype.toString) as (
+  value: number,
+) => string;
+const OBJECT_GET_OWN_PROPERTY_DESCRIPTOR = Object.getOwnPropertyDescriptor;
 const OBJECT_FREEZE = Object.freeze;
+const POSITIVE_INFINITY = Number.POSITIVE_INFINITY;
+const REGEXP_EXEC = Function.prototype.call.bind(RegExp.prototype.exec) as (
+  regexp: RegExp, value: string,
+) => RegExpExecArray | null;
 const REGEXP_TEST = Function.prototype.call.bind(RegExp.prototype.test) as (
   regexp: RegExp, value: string,
 ) => boolean;
@@ -74,12 +85,111 @@ export interface LoadFlowExtensionsOptions<Authority> {
 
 const EXTENSION_HEADER_FIELDS = new Set(['budget', 'tools']);
 const WALLCLOCK_MS = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;
+type StructuredFlowBudget = Exclude<NonNullable<AuthoredFlowDefinition['header']['budget']>, string>;
+
+function ownBudgetField<K extends keyof StructuredFlowBudget>(
+  budget: StructuredFlowBudget,
+  field: K,
+): StructuredFlowBudget[K] | undefined {
+  const descriptor = OBJECT_GET_OWN_PROPERTY_DESCRIPTOR(budget, field);
+  return descriptor !== undefined && 'value' in descriptor
+    ? descriptor.value as StructuredFlowBudget[K]
+    : undefined;
+}
 
 function wallclockMs(value: string): number | undefined {
-  const match = /^(\d+)(ms|s|m|h|d)$/.exec(value);
+  const match = REGEXP_EXEC(/^(\d+)(ms|s|m|h|d)$/, value);
   if (!match) return undefined;
   const unit = match[2] as keyof typeof WALLCLOCK_MS;
-  return Number(match[1]) * WALLCLOCK_MS[unit];
+  const milliseconds = NUMBER(match[1]) * WALLCLOCK_MS[unit];
+  return NUMBER_IS_FINITE(milliseconds) ? milliseconds : undefined;
+}
+
+function hasBudgetCeiling(budget: StructuredFlowBudget): boolean {
+  return ownBudgetField(budget, 'tokens') !== undefined
+    || ownBudgetField(budget, 'dollars') !== undefined
+    || ownBudgetField(budget, 'wallclock') !== undefined;
+}
+
+function validateStructuredBudget(budget: StructuredFlowBudget): void {
+  const tokens = ownBudgetField(budget, 'tokens');
+  if (tokens !== undefined && (!NUMBER_IS_SAFE_INTEGER(tokens) || tokens < 0)) {
+    throw new PluginError('plugin_incompatible', `Malformed token budget ceiling ${JSON_STRINGIFY(tokens)}.`);
+  }
+  const dollars = ownBudgetField(budget, 'dollars');
+  if (dollars !== undefined && (!NUMBER_IS_FINITE(dollars) || dollars < 0
+    || REGEXP_EXEC(/^\d+(?:\.\d{1,6})?$/, NUMBER_TO_STRING(dollars)) === null)) {
+    throw new PluginError('plugin_incompatible', `Malformed dollar budget ceiling ${JSON_STRINGIFY(dollars)}.`);
+  }
+}
+
+function composeBudget(
+  base: AuthoredFlowDefinition['header']['budget'],
+  extensions: readonly LoadedFlowExtension[],
+): AuthoredFlowDefinition['header']['budget'] {
+  type Budget = NonNullable<AuthoredFlowDefinition['header']['budget']>;
+  type StructuredBudget = Exclude<Budget, string>;
+  const effectiveBase = typeof base === 'object' && !hasBudgetCeiling(base)
+    ? undefined
+    : base;
+  const ceilings: Budget[] = [];
+  for (let index = 0; index < extensions.length; index += 1) {
+    const extension = extensions[index]!;
+    const manifestBudget = extension.manifest.permissions.budget;
+    const entryBudget = extension.getDefinition(extension.handle).header.budget;
+    if (manifestBudget !== undefined
+      && (typeof manifestBudget === 'string' || hasBudgetCeiling(manifestBudget))) {
+      appendIntrinsicArray(ceilings, manifestBudget);
+    }
+    if (entryBudget !== undefined
+      && (typeof entryBudget === 'string' || hasBudgetCeiling(entryBudget))) {
+      appendIntrinsicArray(ceilings, entryBudget);
+    }
+  }
+  if (ceilings.length === 0) return base;
+  if (effectiveBase === undefined && ceilings.length === 1 && typeof ceilings[0] === 'string') {
+    return ceilings[0];
+  }
+  let shorthand = typeof effectiveBase === 'string';
+  for (let index = 0; index < ceilings.length; index += 1) {
+    if (typeof ceilings[index] === 'string') shorthand = true;
+  }
+  if (shorthand) {
+    throw new PluginError('plugin_incompatible', 'A shorthand budget cannot compose with structured base-flow or extension budget ceilings.');
+  }
+  const budgets: StructuredBudget[] = [];
+  if (effectiveBase !== undefined) appendIntrinsicArray(budgets, effectiveBase as StructuredBudget);
+  for (let index = 0; index < ceilings.length; index += 1) {
+    appendIntrinsicArray(budgets, ceilings[index] as StructuredBudget);
+  }
+  let tokens: number | undefined;
+  let dollars: number | undefined;
+  let wallclock: string | undefined;
+  let wallclockLimit = POSITIVE_INFINITY;
+  for (let index = 0; index < budgets.length; index += 1) {
+    const budget = budgets[index]!;
+    const budgetTokens = ownBudgetField(budget, 'tokens');
+    const budgetDollars = ownBudgetField(budget, 'dollars');
+    const budgetWallclock = ownBudgetField(budget, 'wallclock');
+    validateStructuredBudget(budget);
+    if (budgetTokens !== undefined && (tokens === undefined || budgetTokens < tokens)) tokens = budgetTokens;
+    if (budgetDollars !== undefined && (dollars === undefined || budgetDollars < dollars)) dollars = budgetDollars;
+    if (budgetWallclock !== undefined) {
+      const candidate = wallclockMs(budgetWallclock);
+      if (candidate === undefined) {
+        throw new PluginError('plugin_incompatible', `Malformed wallclock budget ceiling ${JSON_STRINGIFY(budgetWallclock)}.`);
+      }
+      if (wallclock === undefined || candidate < wallclockLimit) {
+        wallclock = budgetWallclock;
+        wallclockLimit = candidate;
+      }
+    }
+  }
+  return OBJECT_FREEZE({
+    ...(tokens === undefined ? {} : { tokens }),
+    ...(dollars === undefined ? {} : { dollars }),
+    ...(wallclock === undefined ? {} : { wallclock }),
+  });
 }
 
 /** Credentials and servers declared on a flow-extension, probed before the base body starts. */
@@ -253,14 +363,26 @@ async function loadOne<Authority>(
   assertBaseCompatible(manifest, { name: base.definition.name, version: base.definition.header.version });
   const baseBudget = base.definition.header.budget;
   const ceiling = manifest.permissions.budget;
-  if (ceiling?.dollars !== undefined && typeof baseBudget === 'object' && baseBudget.dollars !== undefined && ceiling.dollars > baseBudget.dollars) {
-    throw new PluginError('plugin_incompatible', `${manifest.name} declares a $${ceiling.dollars} budget ceiling above the base flow's $${baseBudget.dollars}.`);
+  if (ceiling !== undefined && hasBudgetCeiling(ceiling) && typeof baseBudget === 'string') {
+    throw new PluginError('plugin_incompatible', `${manifest.name} declares a structured budget ceiling that cannot compose with the base flow's shorthand budget.`);
   }
-  if (ceiling?.wallclock !== undefined && typeof baseBudget === 'object' && baseBudget.wallclock !== undefined) {
-    const pluginMs = wallclockMs(ceiling.wallclock);
-    const baseMs = wallclockMs(baseBudget.wallclock);
+  const ceilingTokens = ceiling === undefined ? undefined : ownBudgetField(ceiling, 'tokens');
+  const ceilingDollars = ceiling === undefined ? undefined : ownBudgetField(ceiling, 'dollars');
+  const ceilingWallclock = ceiling === undefined ? undefined : ownBudgetField(ceiling, 'wallclock');
+  const baseTokens = typeof baseBudget === 'object' ? ownBudgetField(baseBudget, 'tokens') : undefined;
+  const baseDollars = typeof baseBudget === 'object' ? ownBudgetField(baseBudget, 'dollars') : undefined;
+  const baseWallclock = typeof baseBudget === 'object' ? ownBudgetField(baseBudget, 'wallclock') : undefined;
+  if (ceilingTokens !== undefined && baseTokens !== undefined && ceilingTokens > baseTokens) {
+    throw new PluginError('plugin_incompatible', `${manifest.name} declares a ${ceilingTokens}-token budget ceiling above the base flow's ${baseTokens}-token ceiling.`);
+  }
+  if (ceilingDollars !== undefined && baseDollars !== undefined && ceilingDollars > baseDollars) {
+    throw new PluginError('plugin_incompatible', `${manifest.name} declares a $${ceilingDollars} budget ceiling above the base flow's $${baseDollars}.`);
+  }
+  if (ceilingWallclock !== undefined && baseWallclock !== undefined) {
+    const pluginMs = wallclockMs(ceilingWallclock);
+    const baseMs = wallclockMs(baseWallclock);
     if (pluginMs !== undefined && baseMs !== undefined && pluginMs > baseMs) {
-      throw new PluginError('plugin_incompatible', `${manifest.name} declares a ${ceiling.wallclock} wallclock ceiling above the base flow's ${baseBudget.wallclock}.`);
+      throw new PluginError('plugin_incompatible', `${manifest.name} declares a ${ceilingWallclock} wallclock ceiling above the base flow's ${baseWallclock}.`);
     }
   }
   const entryPath = join(directory, manifest.entry);
@@ -279,7 +401,9 @@ async function loadOne<Authority>(
   if (!manifest.extends.handlers && definition.handlers.length > 0) {
     throw new PluginError('plugin_manifest_invalid', `${manifest.name}: ${manifest.entry} declares handlers but extends.handlers is false.`);
   }
-  definition.handlers.forEach((handler, index) => assertDeclaredSubscription(manifest.name, manifest, handler, index));
+  for (let index = 0; index < definition.handlers.length; index += 1) {
+    assertDeclaredSubscription(manifest.name, manifest, definition.handlers[index]!, index);
+  }
   const hooks = imported.hooks;
   const exported = Object.keys(hooks).sort();
   const declared = [...manifest.extends.hooks].sort();
@@ -292,9 +416,13 @@ async function loadOne<Authority>(
       throw new PluginError('plugin_incompatible', `${manifest.name}: hook ${hook} is not declared by the base flow.`);
     }
   }
-  return Object.freeze({
+  const handlers: TriggerHandler[] = [];
+  for (let index = 0; index < definition.handlers.length; index += 1) {
+    appendIntrinsicArray(handlers, definition.handlers[index]!);
+  }
+  return OBJECT_FREEZE({
     name: manifest.name, version: manifest.version, ref, digest: lock.digest, directory, entryPath, manifest,
-    handle: imported.handle, getDefinition: imported.getDefinition, handlers: Object.freeze([...definition.handlers]),
+    handle: imported.handle, getDefinition: imported.getDefinition, handlers: OBJECT_FREEZE(handlers),
     hooks,
   });
 }
@@ -329,11 +457,23 @@ export async function loadFlowExtensions<Authority>(
   return Object.freeze(loaded);
 }
 
-/** The base definition with extension handlers appended in lock order; the base's own fields are untouched. */
+/** The base definition with extension handlers appended and every declared budget ceiling retained. */
 export function composeDefinition<Input>(base: AuthoredFlowDefinition<Input>, extensions: readonly LoadedFlowExtension[]): AuthoredFlowDefinition<Input> {
   if (extensions.length === 0) return base;
-  return Object.freeze({
+  const budget = composeBudget(base.header.budget, extensions);
+  const handlers: TriggerHandler[] = [];
+  for (let index = 0; index < base.handlers.length; index += 1) appendIntrinsicArray(handlers, base.handlers[index]!);
+  for (let extensionIndex = 0; extensionIndex < extensions.length; extensionIndex += 1) {
+    const extensionHandlers = extensions[extensionIndex]!.handlers;
+    for (let handlerIndex = 0; handlerIndex < extensionHandlers.length; handlerIndex += 1) {
+      appendIntrinsicArray(handlers, extensionHandlers[handlerIndex]!);
+    }
+  }
+  return OBJECT_FREEZE({
     ...base,
-    handlers: Object.freeze([...base.handlers, ...extensions.flatMap(extension => extension.handlers)]),
+    header: budget === base.header.budget
+      ? base.header
+      : OBJECT_FREEZE({ ...base.header, budget }),
+    handlers: OBJECT_FREEZE(handlers),
   });
 }

package/src/flow-extension-manifest.ts

@@ -6,6 +6,7 @@ import { PluginError, pluginKindOf } from './plugin-manifest.js';
 import { safePath } from './bundle.js';
 import { SHA, parsePluginSource, type PluginSourceInput } from './plugin-source.js';
 import { isVersionRange, parseVersion } from './semver-range.js';
+import { parseBudget } from './budget.js';
 
 /**
  * Schema 2, `kind: "flow-extension"`: a plugin whose `entry` default-exports
@@ -29,7 +30,7 @@ export interface FlowExtensionPermissions {
   readonly mcp: readonly string[];
   /** Declared effect classes, shown for review; not enforced by this runtime (gate 8 / #442). */
   readonly writes: readonly string[];
-  readonly budget?: { readonly dollars?: number; readonly wallclock?: string };
+  readonly budget?: { readonly tokens?: number; readonly dollars?: number; readonly wallclock?: string };
 }
 export interface FlowExtensionManifest {
   readonly schema: 2;
@@ -117,10 +118,12 @@ function permissions(value: unknown): FlowExtensionPermissions {
   for (const harness of harnesses) if (!(FLOW_HARNESSES as readonly string[]).includes(harness)) return invalid(`permissions.harnesses: unknown harness ${harness}.`);
   let budget: FlowExtensionPermissions['budget'];
   if (value.budget !== undefined) {
-    if (!object(value.budget) || Object.keys(value.budget).some(k => !['dollars', 'wallclock'].includes(k))) return invalid('permissions.budget expects dollars and/or wallclock.');
+    if (!object(value.budget) || Object.keys(value.budget).some(k => !['tokens', 'dollars', 'wallclock'].includes(k))) return invalid('permissions.budget expects tokens, dollars, and/or wallclock.');
+    if (value.budget.tokens !== undefined && (typeof value.budget.tokens !== 'number' || !Number.isSafeInteger(value.budget.tokens) || value.budget.tokens < 0)) return invalid('permissions.budget.tokens must be a non-negative safe integer.');
     if (value.budget.dollars !== undefined && (typeof value.budget.dollars !== 'number' || !(value.budget.dollars > 0) || !Number.isFinite(value.budget.dollars))) return invalid('permissions.budget.dollars must be a positive number.');
     if (value.budget.wallclock !== undefined && (typeof value.budget.wallclock !== 'string' || !WALLCLOCK.test(value.budget.wallclock))) return invalid('permissions.budget.wallclock must be a duration such as 45m.');
-    budget = Object.freeze({ ...(value.budget.dollars === undefined ? {} : { dollars: value.budget.dollars }), ...(value.budget.wallclock === undefined ? {} : { wallclock: value.budget.wallclock }) });
+    try { parseBudget(value.budget); } catch { return invalid('permissions.budget must use runtime budget syntax.'); }
+    budget = Object.freeze({ ...(value.budget.tokens === undefined ? {} : { tokens: value.budget.tokens }), ...(value.budget.dollars === undefined ? {} : { dollars: value.budget.dollars }), ...(value.budget.wallclock === undefined ? {} : { wallclock: value.budget.wallclock }) });
   }
   return Object.freeze({
     integrations: stringList(value.integrations, 'permissions.integrations', PROVIDER),

package/src/helper-instruction.ts

@@ -0,0 +1,2 @@
+/** The instruction prefix a lowered provider helper step carries (`yaml-helpers.ts`). */
+export const HELPER_INSTRUCTION_PREFIX = 'relayflows:helper:v1\n';

package/src/hosted-extension-manifest.ts

@@ -12,6 +12,7 @@ import { PluginError } from './plugin-manifest.js';
 
 const ARRAY_IS_ARRAY = Array.isArray;
 const NUMBER_IS_FINITE = Number.isFinite;
+const NUMBER_IS_SAFE_INTEGER = Number.isSafeInteger;
 const OBJECT_CREATE = Object.create;
 const OBJECT_FREEZE = Object.freeze;
 const OBJECT_HAS_OWN = Object.hasOwn;
@@ -20,6 +21,10 @@ const REGEXP_TEST = Function.prototype.call.bind(RegExp.prototype.test) as (
   regexp: RegExp,
   value: string,
 ) => boolean;
+const REGEXP_EXEC = Function.prototype.call.bind(RegExp.prototype.exec) as (
+  regexp: RegExp,
+  value: string,
+) => RegExpExecArray | null;
 const STRING_ENDS_WITH = Function.prototype.call.bind(String.prototype.endsWith) as (
   value: string,
   search: string,
@@ -38,7 +43,8 @@ const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const PROVIDER = /^[a-z0-9][a-z0-9-]{0,63}$/;
 const WRITE_CLASS = /^[a-z0-9-]+(?::[a-z0-9_-]+)+$/;
-const WALLCLOCK = /^\d+(?:ms|s|m|h|d)$/;
+const DOLLARS = /^\d+(?:\.\d{1,6})?$/;
+const WALLCLOCK = /^(\d+)(ms|s|m|h|d)$/;
 const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 const VERSION_RANGE = /^(?:\*|(?:[\^~]|>=)?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?: <\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)?)$/;
 const MAX_DESCRIPTION = 500;
@@ -168,19 +174,36 @@ function permissionsShape(value: unknown): FlowExtensionPermissions {
   }
   let budget: FlowExtensionPermissions['budget'];
   if (value.budget !== undefined) {
-    if (!record(value.budget) || !hasOnlyKeys(value.budget, ['dollars', 'wallclock'])) {
-      return invalid('permissions.budget expects dollars and/or wallclock.');
+    if (!record(value.budget) || !hasOnlyKeys(value.budget, ['tokens', 'dollars', 'wallclock'])) {
+      return invalid('permissions.budget expects tokens, dollars, and/or wallclock.');
+    }
+    if (value.budget.tokens !== undefined
+      && (typeof value.budget.tokens !== 'number'
+        || !NUMBER_IS_SAFE_INTEGER(value.budget.tokens) || value.budget.tokens < 0)) {
+      return invalid('permissions.budget.tokens must be a non-negative safe integer.');
     }
     if (value.budget.dollars !== undefined
       && (typeof value.budget.dollars !== 'number' || value.budget.dollars <= 0
-        || !NUMBER_IS_FINITE(value.budget.dollars))) {
+        || !NUMBER_IS_FINITE(value.budget.dollars)
+        || !matches(DOLLARS, `${value.budget.dollars}`))) {
       return invalid('permissions.budget.dollars must be a positive number.');
     }
     if (value.budget.wallclock !== undefined
       && (typeof value.budget.wallclock !== 'string' || !matches(WALLCLOCK, value.budget.wallclock))) {
       return invalid('permissions.budget.wallclock must be a duration such as 45m.');
     }
-    const projected = OBJECT_CREATE(null) as { dollars?: number; wallclock?: string };
+    if (value.budget.wallclock !== undefined) {
+      const match = REGEXP_EXEC(WALLCLOCK, value.budget.wallclock)!;
+      const multiplier = match[2] === 'ms' ? 1
+        : match[2] === 's' ? 1_000
+        : match[2] === 'm' ? 60_000
+        : match[2] === 'h' ? 3_600_000 : 86_400_000;
+      if (!NUMBER_IS_SAFE_INTEGER(+match[1]! * multiplier)) {
+        return invalid('permissions.budget.wallclock must fit the runtime duration range.');
+      }
+    }
+    const projected = OBJECT_CREATE(null) as { tokens?: number; dollars?: number; wallclock?: string };
+    if (value.budget.tokens !== undefined) projected.tokens = value.budget.tokens;
     if (value.budget.dollars !== undefined) projected.dollars = value.budget.dollars;
     if (value.budget.wallclock !== undefined) projected.wallclock = value.budget.wallclock;
     budget = OBJECT_FREEZE(projected);

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 = '8bbcf0e42f47d6bc6491a129935f96b791be03c8a5ed5b73d651c4e77913e2d7';
+const SOFTWARE_FACTORY_SHA256 = '4339c0c45a4fc928092a3e32275c061000887ed95acdc2f898966c35aca91a2d';
 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/hosted-extension-sandbox.ts

@@ -124,11 +124,11 @@ const NODE_EXECUTABLE = captureNodeExecutable();
 const ADDRESS_SPACE_BYTES = 16 * 1024 * 1024 * 1024;
 const DATA_BYTES = 3 * 1024 * 1024 * 1024;
 const SURFACE_RUNTIME_SHA256 = OBJECT_FREEZE({
-  'flow.js': '4aaeacc55de3074f4d121ce7253c3be50a93757e6540ba8159889a9450d1c05c',
+  'flow.js': '2ba972849bf435bba36b918c348efeab71ec34d180cec7a722e535f482687a6a',
   'helpers/providers.js': '4eb06d0d85ca0a3434bb2dbba7407e3d95eef2dfbedaeb0e2de0c0c0ea812457',
   'provider-trigger.js': 'e2664c65397f93fb486eb6f1e756c7cec3f88b3851d79c23567cad986f80f1ff',
   'schedule.js': '8fe72f176a75ec0b5f26e12db7a597575c259a2e2cbb59690f9dc20a5e63940b',
-  'triggers.js': '4a3515b571a318f6c7a5661f9310bc9af43e3faf20ea39903a9b363c51258e4c',
+  'triggers.js': '421609a6ea6d2ea77051dd4826a32e773b7db81dedd1dde91f4187b382cd46e3',
   'triggers/github.js': 'e312994320f82aad0af00d09c504175d929cc6c601dfe1bc522632462ad9a48b',
 });
 const SURFACE_PACKAGE_JSON = '{"name":"@relayflows/surface","type":"module","exports":{".":"./index.js","./runtime":"./runtime.js"}}';

package/src/journal-client.ts

@@ -13,7 +13,7 @@ import { EventEmitter } from 'node:events';
 export { walkJournal, JournalReadError, type JournalEvent, type JournalReadFailure } from './journal-reader.js';
 import { randomUUID } from 'node:crypto';
 import { createConnection, type Socket } from 'node:net';
-import type { VerbContract, EventEmitParams, EventSubmitParams } from './protocol.js';
+import type { VerbContract, EventEmitParams, EventSubmitParams, ReportedCost } from './protocol.js';
 import {
   PROTOCOL_VERSION,
   type CompletionReason,
@@ -61,6 +61,8 @@ export class JournalProtocolError extends Error {
 }
 
 export class JournalClient extends EventEmitter {
+  /** Additive request capabilities the daemon advertised at `hello`; none until then. */
+  private features: ReadonlySet<string> = new Set();
   private socket: Socket | null = null;
   /** Why the connection ended, so a later "not connected" names its cause rather than hiding it. */
   private disconnectCause: Error | undefined;
@@ -215,9 +217,11 @@ export class JournalClient extends EventEmitter {
 
   // --- Typed verb methods (gate 1 minimal set, kernel DESIGN.md §5) --------
 
-  /** Handshake; version mismatch is a hard error. */
-  hello(client: string): Promise<VerbContract['hello']['result']> {
-    return this.request('hello', { protocol: PROTOCOL_VERSION, client });
+  /** Handshake; version mismatch is a hard error. Records the daemon's additive features. */
+  async hello(client: string): Promise<VerbContract['hello']['result']> {
+    const result = await this.request('hello', { protocol: PROTOCOL_VERSION, client });
+    this.features = new Set(Array.isArray(result.features) ? result.features.filter(f => typeof f === 'string') : []);
+    return result;
   }
 
   /**
@@ -403,15 +407,20 @@ export class JournalClient extends EventEmitter {
       effects?: EffectRef[];
       trajectory_tail?: unknown;
       human_intervention?: boolean;
+      reported_cost?: ReportedCost;
     } = {},
   ): Promise<VerbContract['step.complete']['result']> {
+    // `reported_cost` is display-only, and a daemon that predates it refuses
+    // unknown completion fields: drop it rather than fail the completion.
+    const { reported_cost: reportedCost, ...rest } = extra;
     return this.request('step.complete', {
       run_id: runId,
       step_id: stepId,
       attempt,
       idempotency_key: idempotencyKey,
       completionReason,
-      ...extra,
+      ...rest,
+      ...(reportedCost !== undefined && this.features.has('reported_cost') ? { reported_cost: reportedCost } : {}),
     }, null).catch(error => {
       if (error instanceof JournalProtocolError) error.verb = 'step.complete';
       throw error;

package/src/llm-worker.ts

@@ -1,10 +1,11 @@
 import { workerSpend } from './worker-spend.js';
+import { reportedCost } from './reported-cost.js';
 import { DEFAULT_LOCAL_AGENT_CAPACITY } from './worker-slots.js';
 import type { WorkerCliResult } from './worker-cli.js';
 import { EventEmitter } from 'node:events';
 import type { JournalClient } from './journal-client.js';
 import type { CompletionReason, StepDispatchEvent } from './protocol.js';
-import type { KernelLlmStep } from './spec.js';
+import type { ResolvedKernelLlmStep } from './resolved-cli-identity.js';
 import { runAgentCli } from './worker-cli.js';
 import { resolveCliModel } from './cli-adapter.js';
 import { withWorkerLease } from './worker-lease.js';
@@ -22,6 +23,7 @@ export class LlmWorker extends EventEmitter {
     private readonly client: JournalClient,
     private readonly workerId: string,
     private readonly capacity: number = DEFAULT_LOCAL_AGENT_CAPACITY,
+    private readonly environment?: NodeJS.ProcessEnv,
   ) {
     super();
   }
@@ -52,16 +54,20 @@ export class LlmWorker extends EventEmitter {
   };
 
   private async execute(dispatch: StepDispatchEvent): Promise<void> {
-    const spec = dispatch.spec as KernelLlmStep;
+    const spec = dispatch.spec as ResolvedKernelLlmStep;
     const schema = spec.verification?.json_schema;
     const prompt = schema === undefined ? spec.prompt
       : `${spec.prompt}\n\nReturn only a JSON value matching this JSON Schema (no Markdown fences):\n${JSON.stringify(schema)}`;
-    const effectiveModel = typeof spec.cli === 'string' ? resolveCliModel(spec.cli, spec.model) : spec.model;
+    const effectiveModel = typeof spec.cli === 'string'
+      ? resolveCliModel(spec.cli_identity ?? spec.cli, spec.model)
+      : spec.model;
     const completed: WorkerCliResult = await withWorkerLease(this.client, dispatch, signal =>
       typeof spec.cli === 'string' && typeof spec.prompt === 'string'
-        ? runAgentCli(spec.cli, workerInstruction(prompt, dispatch), dispatch.wake_context, effectiveModel, undefined, signal, 'llm')
+        ? runAgentCli(spec.cli, workerInstruction(prompt, dispatch), dispatch.wake_context, effectiveModel, undefined, signal, 'llm',
+          undefined, undefined, 'direct', undefined, this.environment, spec.cli_identity)
         : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'llm step has no declared CLI' }));
     const { result, usage } = workerSpend(completed, effectiveModel);
+    const cost = reportedCost(completed, effectiveModel);
     let reason: CompletionReason = result.exit_code === 0 ? 'success' : 'worker_error';
     let output: unknown = result.stdout_tail;
     let detail = result.stderr_tail;
@@ -94,6 +100,7 @@ export class LlmWorker extends EventEmitter {
       dispatch.idempotency_key, reason, {
         output,
         ...(usage !== undefined ? { usage } : {}),
+        ...(cost === undefined ? {} : { reported_cost: cost }),
         ...(Object.keys(trajectoryTail).length === 0 ? {} : { trajectory_tail: trajectoryTail }),
       });
   }

package/src/local-agent-environment.ts

@@ -0,0 +1,92 @@
+import { closeSync, readSync } from 'node:fs';
+
+/**
+ * Inherited descriptor carrying environment values that only local agent/LLM
+ * subprocesses may receive. The flows process consumes and closes it before
+ * loading authored code, so that code cannot inherit or read the credentials.
+ */
+export const LOCAL_AGENT_ENV_FD = 'FLOWS_LOCAL_AGENT_ENV_FD';
+
+const MAX_BYTES = 64 * 1024;
+const AGENT_CREDENTIAL_NAMES = new Set([
+  'ANTHROPIC_API_KEY',
+  'ANTHROPIC_BASE_URL',
+  'OPENAI_API_KEY',
+  'OPENAI_BASE_URL',
+]);
+
+export function localAgentEnvironment(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv | undefined {
+  const environment = { ...base };
+  const rawFd = environment[LOCAL_AGENT_ENV_FD];
+  delete environment[LOCAL_AGENT_ENV_FD];
+  // Without the descriptor, provider launches keep their historical live
+  // process.env behavior instead of freezing an early snapshot.
+  if (rawFd === undefined) return undefined;
+  // Every later child — especially the authored runtime — inherits process.env.
+  // Remove the capability marker before any authored module can be imported.
+  if (base === process.env) delete process.env[LOCAL_AGENT_ENV_FD];
+
+  if (!/^[0-9]+$/.test(rawFd)) throw new Error(`${LOCAL_AGENT_ENV_FD} must name an inherited file descriptor`);
+  const fd = Number(rawFd);
+  if (!Number.isSafeInteger(fd) || fd < 3 || fd > 255) {
+    throw new Error(`${LOCAL_AGENT_ENV_FD} must name an inherited file descriptor`);
+  }
+
+  const chunks: Buffer[] = [];
+  let bytes = 0;
+  try {
+    for (;;) {
+      const chunk = Buffer.allocUnsafe(Math.min(8 * 1024, MAX_BYTES + 1 - bytes));
+      const read = readSync(fd, chunk, 0, chunk.length, null);
+      if (read === 0) break;
+      bytes += read;
+      if (bytes > MAX_BYTES) throw new Error('local agent environment payload exceeds 64 KiB');
+      chunks.push(chunk.subarray(0, read));
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message === 'local agent environment payload exceeds 64 KiB') throw error;
+    throw new Error('local agent environment payload could not be read');
+  } finally {
+    try { closeSync(fd); } catch { /* The descriptor is unusable either way. */ }
+  }
+
+  let parsed: unknown;
+  try { parsed = JSON.parse(Buffer.concat(chunks, bytes).toString('utf8')); }
+  catch { throw new Error('local agent environment payload is not valid JSON'); }
+  if (!plainObject(parsed)) throw new Error('local agent environment payload must be an object of strings');
+  const agentEnvironment: NodeJS.ProcessEnv = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!AGENT_CREDENTIAL_NAMES.has(key) || typeof value !== 'string' || value.includes('\0')) {
+      throw new Error('local agent environment payload must be an object of valid environment strings');
+    }
+    if (key !== LOCAL_AGENT_ENV_FD) agentEnvironment[key] = value;
+  }
+  return { ...environment, ...agentEnvironment };
+}
+
+/** Reduce a composed provider environment to the credential overlay that is
+ * safe to serialize across the authored Node runtime boundary. */
+export function localAgentCredentialEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return Object.fromEntries([...AGENT_CREDENTIAL_NAMES]
+    .flatMap(key => environment[key] === undefined ? [] : [[key, environment[key]!]]));
+}
+
+/** Validate the parent-to-authored-runtime handoff without touching a descriptor. */
+export function validatedLocalAgentEnvironment(value: unknown): NodeJS.ProcessEnv | undefined {
+  if (value === undefined) return undefined;
+  if (!plainObject(value)) throw new Error('local agent environment payload must be an object of strings');
+  const environment: NodeJS.ProcessEnv = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (!AGENT_CREDENTIAL_NAMES.has(key) || typeof entry !== 'string' || entry.includes('\0')) {
+      throw new Error('local agent environment payload must be an object of valid environment strings');
+    }
+    environment[key] = entry;
+  }
+  return environment;
+}
+
+function plainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value) as unknown;
+  return prototype === Object.prototype || prototype === null;
+}

package/src/local-agent.ts

@@ -15,6 +15,7 @@ export async function attachLocalAgent(
   capacity: number = DEFAULT_LOCAL_AGENT_CAPACITY,
   runRoot?: string,
   declaredStreams: readonly string[] = [],
+  environment?: NodeJS.ProcessEnv,
 ): Promise<{
   stream: string;
   readonly failure: unknown;
@@ -31,7 +32,7 @@ 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, runRoot,
+    dataDir, onPtyReady, runRoot, environment,
     pins: { workspace: [], streams: [...new Set([stream, ...declaredStreams])]
       .map(stream => ({ stream, read_offset: 0 })) },
   });