@sema-agent/core 5.33.0 → 5.34.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 5.34.0 — 2026-08-15
+
+No BREAKING changes. Two behavior-surface additions (both additive seats), one packaging addition,
+new test/gate infrastructure; zero resolution-result changes.
+
+### Added
+
+- `RunInternals.onStatusEvent` (#253): the run's own top-level `status` TaskEvent stream (brain
+  liveness — rate-limit/retry/reconnect/circuit-open) offered to the internals holder beside the
+  queue. A composition entry (verify/cascade/`runDeveloperTask`) drains its inner legs' queues
+  itself, so an inner leg's retry disclosure previously died inside the gate. The sink receives the
+  SAME (frozen) frame object the stream carries, gated on queue acceptance (a late detached emission
+  cannot reach the sink after the stream refused it), contained per the host-callback isolation
+  primitive: a throwing OR async-rejecting sink never faults the leg, first failure per site is
+  disclosed via `console.warn`, later ones are counted.
+- Status frames on the task stream are now frozen (`Object.freeze`, flat object): a mutating host
+  callback can no longer rewrite the queued wire event. `PushQueue.push` returns whether the value
+  was accepted (compatible signature widening, `void` callers unaffected).
+- The export-surface snapshot (`test/export-surface.snapshot.json`) ships in the npm package —
+  downstream consumption gates can anchor the in-package file instead of a vendored copy.
+- `examples/` (source tree, excluded from the build): a runnable end-to-end governed-agent arc
+  (`src/examples/governed-agent/`) — org rules, narrowing, durable approval park, cross-worker
+  resume with non-widening enforcement — 29 self-checking steps, offline and key-less, with a
+  smoke test on the real loading path. Not part of the published artifact.
+- Request-prefix/caching test infrastructure: a prefix-stability baseline (adjacent requests as
+  append-extensions, three known breaks pinned as current-state), a live provider cache-hit leg
+  (same-session second turn must be served from the prefix cache; measured ≈97.5% on deepseek), and
+  a byte-equal request-reconstruction pin across durable resume and session fork.
+- ship-post-lint registry legs: cited F-nnn/A-nnn ledger files must exist and carry the shipping
+  version; zero citations require an explicit `FEATS: none` / `AUDITS: none`.
+
+### Fixed
+
+- 5.34 pre-release rescan (two confirmed): an `async` sink at any run-internals seat now has its
+  rejection contained through the same notifier/site as a synchronous throw
+  (`observeThenableRejection`, one source for status + both activity sites — previously a rejected
+  async `onActivity` escaped as an unhandled rejection and could terminate the process); and
+  ship-post-lint's published-output delta and `--tree-fingerprint` now fold packaged non-dist files
+  (`pkg:` prefix), so a change to the shipped snapshot can no longer report as byte-identical output.
+
+- #248: the run-internals activity sink (`onActivity`) joins the host-callback isolation primitive —
+  a throwing sink previously failed the leg (misclassified `provider.error`) and, inside a cascade,
+  escalated a rung whose non-idempotent write had already run (measured: the write ran twice). Now
+  contained: swallow + first-failure disclosure + per-site counts.
+
+### Docs
+
+- The blackbox gate leaves the release tiers (its leg is owned by the independent black-box
+  acceptance institution; the script remains a dev-time self-check).
+- Six live standing-leg env-gated skips join the skip baseline (historical omission; union merge,
+  zero removals).
+
 ## 5.33.0 — 2026-08-14
 
 ### BREAKING (operational)

package/dist/core/push-queue.d.ts

@@ -3,7 +3,10 @@ export declare class PushQueue<T> implements AsyncIterable<T> {
     private buffer;
     private waiters;
     private closed;
-    push(value: T): void;
+    /** Returns whether the value was ACCEPTED (`false` after close — the push is a silent no-op then).
+     *  Callers that mirror a pushed value to a second reader gate on this so both sides stay in parity
+     *  (#253: a status frame must not reach a side sink the stream itself already refused). */
+    push(value: T): boolean;
     close(): void;
     [Symbol.asyncIterator](): AsyncIterator<T>;
 }

package/dist/core/push-queue.js

