Run connected steps

Run actual project inputs through connected Blocks and retain each completed result.

Inspect a specific run

In a project's Flow view, select a live run to see its captured input connections, or select a historical attempt to inspect its saved evidence. Current connections remain a separate planned view. Missing captured input records are shown as unavailable; the host does not reconstruct them from today's source choices.

Ask chat about this run captures the selected receipt, including batch item, attempt and loop pass when recorded. The native controller resolves that receipt again through authorized saved-project inspection. Unsaved or evicted receipts are unavailable to that saved-project read; another attempt is never substituted. Legacy run-only targets are accepted only when exactly one receipt matches.

Host integrations use projectFlowRunReceiptIdentity(record) from packages/block-platform/flow-inspection.js for the bounded receipt:<placementId>:<identity> conversation scope. This is a locator, not an access grant. Resolve it within the authorized project's placement history and require exactly one match. Inspect/read operations neither run a Block nor change its source. Existing retained-history limits still apply.

Failure and recovery evidence

Flow distinguishes EXECUTION_FAILED from RESULT_DELIVERY_FAILED (a result returned, but delivery to the project was interrupted) and RESULT_SAVE_FAILED (a result returned, but project saving was not confirmed). The latter states show Needs recovery rather than implying that generation produced nothing. Recovery must use the supported request/result controls before a new paid run is considered.

The original failed-attempt record remains in history. If a matching provider result or exact run/input/item receipt is later retained, its history entry gains recovered: true and the current failure warning clears. This does not mean a retained result was selected. Diagnostics contain bounded codes and duration; raw provider messages, prompts and media addresses are excluded.

Run connected Steps

Inside a Project Type, Run connected steps runs the selected recipe or isolated JavaScript Step and the following supported connected Steps in workflow order. The host captures the exact Project Type, package versions, current settings, conditions and connections. Every input comes from current project data, supplied values, declared context, or an actual upstream output. Production runs never prefill missing values from package test fixtures.

A connected run stops before a manual workspace, a Block requiring separate runtime approval, or an unconnected Step. The UI shows the ordered sequence and stopping point; it does not ask users to wire a graph. ComfyUI, hosted workspaces and generation are not silently dispatched as part of this local sequence. They retain their own execution and confirmation paths.

The shared host helper is packages/block-platform/segment-runner.js:

const plan = await planSegment(projectType, canvas, startingStepId);
const result = await runSegment(plan, {
  source: selectedSource, // stable source/version identity, when applicable
  inputs: { [startingStepId]: currentInputs },
  externalInputs: currentInputsFromOutsideTheSegment,
  resolveContext: (step, source) => scopedContextFor(step, source),
  execute: (pkg, input, { signal, check }) => runInTrustedHost(pkg, input, { signal, check }),
  check: () => verifyCurrentSourceSettingsPermissions(),
  onStep: record => retainCompletedResult(record),
  signal,
});

Custom durable hosts can opt into stateful sandboxed segments with planSegment(type, canvas, startingStepId, {background: true}). Then call runSegment(plan, {background: true, states, ...options}), where states supplies {version, value} for every stateful Step ID. Background plans pin code, settings and connections independently of current memory. The runner never mutates the supplied memory. Keep the starting memory snapshot with the job; resuming previousResults verifies it and refuses changed inputs or memory. Persist returned states only in the same transaction as the completed workflow results. A failed later Step can retain earlier provisional results, but those results must not advance shared memory prematurely. This mode does not authorize hosted APIs or ComfyUI. StillMade's scheduled multi-Block service uses this mode with shared Canvas editing enabled. It pins the job's starting states, retains provisional checkpoints after failures, and commits all memory changes with the completed workflow. Selecting a retained result does not apply its memory a second time.

