Eve library

Agentic run records and recovery: source review

Guide

Revision 1

On this page

Status: counterexamples verified; the three source corrections are applied. The application record binds the reviewed content and preserves the historical proposal at commit 7167e08ce5. Rendering, narration and reader acceptance require their separate current checks. This review does not accept the current Agentic Studio guide. Its remaining registry, invocation, governance, grants, handoff, isolation, mode and pipeline explanations need their own source review. No source-unit teaching assignment is added by this document.

Source pin: 1ceae52c7896a59ac74a4429d410f3218f0b91c6. Primary evidence is libs/oshun/agentic-studio/src/runs/{agent-run,checkpoint,run-controls,replay,streaming-progress}.ts. The existing runs.test.ts suite and the new tools/presentations/tests/pinned-agentic-recovery.test.mjs execute the relevant functions. The feature page is useful context, but several of its broad claims are narrower in code. Do not copy those claims into reviewed explanations.

Corrections that must precede guide acceptance#

Current slide Problem Required correction
agents-lifecycle General terminal-guard wording hides the different fork/retry contracts and can make these helpers sound like a scheduler or authorization boundary. Distinguish ordinary resume from a new attempt; explain suffix-based retry, caller validation and each actual guard.
agents-checkpoints “Matching snapshot” / “mutated envelope” wording overstates a selected-field serialization; the narrative omits the unenforced resume budget. Name the compared fields, include unchanged-ID/changed-content and zero-budget counterexamples, and separate returned state from durable recovery.
agentic-studio-failure The title implies resume requires remaining budget; “envelope changed” overstates what the comparison rejects. Remove the implied budget gate and full-envelope integrity claim; retain the need for current authority, verified storage and restart evidence.

The exact proposed text and source references are in the pending replacements. The dated verification receipt binds the current assembled slide hashes, source bytes, tests and draft. Applying the draft requires rechecking those hashes; do not overwrite a newer editorial revision blindly.

Visual thesis: keep the cream, ink and terracotta reading plane; make the comparison's limited scope the dominant idea, without depicting a checkpoint as a seal of trust.

Content plan: retain the lifecycle vocabulary; contrast the checkpoint helper's actual checks with caller obligations; finish with a changed-artifact worked case. Keep detail in natural explanatory narration and exact source excerpts.

Interaction thesis: preserve existing navigation, source disclosure and reduced-motion-aware transitions. The checkpoint comparison must stand alone in static HTML/PDF; no new motion or interaction is needed to understand it.

The checkpoint draft uses an existing table treatment because the rows describe independent boundaries, not a four-stage execution chain. This is a proposed treatment, not a reviewed visual benchmark. Real embedded/mobile table fit, reading order, all text preservation and PDF legibility remain unverified.

What the checkpoint functions actually establish#

takeCheckpoint records the last completed step in plan-array order, not the most recent completion timestamp. It keeps the intermediate-artifact array by reference. readonly types do not deeply freeze or persist its contents. resumeBudgetUnits, checkpoint identity and time are supplied by the caller; this function does not validate them.

fingerprintEnvelope joins these six groups into a string:

  1. Run ID.
  2. Root agent ID and version.
  3. Sorted completed-step IDs.
  4. Sorted intermediate-artifact IDs.
  5. Sorted output-bundle IDs.
  6. Total cost units.

The serialization is not a cryptographic hash and does not escape identifier delimiters. Two different identifier arrays can therefore serialize equally. More routinely, it omits the tenant, input payload, step descriptions, step-agent assignments and dependencies, tool calls, artifact content fingerprints and persistence keys, bundle membership, evidence and individual resource dimensions. “The envelope is unchanged” is not an inference supported by equal strings.

resumeFromCheckpoint first compares run IDs, then that string. A run-ID mismatch yields unknown-checkpoint; this does not look up a checkpoint in a store. A different recomputed serialization yields fingerprint-mismatch. It does not consult the checkpoint ID, recorded last step, artifact manifest, checkpoint time or resume budget. Zero, negative and nonfinite supplied budgets can pass this local helper. This does not establish that a separate deployed admission boundary would permit execution.

On success, completed step objects are preserved; all non-completed statuses, including failed and skipped, become pending with cleared step timestamps. The returned envelope becomes queued. Terminal inputs are accepted, and the old envelope completion timestamp is not cleared. No queue call, object-store read, content verification or grant resolution occurs here.

preservePartialOutputs appends a <runId>.partial bundle for failed, cancelled or killed runs with intermediate artifacts. Otherwise it returns the existing output array. It does not mutate the input envelope or persist an artifact. Passing its returned outputs back into another call can append a duplicate bundle ID; preservation is not an idempotent storage transaction.

A worked case to teach before discussing recovery readiness#

Use a clearly labeled controlled example: run run-1 has completed an outline step, produced artifact-1, and recorded 12 cost units. Its checkpoint records a zero resume budget. Change artifact-1's content fingerprint and object-store key without changing its ID.

The local comparison still matches and returns a queued envelope. That result does not mean the revised content was verified, the budget admitted another call or the original objects were restored. A caller needs separate authority, artifact-integrity, admission, persistence and dispatch evidence. Conversely, changing the run ID rejects with unknown-checkpoint; changing a compared artifact ID or total cost rejects with fingerprint-mismatch. The contrast teaches exactly what a successful comparison says, rather than making success sound meaningless or universally safe.

This example is executed against the pinned helper, not a production incident or a live tenant recovery. No provider, network, credentials or object store is used by the probes.

Control contracts: do not imply one universal terminal guard#