@@ -4,7 +4,7 @@ export class PushQueue {
     closed = false;
     push(value) {
         if (this.closed) {
-            return;
+            return false;
         }
         const waiter = this.waiters.shift();
         if (waiter) {
@@ -13,6 +13,7 @@ export class PushQueue {
         else {
             this.buffer.push(value);
         }
+        return true;
     }
     close() {
         this.closed = true;

package/dist/core/runner/prepare-task.d.ts

@@ -1285,6 +1285,19 @@ export interface RunInternals {
      * MODEL context (this is purely a render channel). Absent unless the deployment opted in.
      */
     onForwardEvent?: (event: TaskEvent) => void;
+    /**
+     * #253 — the run's OWN top-level `status` TaskEvent stream (brain liveness: rate-limit/retry/
+     * reconnect/circuit-open), offered to the internals holder beside the queue. The queue alone was
+     * enough for a direct `runTask` caller (the TaskStream carries these frames), but a COMPOSITION
+     * entry (verify/cascade) drains its inner legs' queues itself — without this seat, an inner leg's
+     * retry disclosure died inside the gate and the wire showed a silent stall. Fed the SAME frame
+     * object the queue receives, at the same moment; contained by the run's safe notifier (#248 form:
+     * a throwing sink is swallowed, first failure per site disclosed, never faults the leg). Subagent
+     * frames still ride {@link onForwardEvent} — this seat is ONLY the run's own status type.
+     */
+    onStatusEvent?: (event: Extract<TaskEvent, {
+        type: "status";
+    }>) => void;
     /**
      * design/115 P2 core slice — trusted run-local system-injection sink. `Runner.runLocked` wires this to the
      * live TaskStream queue plus the current harness follow-up lane; it is not a public TaskSpec field.

package/dist/core/runner/runtask.js

@@ -1,5 +1,5 @@
 import { persistedReadDenyEntryProblem } from "../../tools/fs/read-deny.js";
-import { createSafeNotifier } from "../safe-notify.js";
+import { createSafeNotifier, observeThenableRejection } from "../safe-notify.js";
 import { AgentHarness, DEFAULT_COMPACTION_SETTINGS, uuidv7 } from "../../internal/harness.js";
 import { snapshotActorAssertion } from "../../internal/llm.js";
 import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, F012_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
@@ -1154,7 +1154,7 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
                 rs.counters.groundingSignalPostR9 = true;
         }
         const activityArg = primaryActivityArg(event.args);
-        internalsNotifier.notify(() => internals?.onActivity?.({ phase: "start", toolCallId: event.toolCallId, toolName: event.toolName, at: startAt, ...(activityArg !== undefined ? { arg: activityArg } : {}) }), "runtask.onActivity.start");
+        internalsNotifier.notify(() => observeThenableRejection(internals?.onActivity?.({ phase: "start", toolCallId: event.toolCallId, toolName: event.toolName, at: startAt, ...(activityArg !== undefined ? { arg: activityArg } : {}) }), internalsNotifier, "runtask.onActivity.start"), "runtask.onActivity.start");
         pushContent({
             type: "tool_start",
             toolCallId: event.toolCallId,
@@ -1203,7 +1203,7 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
             ok: !event.isError,
             ts: toolNow,
         }));
-        internalsNotifier.notify(() => internals?.onActivity?.({ phase: "end", toolCallId: event.toolCallId, toolName: event.toolName, isError: event.isError, at: toolNow }), "runtask.onActivity.end");
+        internalsNotifier.notify(() => observeThenableRejection(internals?.onActivity?.({ phase: "end", toolCallId: event.toolCallId, toolName: event.toolName, isError: event.isError, at: toolNow }), internalsNotifier, "runtask.onActivity.end"), "runtask.onActivity.end");
         if (prepared.lspDiagnostics && !event.isError) {
             const name = event.toolName;
             if (name === "Edit" || name === "Write" || name === "NotebookEdit") {
@@ -2329,8 +2329,11 @@ export class Runner {
             queue.push({ type: "message_committed", entryId, role, ...(toolCallId !== undefined ? { toolCallId } : {}), ...ident() });
         };
         const subagentName = parentToolCallId !== undefined && internals?.agentName !== undefined ? inlineUntrusted(internals.agentName.slice(0, 320), 80) : undefined;
+        const statusSinkNotifier = createSafeNotifier({
+            onError: (f) => console.warn(`[sema-core] ${f.site}: run-internals status sink threw (contained; further failures counted, not re-disclosed): ${f.error.message}`),
+        });
         const statusEmit = (s) => {
-            queue.push({
+            const frame = {
                 type: "status",
                 phase: s.phase,
                 ...(s.detail !== undefined ? { detail: s.detail } : {}),
@@ -2340,7 +2343,12 @@ export class Runner {
                 ...(s.maxRetries !== undefined ? { maxRetries: s.maxRetries } : {}),
                 ...(s.errClass !== undefined ? { errClass: s.errClass } : {}),
                 ...ident(),
-            });
+            };
+            Object.freeze(frame);
+            const accepted = queue.push(frame);
+            if (accepted && internals?.onStatusEvent !== undefined) {
+                statusSinkNotifier.notify(() => observeThenableRejection(internals.onStatusEvent?.(frame), statusSinkNotifier, "runtask.onStatusEvent"), "runtask.onStatusEvent");
+            }
         };
         const telemetryEmit = (t) => {
             emitTrace(rs.telemetry.tracer, () => t.kind === "failover"

package/dist/core/safe-notify.d.ts

@@ -79,3 +79,12 @@ export interface SafeNotifier {
  * notifier whose callbacks never throw costs one object and nothing per call beyond the `try`.
  */
 export declare function createSafeNotifier(opts?: SafeNotifierOptions): SafeNotifier;
+/**
+ * Observe a `=> void` host callback's RETURN value for the async dialect: TypeScript accepts an
+ * `async` function at a void seat, and a rejected one would escape {@link SafeNotifier.notify}
+ * (which deliberately ignores return values — see the scope note above) as an unhandled rejection.
+ * Call this with the callback's return value INSIDE the notify thunk: a thenable's rejection is
+ * routed back through the same notifier/site, so async and sync failures share one count and one
+ * bounded disclosure, and neither can fault the engine's control flow.
+ */
+export declare function observeThenableRejection(r: unknown, notifier: SafeNotifier, site: string): void;

package/dist/core/safe-notify.js

@@ -57,3 +57,12 @@ export function createSafeNotifier(opts) {
         },
     };
 }
+export function observeThenableRejection(r, notifier, site) {
+    if (typeof r?.then === "function") {
+        r.then(undefined, (err) => {
+            notifier.notify(() => {
+                throw err instanceof Error ? err : new Error(String(err));
+            }, site);
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.33.0",
+  "version": "5.34.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -36,6 +36,7 @@
   },
   "files": [
     "dist",
+    "test/export-surface.snapshot.json",
     "README.md",
     "NOTICE.md",
     "CHANGELOG.md",