This helper is a host orchestration API, not a capability exposed to guest code. The host owns permissions, quarantine checks, media decoding/storage and durable adoption. externalInputs is keyed by target Step ID then port name, and may only fill declared connections from outside the segment. Internal connections always use outputs produced earlier in the current run. Context access follows each Block's own declarations. A false condition uses the existing typed bypass rule. Missing inputs, incompatible roles or stale package/settings pins stop execution. Pinned safe connection conversions run in the host before each receiving Block. They recheck actual media kinds and authorized current context; a failed conversion retains completed upstream results and stops before the receiving Step. They do not add a provider call or silently select replacement media.

For an explicit batch selection, a trusted host can set overridePrimary: true with its already-authorized media source. This replaces only the first Step's primary input; it must match that input's type and role. Do not put this receiver-typed source into externalInputs as though it were a raw upstream shot or scene. Ordinary connected runs leave the option false. The host records primaryInputOverride when a connection was bypassed, and must preserve that choice when validating retained results. This option grants no asset access: the host still validates ownership, selection, permissions and source freshness.

The immutable plan has workflowDigest, planDigest, startStepId, ordered steps, nextStageId, and stopReason. result.steps contains one record per completed placement: stepId, packageDigest, inputDigest, outputs, skipped, at, and optional host mediaReceipts. Identical Blocks at two positions retain separate records. On failure, error.partialResult retains completed records; later Steps are not reported as completed. A host can supply previousResults only as an ordered prefix whose source, input and package digests still match. Cancellation or failure cannot turn a stale partial result into a new success.

Project handoffs and Flow inspection

Saved shared tasks use PROJECT_FLOW_OPERATIONS.inspectTasks (inspect_project_tasks, projects:read) and controlTask (control_project_task, separately granted projects:control plus projects:read). These do not require navigation or a live tab. Inspection returns bounded current task pages or one exact taskId. Control accepts pause/takeover/cancel/resume with exact requesterId, taskRevision, instructionRevision, controlEpoch and a unique requestId; current project and connection authority are checked in the transaction. Identical replay returns its original receipt plus current task state without reapplying. Resume queues the existing revalidation process and never approves dispatch, spending or edits; takeover preserves requester/payer. Accepted provider work may still finish after pause/cancel. Native task controls share the coordinator through their existing UI, so their registry nativeAction is null. Native and external controls both require the complete observed fence; older native payloads fail with PROJECT_AI_REFRESH_REQUIRED instead of changing newer task intent. See saved task control details.

recover_project_capability_request retrieves one actor-owned project request under projects:read + runs:read and the existing current edit-access requirement. It verifies retained source/media and an unchanged request ledger before returning bounded, redacted stored outputs with applied:false and selectionChanged:false. It does not poll a provider, execute, settle, save or select a result. Truncated output envelopes are excerpts. Applying a retained result remains a separate reviewed native recovery action.

The in-app Project Type Builder accepts pinned built-in stages and embedded recipe packages in an optional packages array. Each stage uses {id,blockId,version,label}; connections use {from:{stage,port},to:{stage,port}}. Duplicate dependencies, missing versions, incompatible ports, duplicate input producers, cycles, and root chat overrides are rejected. Embedded recipe fixture tests must pass before launch or release.

Executable custom types combine embedded SDK processing Blocks with the existing production workspaces: Voiceover, Script Writer, Shots, Blueprint, Canvas, Image Panels, White Board Motion, animated assets, Editor and Export. The workspace adapter selects the existing production screen for each placement. Legacy component adapters remain available to saved types; they do not become separate workspace listings. Custom JavaScript, recipes and reviewed ComfyUI packages open in their own Step workspace. Run them explicitly; navigation never triggers paid generation or automatic reruns.

Connections use declared SDK ports or an implemented host port adapter. Canvas and Editor workspaces share persistent project documents; listing a port does not invent an executable conversion. The builder validates supported handoffs and explains when a host port or conversion is not implemented. Script Writer's script-to-Voiceover handoff uses the existing narration document. Starting Chat remains protected before the configurable flow.

