Eve library

Agentic admission and execution: source review

Guide

Revision 1

On this page

Status: two replacements and three additional detail slides are applied. The correction file joins the separate recovery and authority drafts. Together they contain eight disjoint replacements and three insertions, yielding a 17-slide Agentic Studio guide. The application record binds exact content. The obsolete admission graph override is retired so the responsibility table is actually rendered. Historical proposal tests retain the 7167e08ce5 baseline; live-content tests separately verify application. Rendering, narration and reader acceptance need their own current evidence. No source-unit assignment or guide acceptance changes in this increment.

Source pin: 1ceae52c7896a59ac74a4429d410f3218f0b91c6. Review compares the feature description and generated execution-field reference with the actual admission helper, dispatcher, legacy plan, governed runner and execute route. Their responsibility boundaries matter more than their introductory comments.

Teaching and composition#

Visual thesis: keep the cream, ink and terracotta reading plane, making a verdict, an attempted call and an observed effect visibly distinct. Avoid a single reassuring dispatch arrow that hides failure between those boundaries.

Content plan: correct the existing envelope/privacy explanation; compare the three execution layers at admission; follow the eligible call path; compare attempt accounting; then inspect the interrupted completion case. The final case separates saved evidence, actual action and the recovery decision into independent columns. It is not a guaranteed three-step recovery protocol.

Interaction thesis: retain existing navigation, source disclosure and reduced-motion-aware transitions. Tables compare responsibilities and outcomes; the sole new flow depicts actual ordering with an explicit conditional network step and early-refusal scope. All meaning must survive static HTML and PDF. No new decorative motion, images or renderer primitives are needed. These are draft choices, not an accepted benchmark or a reader-comprehension pass.

Slide Communication job Pending change
agents-envelope Explain what telemetry can establish Preserve the overview; correct raw-payload, redaction, evidence and accounting limits.
agents-admission Distinguish gate, legacy plan and actual governed path Replace the implied universally wired safety/cost/rate flow with a responsibility table.
agents-execution-path Follow one eligible attempt Add the ordered control, broker, admission, optional network, pending-write and dispatch path.
agents-attempt-accounting Interpret outcomes and resource charges Compare denied, error, okay and partial, then work the budget and finalization cases in notes.
agents-execution-interruption Decide what pending does not prove Show a completion-write failure after a simulated effect, without inventing exactly-once recovery.

Six dry authoring tests bind the two existing slide fingerprints, require three unused IDs and explicit scope, merge all eight replacements and three insertions in memory, preserve the original reading order, and validate the current rendering, source and paragraph-speech contracts. They write no live content or delivered artifact. Layout geometry, accessibility, PDF readability, actual narration and willing-reader comprehension remain separate gates.

Gate versus runner#

admitToolCall first rejects a terminal run, then evaluates safety, each supplied budget in order, and an optional token bucket. It returns next state, warnings or refusal; it invokes no tool and does not persist or consume measured usage. It has no general paused/waiting-state guard. Its budget-stop copy is not an automatic resumption implementation.

dispatchGuardedToolCall calls its injected callback only after admission. It does not manufacture attempt telemetry, persist results or meter actual usage. An exception from the callback rejects its promise.

The legacy runGuardedToolPlan passes the same supplied budget meters, clock and switch list at each iteration. It explicitly passes throttle: null. The controlled example executes two calls against a 15-unit cap and unchanged 10-unit projections because no measured consumption occurs here; its envelope still has no call records or costs. A paused envelope can also pass through this lower-level path. This is not a bypass demonstration against the HTTP route, which uses a different runner.

runGovernedToolPlan also passes throttle: null, but owns a sequential attempt loop with private consumed meters, refreshed run status and switches, broker authorization and optional persistence. Only running/starting states are eligible. A throttled result type or unreachable handling branch does not establish that a token bucket is wired into either plan runner.

Actual governed and HTTP boundaries#

The route authenticates the caller and uses verified actor/tenant identity, server target attributes and server-owned tool policy. Missing tools or policy fail closed. Configured caller-scope checks and existing-run ownership/state checks precede execution. Bounded low/medium tools may use exact per-run policy grants; advanced authority needs an injected pre-approved broker. The broker's own permission checks are distinct from the execution probes' scripted broker.

The governed runner validates present entries of all planned estimated, denied and failed usage policies before its initial persistence hook. Before each reached call it resolves eligible run status, asks the broker, resolves switches and projects each budget using the larger of request units and estimated category usage. Authorization denial happens before safety admission; that path charges and records the configured denial.

Network authorization additionally requires an adapter preparation hook and broker revalidation of the reported URL, method and connected address. Missing preparation, a preparation exception and a rejected destination have different denial/error paths. The runner then awaits its pending-attempt write before calling the tool. It records okay/partial results, usage, evidence and effects, merges newly observed controls, and awaits the completed-attempt write before proceeding. Refusals, callback exceptions and failed surrounding awaits can leave the happy path earlier.

resolveRun merges status and timestamps, not every authoritative envelope field. Different run IDs reject. There is no additional control read between pending persistence and dispatch. A pause arriving during that await still permits the admitted callback; the next step can stop after the post-callback merge. A switch arriving after admission is checked at the next reached gate. Neither source structure nor these tests measures production five-second propagation or proves immediate abort of an in-flight tool.