pause accepts queued, starting, running, awaiting-tool and awaiting-branch-selection. It rejects terminal runs explicitly; paused and awaiting-approval have their own invalid-status result. Ordinary resume accepts only paused. cancel and kill reject terminal inputs, then record distinct cancelled/killed outcomes and completion times.

fork and retryWithChanges do not reject terminal inputs. Fork checks only that the supplied ID differs from the source ID; it does not check nonblankness or reserve a globally unique ID. It queues the copied envelope and records the parent, retaining all existing plan states, artifacts, calls and cost. The fork audit uses the parent's run ID. Caller-side validation is essential before calling this a legitimate new run.

Retry locates the chosen step in the array, then resets that suffix. It does not compute graph descendants: a later independent step is reset, while an earlier dependent entry is untouched. Supplied step overrides can change agent and dependency fields; status and step timestamps are subsequently forced to pending/null. Existing calls, artifacts, outputs and costs remain. These are transformation rules, not permission to reuse effects or widen authority.

chooseBranch requires the waiting status and an existing step ID, even if that step is already completed; it records the choice in the rationale and returns running without modifying the plan. It does not evaluate the separate branch policy. operatorStep advances the first pending entry from paused and returns running, without validating dependency readiness. A second step requires another appropriate transition. None of these pure controls authenticates its supplied actor or requires a nonblank rationale; app/operator policy is a separate layer.

Further learning material required, beyond the three corrections#

The following mechanisms deserve focused implementation explanations, not an expanded claim that the current fourteen-slide overview already teaches them. These proposed learning outcomes do not set a final guide or slide-count cap.

Learning outcome Evidence-backed distinction Worked task
Interpret run accounting Measured usage attributes cost plus tokens, GPU/voice/avatar time, retrievals, external calls and storage; the legacy call helper increments external-call count by one. Compare a measured local call with legacy accounting; explain what the counters actually mean.
Choose a recovery operation Pause/resume, fork, retry and checkpoint recovery have different guards and preservation behavior. Predict retained effects and reset steps before selecting an operation.
Read replay without mistaking it for a full snapshot Timeline entries retain referenced records. Historical projection rewinds selected collections, not the entire envelope. Stop at time 25 and identify data that still reflects a later result.
Separate customer narrative from subscriber authorization Subscriber filtering checks run, tenant and visibility. Customer summarization only filters visibility and sorts sequence. Scope a mixed event collection before presenting any customer narrative.
Validate progress-log inputs Append compares the last event's tenant/run and sequence; it does not validate the whole history or typed input shape. Contrast an increasing valid sequence with malformed or mixed earlier history.

For replay specifically, calls are included by start time, and their later completion/outcome/result fields are retained. A cutoff does not rewind cost, evidence or the envelope's completion timestamp. Plan entries with a completion timestamp at or before the cutoff are preserved regardless of their status; other started entries become running, later entries pending. Artifact/output timestamps use inclusive bounds. The latest supplied applicable status event is chosen without filtering its tenant or run. Callers must supply a correctly scoped collection; the helper is neither an authorization boundary nor a full event-sourced reconstruction.

For progress, shouldDeliverToSubscriber enforces the run match even for a platform operator. Other roles also require a tenant match, then the appropriate visibility tier. summarizeForCustomer has no subscriber argument; passing mixed tenants/runs can expose their customer-visible messages together. Append accepts sequence gaps, compares only the last existing record and permits an empty log's first supplied value without a finite/nonnegative validation pass. The new tests deliberately distinguish these functions' responsibilities.

Source units are still awaiting substantive teaching#

The affected V1/features/agentic-registry-jobs-plans.md units remain unassigned; source-review notes and executable probes are not slide assignments.

Unit ID Section What remains
023a9ac2ae791fed9a4bb403 AgentRunEnvelope Reconcile the fuller code record, optional redacted telemetry and result/effect fields.
8c484761022155aa472f3999 Run cost ledger Teach both accounting helpers and the storage dimension, without inferring actual usage.
e1968ba8a5efcef95fd4f27b Run-status enum Correct the broad universal-control-guard implication.
03513316ef2f93abe2feb2f2 Checkpoint/resume/partial outputs Apply the bounded comparison and recovery corrections above.
3d3d0ac0f0d99b4da235a8b3 Streaming progress Teach subscriber checks separately from summary and append helpers.
74f015a044313ae18b415beb Run controls Explain precise guards, suffix retry, preservation and caller obligations.
74bd80aaf786d69fe577a0a5 Replay Replace a full historical-state inference with the actual partial projection.

Apply and verify after the active narration inputs are stable#

  1. Revalidate this review's source pin, current assembled slide hashes and draft fields. Inspect any intervening source/content changes before merging.
  2. Apply the three pending patches deliberately. Preserve stable IDs and the remaining guide explanations; do not copy this draft into the live catalog without source, editorial and composition review.
  3. Rebuild scripts and preview artifacts. Re-render the three changed tracks, invalidating their old speech fingerprints. None of these, including agentic-studio-failure, was current in the original 177-track baseline. Preserve all 177 without an exception. This corrects the original review's mistaken membership claim; retain its receipt as historical evidence.
  4. Run the new pinned probes, relevant existing package tests, full applicable presentation tests, source/citation freshness and narration decode/pause checks. Added code citations will also require repository/workflow inventory input-hash refreshes where their bound citation index changes.
  5. Run the full Agentic Studio standalone checks, affected embedded center/table checks, actual-audio controls and PDF rendering. Inspect actual-size captures and complete the natural-speed listening/editorial pass. None is supplied by this source-only receipt.
  6. Add reviewed source-unit assignments only after the final slides genuinely explain those units. Then publish the verified corrections and update this pending review, counts and evidence. Do not accept the old guide merely because its audio becomes mechanically current.