Project Flow inspection contract

The SDK exports ProjectFlowTarget, projectFlowTarget() and projectFlowSnapshot() from @stillmade/block-sdk. Targets use stable project, placement, input/output, run, attempt and repeated-item IDs; display names and screen positions are not target identity. A target may name the planned, active_run or historical_run perspective. The snapshot validator checks its contract version, definition identity, unique placement IDs, receiving edges, completeness flag and documented size bounds. External inspect_project_flow reads also return a host-computed snapshotCursor; use that exact cursor when reviewing or applying a saved-project source or result-pin change. redactProjectFlowMediaAddresses() recursively removes media address fields from preview projections before they cross into chat or another client surface. When present, a placement's optional condition summary contains its input key and safe label, bounded field path, supported operator, and the last applied outcome (unknown, ran, or skipped). It deliberately omits the comparison value. A current skipped conditional output and its receiving input use the skipped state with no materialized value; this is distinct from a missing result. Historical skipped attempts retain a skipped history status. Saved activity and history may include a bounded execution summary: execution kind, whether output was captured or omitted by a conditional skip, and a capped media-receipt count. It contains no provider run IDs or playable URLs and does not establish provider activity for an attempt without a saved Block receipt.

PROJECT_FLOW_OPERATIONS maps the shared operation IDs to the native action and external tool names. updateAffected maps to the existing native update_affected_steps action; it runs eligible live-workspace Steps, with a whole-update budget and separate exact generation review for hosted execution, and has no saved-project external tool. useCompletedResults maps to the native use_completed_results action; it adopts retained connected-workflow outputs in the live workspace after the host revalidates their receipts, without dispatching generation, and has no saved-project external tool. These SDK helpers validate a data shape and map operation names; they do not grant access to a project, authorize a mutation, or dispatch a Block. Hosts resolve every ID and filter labels, previews, candidates and history against current permissions. The current saved-project operations are inspect_project_flow, list_project_flow_placements, list_project_flow_ports, list_project_flow_history, list_project_flow_run_inputs, read_project_flow_text, recover_project_media, diagnose_project_flow, preview_project_flow_source, change_project_flow_source, preview_project_flow_pin, pin_project_flow_result and clear_project_flow_pin; write operations require the current projects:write grant and exact preview revisions. They never run a Block. Reruns, retries and costly review remain separate authorized actions.

Native list_placements, list_ports and list_history use the same bounded projection as those three saved-project page tools. Each requires the exact revision from its own preceding inspection: native surface revisions and saved-project revisions are different and cannot be interchanged. A placement page accepts at most 8 rows; ports and retained history accept at most 16. Later pages of inspect_project_flow also require expectedRevision. Membership and project ownership are checked again after saved reads.

For example, after inspect_project_flow({projectId}) returns revision, read list_project_flow_history({projectId, placementId, revision, offset:0, limit:8}) and continue with the returned nextOffset. Each entry includes a receiptId and targetKey identifying the exact attempt/item, plus recorded input evidence. Use targetKey for chat receipt targeting; several entries may share runId. historyComplete:false distinguishes incomplete retained history from the end of a page. retainedHistoryComplete:false still applies at the last page; this operation cannot recover evicted records or missing historical input evidence. inputsTruncated:true means only a bounded subset of captured input identities was included. The receipt exposes inputsCount, inputsRevision, inputsNextOffset and inputsRetainedComplete. Use native list_run_inputs or external list_project_flow_run_inputs with {placementId, receiptId, revision: inputsRevision, offset, limit} (plus projectId externally) to read at most 16 named captured-input identities per page. This captured-input revision is different from the surface/Flow revision. Every page rechecks the exact retained receipt and current read permission; changes beyond the initial 64-input projection also invalidate its revision. A source's present selection never replaces the recorded identity. Follow nextOffset until null; a final page with retainedComplete:false still indicates missing original evidence. The run capture stores at most 128 named inputs. A capture at that limit may have omitted identities and is conservatively marked incomplete. Preview attempts also have a 64-input cap and a byte limit. An older preview may have retained fewer identities than the original run; paging cannot recover those lost entries. Nested collection member identities remain bounded within each input; this operation pages named inputs, not raw values, full text, or the members of captured collections. The historical inspector's Previous/Next inputs controls keep its map on that exact input page. None of these reads starts work, applies results, or proves media playback. The native summary exposes historyTotal and historyNextOffset so three displayed receipts are never reported as the whole retained history.