Accounting and completion counterexamples#

  • With cap 15, estimate 10 and first actual usage 10, the next call is denied; a one-unit denial charge leaves 11 used. Two attempt records retain the okay and denied outcomes. This is the governed path, unlike the legacy example.
  • A final callback estimated at 10 can report 25 against cap 15. Consumption records the overshoot, but there is no subsequent gate to kill that invocation. The effect has already happened. Estimates are not atomic reservations.
  • Separate invocations over the same supplied original meter each start from it. The library's private meter does not establish shared cross-run accounting or persist updated budget state through an independent budget hook.
  • Denied and failed attempts use policy charges. Okay and partial attempts use reported adapter usage. Failed usage validation happens after a callback may have caused an effect. Validation checks existing entries, not the presence of every typed dimension: a JavaScript {} usage object passes that check, its call cost remains absent, and ledger normalization contributes zero. This is a local schema counterexample, not a claim that a caller controls the server policy or can exploit a deployed route.
  • Partial returns complete the matching stage and can be followed by another planned call. The library leaves run finalization to its caller. The actual HTTP route can mark the still-running run completed when every planned call returned, including partial. The new HTTP test retains the partial call under that completed envelope. Consumers must inspect requested deliverables and attempt outcomes rather than infer universal success from the run label.
  • Repeated planned tools receive increasing attempts and a prior-call reference in the route; a second callback still runs. These labels do not implement automatic retry, effect deduplication or an idempotency policy.

Pending is not an external-effect transaction#

The pinned probes accept initial and pending writes, execute a callback that increments a simulated effect, then reject completion persistence. The promise rejects while the last saved fixture remains pending with no saved call charge. Initial/pending write failures instead prevent the tool callback. A broker result-audit exception can also escape after the callback has acted.

The additional HTTP case uses the actual route, broker and lifecycle store with a controlled snapshot sink. That sink rejects completed telemetry. The route returns 500 after one simulated effect, and the store restores its last accepted pending snapshot. This is stronger evidence for the configured call path than a runner-only fixture, but still not a real database outage, process crash, provider transaction or deployed durability certification.

A thrown callback may itself have partially acted; recording an error cannot roll back an external system. Recovery needs actual effect evidence and the deployment's idempotency/reconciliation mechanisms before retrying uncertain work. The checkpoint, resume, fork and retry helpers reviewed separately do not close this window by themselves.

Telemetry and evidence limits#

The runner hashes canonically ordered raw arguments and recursively redacts a fixed set of normalized sensitive key names in stored arguments/results. Ordinary free text survives; error messages are truncated to 2,000 characters without secret scrubbing. The dispatch context and library executed results retain raw values. Key redaction and hashing are not a complete privacy or exposure policy. All test strings are conspicuously fake sentinels.

Usage, effects, emitted artifact IDs and evidence are supplied by adapters. Appending them to telemetry does not independently prove an external change, artifact existence or factual grounding. The ledger includes storage bytes as well as the eight previously explained dimensions. Actual customer exposure, retention and model/provider evidence still need their own integration review.

Evidence and remaining work#

Thirty-one Node probes execute nine complete, unmodified TypeScript modules from the pin. The broker and persistence hooks are explicit test doubles. The existing six package suites pass 70 tests, including actual portfolio-broker and governed-runner tests. The BFF route suites pass 25 tests: 22 existing and three new. They use Fastify injection and bounded fake tools, not live requests to a deployed service. The route/store source files and package match the pin; the BFF tests load the current checkout's transitive dependencies.

The final HTTP fixtures live in presentation tooling and reuse the BFF Vitest configuration. An exploratory affected typecheck passed BFF but failed the unchanged web screenshot helper; prompt-injection evals were not reached after fail-fast. The receipt retains the missing local dependency and other three web errors explicitly. No application implementation or type-error baseline is changed, and no full web/Eve release pass is claimed.

Seven relevant documentation units remain unassigned: budget overview, envelopes/meters, kill switches, the feature's runtime-seam description, the generated execution overview, field contract and claim boundary. Other source families, isolation, registry, modes, pipeline execution and broader Agentic teaching remain open. Counts of passing examples do not establish exhaustive source coverage.

After the active narration queue is stable:

  1. Revalidate all three drafts' baselines and apply eight replacements and three insertions deliberately. None of the eight replacements, including agentic-studio-failure, was current in the original 177-track baseline. Preserve all 177 without an exception; preserve the other 380 tracks from the completed 388-track queue. This corrects the original review's mistaken membership claim without rewriting its receipt. Recompute final counts.
  2. Refresh source excerpts, catalog, coverage inputs and source/workflow/repo inventory bindings. Complete substantive teaching review before assigning source units; do not treat these probes as assignments.
  3. Update phase-specific authoring proof to verify the applied content; retain the original draft/evidence history instead of silently accepting changed hashes. Regenerate the eight changed and three new tracks, HTML and PDFs.
  4. Extend and run affected standalone and embedded Playwright, including every new slide, table ends, compact playback and mobile reflow. Complete actual audio/decode/pause, PDF, visual and normal-speed listening review. The shared library's final gates and representative-reader acceptance remain required.

See the hash-bound receipt.