@intx/workflow-host 0.2.2 → 0.4.0

package/dist/child/proxy-repo-store.d.ts

@@ -5,8 +5,9 @@ export interface CreateProxyWorkflowRunRepoStoreOpts {
      * Bare substrate handle the child opens against the shared on-disk
      * data dir. Used for the read-only methods that consult the
      * substrate's local state -- `getRepoDir` (path computation, no
-     * I/O), `resolveRef`, `listRefs`, `resolveHead`, `createPack`. The
-     * bare store is never used as a writer here; its
+     * I/O), `resolveRef`, `listRefs`, `resolveHead`, `openCommittedReads`,
+     * `openCommittedReadsAtCommit`, `createPack`. The bare store is never
+     * used as a writer here; its
      * `writeTreePreservingPrefix` / `writeTree` / `receivePack` are not
      * reachable through this proxy.
      */

package/dist/child/proxy-repo-store.js

@@ -117,6 +117,8 @@ export function createProxyWorkflowRunRepoStore(opts) {
         listRefs: bareStore.listRefs.bind(bareStore),
         resolveHead: bareStore.resolveHead.bind(bareStore),
         getRepoDir: bareStore.getRepoDir.bind(bareStore),
+        openCommittedReads: bareStore.openCommittedReads.bind(bareStore),
+        openCommittedReadsAtCommit: bareStore.openCommittedReadsAtCommit.bind(bareStore),
         subscribe(_principal, repoId, ref, subOpts) {
             // Synthesizing the subscribe surface in the proxy: the bare
             // store's `subscribe` would only fire from its own writes, but

package/dist/child/run-child.d.ts

@@ -1,14 +1,18 @@
 import type { Principal, RepoId, RepoStore as SubstrateRepoStore } from "@intx/hub-sessions/substrate";
-import type { DirectorRegistry } from "@intx/agent";
 import type { AuthzCallResult } from "@intx/inference";
-import type { RunResult, Scheduler, StepInvokeRequest, StepInvokeResult, SpawnChildWorkflow, WorkflowAuthorizeFn } from "@intx/workflow";
+import type { RunResult, Scheduler, ReadParkedApprovalOps, StepInvokeRequest, StepInvokeResult, SpawnChildWorkflow, WorkflowAuthorizeFn, WorkflowDefinition, WorkflowPark } from "@intx/workflow";
 import { type WorkflowHostDrainController } from "../drain-controller.js";
-import type { InferenceSource } from "@intx/types/runtime";
+import type { InferenceSource, MailPartReader } from "@intx/types/runtime";
+import type { CredentialDelivery } from "@intx/types/sidecar";
+import type { RunSuspendableChild, RunChildWorkflow } from "../adapters/spawn-child.js";
 import { type ControlChannelSender, type ControlPayload, type EventPayload, type FrameWriter, type NdjsonReader, type NdjsonWriter } from "../ipc/index.js";
 import type { CredentialsSnapshot } from "../supervisor/credentials.js";
 import { hashGrants } from "../supervisor/credentials.js";
 import type { SpawnTimeEnv } from "./env-bootstrap.js";
+import { type LoadParkedApproval } from "./parked-correlations.js";
 import type { ChildOutboundMailBridge } from "./outbound-mail-bridge.js";
+import type { ChildMailboxMutationBridge } from "./mailbox-mutation-bridge.js";
+import type { MailboxWatchRegistry } from "./mailbox-watch-registry.js";
 import { type WarmAgentCache } from "./warm-agent-cache.js";
 /**
  * `WorkflowAuthorize` closure factory shape. The child's authorize
@@ -27,6 +31,18 @@ import { type WarmAgentCache } from "./warm-agent-cache.js";
 export type CredentialsSnapshotRef = {
     current: CredentialsSnapshot | null;
 };
+/**
+ * The deployment's decrypted credential material and per-handle descriptors,
+ * held through a mutable reference. A `credentials-updated` frame MERGES into
+ * this cell (materials by credentialId, bindings by (consumer, handle); an
+ * explicit `revoke` list drops entries) rather than replacing it wholesale,
+ * because the cell has several independently-scoped producers. The secret lives
+ * ONLY here -- read at tool-invoke time through the gated capability -- and is
+ * never copied into a snapshot, event, or state.
+ */
+export type CredentialMaterialRef = {
+    current: CredentialDelivery | null;
+};
 /**
  * Per-step inference-source table the build path reads through a mutable
  * reference, keyed by stepId. Each value is the step's ordered failover
@@ -92,7 +108,24 @@ export type DrainController = WorkflowHostDrainController;
  * by the run-loop (`runWorkflowChild`), not the binding: the binding
  * only reads it through to the adapter.
  */
-export type ChildStepInvoker = (req: StepInvokeRequest, onEvent: (event: EventPayload) => void, authorize: WorkflowAuthorizeFn, warmCache: WarmAgentCache | undefined, sourcesRef: SourcesSnapshotRef) => Promise<StepInvokeResult>;
+/**
+ * Per-run credential inputs the top-level step invoker carries to the
+ * substrate: the live material cell the control channel writes each delivery
+ * into, and a resolver for a step's grants (which the substrate gates
+ * credential use against). The substrate combines these with its own static
+ * provider registry to assemble each tool bundle's `credentials` capability.
+ *
+ * Grants are typed `readonly unknown[]` here: this package owns no grant
+ * grammar (the credentials snapshot's grants are `unknown[]` throughout), so
+ * the substrate casts to its `GrantRule` shape at its own boundary, exactly
+ * as the grant evaluator does. The cell is read live per use, so a rotation or
+ * a revoking re-push reaches an already-shaped handle without a rebuild.
+ */
+export interface CredentialWiring {
+    readonly materialRef: CredentialMaterialRef;
+    readonly resolveStepGrants: (stepId: string) => readonly unknown[];
+}
+export type ChildStepInvoker = (req: StepInvokeRequest, onEvent: (event: EventPayload) => void, authorize: WorkflowAuthorizeFn, warmCache: WarmAgentCache | undefined, sourcesRef: SourcesSnapshotRef, credentialWiring: CredentialWiring, mailPartReader: MailPartReader) => Promise<StepInvokeResult>;
 /**
  * Bindings the binary owns: per-deployment substrate identity,
  * principal credentials, the runtime-supplied callbacks the
@@ -114,10 +147,6 @@ export interface RunWorkflowChildBindings {
      * the host's substrate accepts for `runs/<runId>/` writes.
      */
     principal: Principal;
-    /** Workflow-asset repo identity (used to load `workflow.json`). */
-    workflowDefinitionRepoId: RepoId;
-    /** Workflow-asset ref the deploy orchestrator wrote to. */
-    workflowDefinitionRef: string;
     /**
      * Step-invoker callback the runtime body invokes per step. The
      * shape is the workflow-runtime `StepInvoker` widened with an
@@ -128,11 +157,51 @@ export interface RunWorkflowChildBindings {
      */
     invokeStep: ChildStepInvoker;
     /**
-     * Child-spawn callback the runtime body invokes for `childWorkflow`
-     * primitives. The production binary wires this against
-     * `createWorkflowSpawnChild`; tests inject a stub.
+     * Terminal child-spawn callback the runtime body invokes for a
+     * `childWorkflow` primitive when the deployment embeds NO inline child
+     * import (the map `run-child` lifts is empty). Optional and, in practice,
+     * only a test seam: a production deployment that carries a childWorkflow
+     * always has a non-empty lifted-body map and routes through the in-memory
+     * resolver built from `runChild` below, and one that carries none never
+     * invokes this. A workflow that reaches a childWorkflow with neither this
+     * nor `runChild` wired fails loud at spawn.
      */
-    spawnChild: SpawnChildWorkflow;
+    spawnChild?: SpawnChildWorkflow;
+    /**
+     * Raw in-process terminal child executor. `run-child` builds the in-memory
+     * childWorkflow resolver from this executor plus the lifted-body map it
+     * extracts after loading the definition -- the parent's own re-verified
+     * closure -- so an owned inline child resolves with NO on-disk read. Parallel
+     * to `runSuspendableChild` for onTrigger bodies. Optional for the same
+     * reason: a child that embeds no childWorkflow import omits it.
+     */
+    runChild?: RunChildWorkflow;
+    /**
+     * Raw in-process suspendable-child executor. `run-child` builds the in-memory
+     * onTrigger-body resolver from this executor plus the bodies map it extracts
+     * AFTER re-evaluating the closure -- the substrate factory cannot build that
+     * resolver because the bodies map does not exist pre-eval. Optional: a child
+     * that runs no onTrigger section omits it.
+     */
+    runSuspendableChild?: RunSuspendableChild;
+    /**
+     * Materialize a loop iteration run's own `runs/<childRunId>/grants.json`,
+     * inheriting the parent (container) run's grants capped to the loop body's
+     * declared resources. A loop iteration runs through the workflow-host-local
+     * loop executor (the inherited env), NOT the sidecar's `buildChildRunEnv`, so
+     * it is the one body birth path that does not otherwise write its own grants
+     * file -- and without it the body's `childWorkflow` grandchild spawn is
+     * refused as under-authorized. Wired by the sidecar (the grant-cap helpers
+     * live there); optional so a test or an in-process host that never spawns a
+     * grandchild from a loop body can omit it. `definition` MUST be the PRE-rewrite
+     * loop body (grandchild still inline) so the cap keeps the grandchild's
+     * declared resources.
+     */
+    materializeLoopIterationGrants?: (args: {
+        parentRunId: string;
+        childRunId: string;
+        definition: WorkflowDefinition;
+    }) => Promise<void>;
     /** Host-process scheduler singleton. The child consumes the same instance. */
     scheduler: Scheduler;
     /** Grant evaluator wired against the host's grant-rule grammar. */
@@ -152,8 +221,45 @@ export interface RunWorkflowChildBindings {
      * adapter (which roots no per-run scratch of its own) can omit it.
      */
     cleanupRunStorage?: (runId: string) => Promise<void>;
-    /** Optional director registry; defaults to the canonical built-ins. */
-    directors?: DirectorRegistry;
+    /**
+     * Recover the durable approval snapshot for a parked control-plane
+     * correlation, so the child can answer a supervisor
+     * `parked-correlations.request` (the supervisor's re-registration path
+     * after a re-establishment). The child owns enumeration -- it walks its
+     * own reduced run state for `awaiting-signal` steps on control-plane
+     * channels -- but the snapshot lives in per-step durable storage whose
+     * on-disk layout (cold vs warm) the host owns, so the read is a host
+     * binding next to `cleanupRunStorage`. Optional so tests inject a stub and
+     * the recursive child-workflow adapter (which roots no per-step approval
+     * storage) can omit it; a production child that enumerates a parked
+     * control-plane step with no binding wired throws rather than silently
+     * dropping the correlation the hub is waiting to register.
+     */
+    loadParkedApproval?: LoadParkedApproval;
+    /**
+     * Enumerate the durable pending approval operations a crashed-mid-invocation
+     * step left behind, so the resume classifier can recover a step that crashed
+     * across the park boundary (durable `StepStarted`, unflushed `SignalAwaited`)
+     * as `awaiting-signal` rather than failing the run. Reads the same per-step
+     * durable storage as `loadParkedApproval` (cold isogit / warm substrate), so
+     * it is a host binding for the same reason. Optional so tests inject a stub
+     * and the recursive child-workflow adapter can omit it; absent, a crashed
+     * invocation step settles as a terminal failure, the pre-recovery behavior.
+     */
+    readParkedApprovalOps?: ReadParkedApprovalOps;
+    /**
+     * Mailbox watch registry backing the warm agent's `mail_wait` (INBOUND half
+     * of mailbox ownership, §3b). The host's substrate factory builds ONE
+     * instance at child boot, shares it with the step agent's supervisor-backed
+     * transport (whose `watch` registers callbacks into it), and exposes it here
+     * so the control loop routes each `mailbox.notify` frame to the same
+     * registry's `fire`. Optional: a deploy that wires no mail surface (and the
+     * recursive child-workflow adapter) omits it, and an inbound `mailbox.notify`
+     * frame is then logged and dropped. A test may instead inject a registry
+     * directly through `RunWorkflowChildOpts.mailboxWatchRegistry`, which takes
+     * precedence.
+     */
+    mailboxWatchRegistry?: MailboxWatchRegistry;
     /** Optional clock override; production wires `() => new Date()`. */
     clock?: () => Date;
     /** Optional id generator override; production wires a monotonic one. */
@@ -173,6 +279,14 @@ export interface RunWorkflowChildBindings {
      * rather than resolving a default.
      */
     initialSources?: Record<string, InferenceSource[]>;
+    /**
+     * Bootstrap credential material for the deployment's tools, decrypted
+     * hub-side and delivered on the deploy frame so it is resident before any
+     * step runs. Seeds the mutable `credentialMaterialRef` the gated capability
+     * reads. Absent when the deployment binds no credentials; a later
+     * `credentials-updated` control frame refreshes it on rotation.
+     */
+    initialCredentialMaterial?: CredentialDelivery;
     /**
      * Optional override for the child's Ed25519 keypair factory. The
      * child mints a fresh keypair at startup, holds the private half
@@ -249,6 +363,33 @@ export interface RunWorkflowChildOpts {
      * but no agent on the child side asked for an outbound send.
      */
     outboundMailBridge?: ChildOutboundMailBridge;
+    /**
+     * Optional mailbox-mutation bridge (INBOUND half of mailbox ownership,
+     * §3b). The step agent's mail tools mutate the INBOX -- flag writes and
+     * `expunge` -- through a transport whose write methods route through
+     * this bridge: it emits a `mailbox.mutate.request` upstream control
+     * frame and resolves once the supervisor's matching
+     * `mailbox.mutate.response` lands. The control loop routes the
+     * downstream response frame to the bridge's `handleResult` and invokes
+     * `cancelAll` on any exit path so a pending mutation does not leak an
+     * awaiter after the supervisor tears the IPC down. When omitted,
+     * inbound `mailbox.mutate.response` frames are logged at warn-level and
+     * dropped -- the wire shape is well-formed but no agent on the child
+     * side asked for a mutation.
+     */
+    mailboxMutationBridge?: ChildMailboxMutationBridge;
+    /**
+     * Optional mailbox watch registry (INBOUND half of mailbox ownership,
+     * design §3b). The supervisor -- the sole mail owner -- commits an arrived
+     * message to the workflow-run substrate mailbox and fires a `mailbox.notify`
+     * control frame; the control loop routes that frame to this registry's
+     * `fire`, which delivers a typed `exists` `MailboxEvent` to the callbacks the
+     * step agent's supervisor-backed transport registered through `watch`
+     * (backing `mail_wait`). When omitted, an inbound `mailbox.notify` frame is
+     * logged at warn-level and dropped -- the wire shape is well-formed but no
+     * watcher on the child side asked for inbound events.
+     */
+    mailboxWatchRegistry?: MailboxWatchRegistry;
 }
 /**
  * Narrow interface the child's control loop calls when downstream
@@ -286,6 +427,21 @@ export interface RunWorkflowChildResult {
  * exits cleanly).
  */
 export declare function runWorkflowChild(opts: RunWorkflowChildOpts): Promise<RunWorkflowChildResult>;
+/**
+ * Forward a control-plane suspension to the supervisor over the upstream
+ * control channel. Fired from `env.onPark` each time a workflow agent step
+ * parks on a reserved `signalName(correlationId)` channel. The supervisor's
+ * `park.notify` arm stamps the deployment identity it owns and sends a
+ * `signal.correlation.register` frame to the hub.
+ *
+ * Best-effort like `emitTerminalEvent`'s send: a transport failure is logged,
+ * not rethrown. A lost frame means the correlation is not registered and the
+ * parked run cannot be resumed until it is re-registered; the failure surfaces
+ * structurally as a run that never resumes rather than a silent lifecycle
+ * corruption. The register at the hub is idempotent, so a re-park resume's
+ * re-emit is safe.
+ */
+export declare function emitParkNotify(upstreamSender: ControlChannelSender, park: WorkflowPark): Promise<void>;
 /**
  * Mirror a run's terminal status back to the supervisor over the
  * upstream control channel. Fired once per run from the resume and