Retained unselected results have a separate read-only inventory. The Result tab shows eight candidates at a time. Use native list_retained_results or external list_project_flow_retained_results with {placementId, revision: unusedResultsRevision, offset, limit} (plus projectId externally); list pages contain at most eight candidates. Only records still retained for the current Block package are included: unused single results, unselected connected results, and batch records explicitly marked unused after a source change. The ordinary batch picker is separate. historyComplete:false means evicted history is not recoverable through this inventory, even at its final page.

Each candidate has an exact candidateId, outputDigest, run/item/attempt metadata, and captured-input/output counts and cursors. Native inspect_retained_result and external inspect_project_flow_retained_result accept {placementId, revision: unusedResultsRevision, candidateId, section, offset, limit}. Sections inputs and outputs page at most 16 identities or previews. Sections text and collection also require outputKey and the exact preview path; text requires its returned identity and permits at most 4,000 characters, collections at most 16 members. Reuse the exact candidate and list revision on every page. Changes anywhere in retained records, package or preview restrictions invalidate that revision. Inspect fresh state after a conflict. Current project read access is rechecked after saved reads; native/UI caches reset when the authorized reader changes. External/native results redact media addresses. Sensitivity and prior preview restrictions still apply; a restricted candidate cannot become inspectable through a later page. Captured inputs remain bounded metadata and may be incomplete; nested structured previews disclose omitted fields rather than claiming a complete document. These reads never select a candidate, restore media, dispatch work, or substitute current output for a retained value.

Mapped native Canvas outputs use the installed exact-version host port adapter. Flow can show a saved image, video or text value as ready with observation.kind: "native-canvas-output" and runReceiptAvailable:false. The Inspector labels that value Available; it does not invent a completed run, receipt or result pin. The exact selected asset/version is preserved in Result and Using. Missing values, mismatched host identities and navigation-only workspace ports remain unavailable. ProjectFlowNativeObservation describes this read-only origin; normal output/source paging retains its identity. Native production-workspace connections also use the exact installed host manifest and declared port handles; a newer catalog release cannot redefine an older pin. Original standalone nodes without placement/version metadata retain their historical 1.0.0 contract. Unknown, mismatched and non-host pins cannot impersonate a production workspace.

Whole-project Script retains its original narration source. Transcript uses the selected Voiceover take’s recorded transcript and word timings, independently of the editable narration draft. Older takes without stored transcript text derive it from their own timed words. A new Transcript-only run protects the original Voiceover document; changing an unrelated narration draft does not invalidate it. Original legacy receipts that also include Script remain valid with their stricter source checks. An older proposal cannot replace original reads with current documents, and a legacy result lacking derived proof must be rerun before guarded adoption. Other derived fields and arbitrary dynamic reads require separate attribution. Scoped narration and supported shot/scene collections capture their original Blueprint, Shot Plan, Animation, Panels and Board contributors, including empty originals whose later additions could change the result. They do not substitute the whole-project Script. Native asset inventories, generation records, scoped version histories and character/location/style collections can now retain their original contributor and membership proof when canonical reconstruction exactly matches the consumed value. A bounded v2 Canvas projection excludes only the exact host-dispatched producing placements while retaining their IDs/types, so saving their own output does not invalidate native collection membership. Current saved executable asset/generation members can retain their original selected-output, state and native-source evidence when exact canonical reconstruction matches the consumed collection. A producing placement’s own consumed previous output is captured separately when provable. Ambiguous, legacy, archived, private or unsupported collection members, local-only media, whole-project version metadata and noncanonical source documents remain unproven. v1 source reads stay compatible; new v2 captures require explicit server support. Media-dependent narration and arbitrary dynamic reads still require separate attribution.

Stateful host runs retain the exact starting-memory identity and resulting-state digest alongside original input/output evidence. Original native reads carry through subsequent memory transitions, connected batches, loops and checkpoint recovery. Declared initial/reset memory is distinct from legacy saved memory even when its bytes match; old receipts cannot gain proof from current documents or by removing a warning. Missing or changed state proof blocks protected workspace adoption. This is host-maintained provenance, not cryptographic attestation against rewriting an entire saved receipt. Older retained plans/checkpoints may require their existing recovery/reset path when the new memory evidence changes the plan identity.

Task-authored final Canvas adoption can bind the original native read union to the same transaction as the current task and Canvas execution checks. The host's taskSourceReadSet is retained in the exact save/recovery receipt, with explicit assistantSourceReadSetVersions capability negotiation. A lost response is recovered by reading the original commit; it does not resubmit an old proposal over newer work. Stale completed results may still be retained for review. Manual selection in saved Canvas projects now uses an acknowledged source save with the original native read union and sourceCanvasPrecondition, negotiated with sourceCanvasPreconditionVersion:1. Source roots and current execution content are checked under the same ordered transaction locks; layout-only changes are preserved. Exact request recovery distinguishes applied, not-applied and unresolved saves, including no-op selection, without replaying old work over newer selections. Servers without the capability refuse selection. Local drafts and unused-result retention remain separate. Legacy results do not gain missing original-source proof. Remaining native/background producers require separate coverage.

The saved-project inspector and compact handoff can open the exact source Block workspace through existing draft-save navigation guards. Account, project, read access, placement and matching package source are checked after drafts finish saving. The existing Editor opening suppresses automatic narration import/export for this navigation request. Previews without workspace navigation say Inspect source Block. Compact handoffs show required inputs needing attention even when the primary value is ready; Using targets the first such input.

Large Flow connection lists page 40 placements and offer Find a Block with direct keyboard access. Exact input links remain available after search. The map keeps its own bounded pages and selected neighborhood. Unchanged bounded scalar activity reports reuse the shared projection; new captured evidence, source changes and revoked access invalidate the relevant view.

External controllers can review one complete retained local connected run with preview_project_flow_completed_results, then select it using use_project_flow_completed_results. Apply requires the exact returned Flow, Canvas and candidate digests, a new request ID and the current task fence. Every selected row must have its original sealed v2 source receipt. The server validates the existing plan and original source roots, rechecks project/connection/task authority, and saves through shared Canvas operations. An acknowledged retry returns its original receipt without selecting the result again, even if the current selection has changed.

This external path supports complete recipe/JavaScript connected runs with current inputs, asset-descriptor batches with non-media outputs, and shared complete local loop receipts. All-assets, scene and selected-shots batches require the original complete inventory receipt captured and acknowledged before dispatch; it binds the original scope, ordered targets, exact plan and eight contributing workspace roots. Preview and apply check those original roots again, including workspaces that were empty when the batch started. JavaScript memory transitions require exact initial, reset or retained starting identity and resulting state with original sealed proof. Preview exposes digest-only stateChanges; apply saves the original outputs and memory without executing them again. Legacy/unproven or changed memory is unavailable. Hosted execution, decoded/generated media, incomplete runs and failure-recovery results still use their existing workspace review. Broad batches without original inventory proof remain unavailable; current inventory cannot be substituted for missing historical evidence. Inventory membership and each consumed item’s output or memory lineage are separate requirements. A local preview does not establish shared source proof. Preview and apply never dispatch a Block, load media, request model analysis or spend credits. A source/authority conflict keeps the retained result available for review; it does not silently rerun the workflow.

Completed local loops can retain their exact whole receipt in shared Canvas history without selecting outputs or advancing memory. A failed shared save preserves the original device checkpoint. Shared retainedLoopRuns summaries expose bounded run identities, pass counts and current selection for review; they do not claim revalidation. Retention is limited to four envelopes, 512 KiB per envelope and 1 MiB total per starting placement; exceeding a bound keeps device recovery and reports the limit rather than evicting old history. External selection validates the original whole loop and every consecutive pass against current sources, memory, task and authority, then uses the existing adoption path without dispatch. In the native workspace, another editor can explicitly choose a shared run without its original device checkpoint. Review validates the original complete receipt; Use rechecks its shared identity and the reviewed Canvas execution state before acknowledged selection. A newer selection or changed source requires fresh review.

Shared loop pass inspection uses the existing list_project_flow_retained_results and inspect_project_flow_retained_result operations. Initial discovery exposes bounded historical identities; explicit inspection verifies the original whole envelope before returning captured input identities and paged output/text/collection previews. It validates original evidence without requiring today's inputs to match, and does not select or execute the pass. Changed original history or revoked read access invalidates the response. Native Result review uses the same verified reader through Inspect saved pass.

Existing-media and host-action selections carry explicit selection metadata. Flow separates them from worker execution receipts and attempt history; a media selection identity is not a run ID. Saved selection still checks current authority and the reviewed Canvas/source state.

External connections must explicitly opt into projects:write alongside projects:read for reviewed Flow input, pin, result/memory changes and saved-media restoration. Defaults and existing connections do not gain permissions. Shared Flow reads recheck current connection authority after asynchronous work; all four Flow mutations recheck it in their write transaction, including replay. Media restoration rechecks through its existing before-write guard. Revocation, expiry, project/scope changes and suspension invalidate stale authority.

Completed background results

In a saved Block workspace, open Background results beneath the result area to review already completed jobs. Editors can explicitly select a result whose original input, output and memory proof remains valid for the current project; viewers can inspect it. Selection rechecks the exact job, project, Block version, sources and shared Canvas and does not execute the Block or advance saved memory. Legacy jobs, pending validation journals and results with missing original source proof remain preview-only. Current source documents never replace missing original evidence. Connected fallback/bypass and unsupported derived sources may therefore remain unavailable for selection.

Use the + between project placements to add a Block. Edit workflow in that dialog opens the ordered builder for adding, removing, disabling, duplicating, replacing, reordering and configuring placements. Changes remain a draft until Save workflow. A changed source requires a new Block version; the same ID/version cannot silently acquire different code.

Removed, disabled, replaced or changed placements retain their SDK package (or built-in host contract), settings, prior results and connections in Workflow history. The old placement is inactive; it is not run by autosave or future-media automation. Re-enabling the same placement and source can recover its results for review, marked stale until rerun. Changing a producer or its inputs also marks affected downstream results stale. Each history entry offers Download Block + SDK. SDK packages come from that retained instance; built-in downloads follow the current-client source behavior described above. Scoped SDK versions context includes retained media as inactive previous versions; archived results do not become current assets or new generations.

The full definition and selected stage travel with project/session saves. A newer installed type cannot replace an existing project's pinned definition. Use node packages/block-cli/cli.js create-type my-type.json, then test, preview, and pack on that JSON file. preview rehearses connected sandbox Blocks using fixture inputs and actual upstream outputs. It marks hosted workspaces as requiring a real project and never calls paid providers. examples/text-workflow.stillmade.json is a complete example. The broader editor command/workspace SDK is not yet exposed to external recipes. Do not invent ctx.editor, ctx.sql, ctx.shell, ctx.fs or ctx.capabilities methods; none exists in 0.1. Keep unsupported requirements explicit.