@novoagents/react 0.3.0-alpha.4 → 0.3.0-alpha.40

package/CHANGELOG.md

@@ -1,102 +1,143 @@
 # Changelog
 
-## Unreleased
-
-## 0.3.0-alpha.4 - 2026-07-29
-
-- Companion release for `novoagents` 0.5.0-alpha.4 (the browser SSE source
-  now applies the same cursor-established rule as the server reader for
-  id-less data frames, and `isFollowupQueueFullDetails` requires the caps the
-  server always sends). The hook source is unchanged; the exact SDK peer
-  moves.
-
-## 0.3.0-alpha.3 - 2026-07-29
-
-- Companion release for `novoagents` 0.5.0-alpha.3 (stream schema v5:
-  heartbeat covers long tool executions with `phase: 'executing_tool'` and
-  `waitId`, `followup_queue_full` becomes a first-class error code,
-  `tool-input-delta` is forwarded, and an id-less data frame after an
-  established cursor is a fatal transport error). The hook source is
-  unchanged; the exact SDK peer moves to the v5 contract.
-
-## 0.3.0-alpha.2 - 2026-07-28
-
-- Companion release for `novoagents` 0.5.0-alpha.2 (stream schema v4:
-  `data-novo-step-terminal` splits overflow reporting into `truncated` for
-  clipped text and `messagesOmitted` for dropped message arrays, and
-  `artifactRef` is removed). The hook source is unchanged; the exact SDK peer
-  moves to the v4 contract, and the packed tarball check now verifies the
-  installed wire contract against the workspace artifact instead of a pinned
-  revision literal.
-
-## 0.3.0-alpha.1 - 2026-07-28
-
-- Companion release for `novoagents` 0.5.0-alpha.1 (stream schema v3:
-  `platform_error` replaces the three engine-named terminal reasons, terminal
-  errors carry `retryable`, and the SDK ships the generated
-  `novoagents/wire-contract.json` compatibility manifest). The hook source is
-  unchanged; the exact SDK peer moves to the v3 contract, and the packed
-  tarball check verifies the installed wire contract's protocol revision.
-
-## 0.2.0-alpha.7 - 2026-07-16
-
-- Companion release for `novoagents` 0.4.0-alpha.7. The hook source remains
-  unchanged; its exact SDK peer moves with the App-only GitHub contract.
-- The workspace declares `novoagents` as a development dependency so a clean
-  CI install can compile the peer-backed `novoagents/browser` imports;
-  consumers still receive only the exact peer dependency, never a nested SDK.
-
-## 0.2.0-alpha.6 - 2026-07-16
-
-- Companion release for `novoagents` 0.4.0-alpha.6. The hook source is
-  unchanged; publishing the React package alongside the SDK keeps its exact
-  `novoagents` peer on the current canonical browser-controller contract.
-
-## 0.2.0-alpha.5 - 2026-07-16
-
-- Moves the type-only `novoagents` relationship from a runtime dependency to
-  an exact peer dependency on 0.4.0-alpha.5. The hooks still require the
-  matching canonical browser-controller contract, while package managers now
-  install one app-owned SDK copy instead of retaining an older nested copy or
-  requiring a consumer override.
-
-## 0.2.0-alpha.4 - 2026-07-16
-
-- Superseded by 0.2.0-alpha.5. The alpha.4 registry artifact was published from
-  the workspace source with npm, which retained the internal `workspace:*`
-  peer specifier instead of pnpm's exact-version rewrite. It is not assigned a
-  dist-tag and should not be installed.
-
-## 0.2.0-alpha.3 - 2026-07-15
-
-- `useNovoRun` exposes the latest provider-neutral thinking/activity snapshot
-  on `state.progress`, or `null` after answer, pause, restart, or terminal
-  boundaries. When safe readable reasoning is available, the snapshot may be a
-  short reasoning-derived summary; it never contains raw reasoning. The hook
-  inherits the canonical browser reducer behavior from `novoagents`.
-
-## 0.2.0-alpha.2 - 2026-07-15
-
-- Updates the packed `novoagents` dependency to 0.4.0-alpha.2, so React run
-  hooks consume targeted `data-novo-model-step-restart` retractions through the
-  canonical browser controller.
-
-## 0.2.0-alpha.1 - 2026-07-14
-
-- `useNovoRun` normalizes `enabled` and `runKey` before its dependency arrays,
-  so identity toggles (`enabled: undefined <-> true`, `runKey: undefined <->
-  null`) no longer dispose and recreate a live controller.
-- Picks up `novoagents` 0.4.0-alpha.1 controller fixes: fatal (non-retried)
-  initial-connect errors, per-drop `transportError` publication, a final
-  `disposed` snapshot published before listeners detach, and interaction-race
-  hardening.
-
-## 0.2.0-alpha.0 - 2026-07-14
-
-- Replaced the alpha store/transport hooks with effect-owned bindings over the
-  canonical `NovoRunController`.
-- Added `useNovoRunSelector` and controller-bound `useNovoInteractions`.
-- Fixed run-key/unmount leaks with stop + disposal and generation-fenced core
-  consumption.
-- Added client entry directives, `sideEffects: false`, React 18/19 peer range,
-  SSR snapshots, and Strict Mode lifecycle coverage.
+## 0.3.0-alpha.40 - 2026-09-06
+
+Companion release for `novoagents` 0.5.0-alpha.36. The React runtime is
+unchanged; the exact peer carries the corrected public type and error exports.
+Packed-consumer verification now runs from a staged copy and exercises the
+workspace peer resolver independently.
+
+## 0.3.0-alpha.39 - 2026-09-06
+
+Companion release for `novoagents` 0.5.0-alpha.35. The React runtime is
+unchanged; the exact peer carries the combined private-input and managed-web
+usage contracts.
+
+## 0.3.0-alpha.38 - 2026-09-06
+
+Companion release for `novoagents` 0.5.0-alpha.34. The React runtime is
+unchanged; the exact peer carries protected browser input and context revision
+contracts.
+
+## 0.3.0-alpha.37 - 2026-09-03
+
+Companion release for `novoagents` 0.5.0-alpha.33. The React runtime is
+unchanged; the exact peer carries the new agent configuration warnings type.
+
+## 0.3.0-alpha.36 - 2026-09-01
+
+Companion release for `novoagents` 0.5.0-alpha.32.
+
+- Controller ownership now rides the external-store snapshot (run key and
+  controller travel with the subscribed state), so an abandoned concurrent
+  render can no longer strand ownership in a render-written ref. Selector
+  readers isolate speculative renders while preserving equal object identity
+  across inline selector changes: the committed selection lives in a
+  `useState`-held cell that is still read during render, by design, mirroring
+  React's own `useSyncExternalStoreWithSelector` shim. Behavior is unchanged
+  across React 18 and 19, and the package now passes the canonical hooks lint
+  rules.
+
+## 0.3.0-alpha.35 - 2026-08-26
+
+- Companion release for `novoagents` 0.5.0-alpha.31. GitHub connection and
+  agent repository grants now carry exact immutable repository identities
+  end to end; an explicit empty agent selection grants no repositories.
+
+## 0.3.0-alpha.34 - 2026-08-26
+
+- Companion release for `novoagents` 0.5.0-alpha.30. The React runtime is
+  unchanged; the exact peer carries the immutable repository id on grantable
+  GitHub repositories.
+
+## 0.3.0-alpha.33 - 2026-08-26
+
+- Companion release for `novoagents` 0.5.0-alpha.29. The React runtime is
+  unchanged; the exact peer carries the discriminated usage-lineage and
+  debit-group identity contract.
+
+## 0.3.0-alpha.32 - 2026-08-25
+
+- Companion release for `novoagents` 0.5.0-alpha.28. It carries the exact peer
+  for scheduled wake-ups, stream protocol 18, and customer wake-up
+  cancellation. The React runtime is unchanged.
+
+## 0.3.0-alpha.31 - 2026-08-21
+
+- Companion release for `novoagents` 0.5.0-alpha.27. The controller can follow
+  ordered thread segments with an injected cursor codec; React state exposes
+  the segment ledger while preserving the transcript across engine-owned runs.
+
+## 0.3.0-alpha.27 - 2026-08-20
+
+- Companion release for `novoagents` 0.5.0-alpha.25. The React runtime is
+  unchanged; the exact peer carries autonomous run starts and all-attempt Stop
+  semantics for background subagents.
+
+## 0.3.0-alpha.26 - 2026-08-20
+
+- Companion release for `novoagents` 0.5.0-alpha.24. It carries the exact peer
+  for wire protocol 16, the shared GitHub installation contract, and the
+  `ask_question` lifecycle whose first public terminal is the user's real
+  resolution.
+
+## 0.3.0-alpha.25 - 2026-08-20
+
+- Companion release for `novoagents` 0.5.0-alpha.23. It carries the exact peer
+  required for stream schema 14, including background worker task metadata and
+  `data-novo-worker-report` message parts.
+
+## 0.3.0-alpha.24 - 2026-08-18
+
+- Companion release for `novoagents` 0.5.0-alpha.22. The hook runtime is
+  unchanged; the package carries an exact peer on the SDK version whose browser
+  run controller it binds. Consumers rendering `run.messages` now see one
+  `data-novo-heartbeat` part per tool wait (see the core changelog).
+
+## 0.3.0-alpha.23 - 2026-08-17
+
+- Companion release for `novoagents` 0.5.0-alpha.21. The hook runtime is
+  unchanged; the package carries an exact peer on the SDK version whose browser
+  run controller it binds.
+
+## 0.3.0-alpha.22 - 2026-08-17
+
+- Companion release for `novoagents` 0.5.0-alpha.20. The hook runtime is
+  unchanged; the package carries an exact peer on the SDK version whose browser
+  run controller it binds.
+
+## 0.3.0-alpha.21 - 2026-08-17
+
+- Companion release for `novoagents` 0.5.0-alpha.19. The hook runtime is
+  unchanged; the package carries an exact peer on the SDK version whose browser
+  run controller it binds.
+
+## 0.3.0-alpha.20 - 2026-08-16
+
+- Companion release for `novoagents` 0.5.0-alpha.18. The hook runtime is
+  unchanged; the package carries an exact peer on the SDK version whose browser
+  run controller it binds.
+- `0.3.0-alpha.19` was published through npm instead of pnpm and therefore
+  preserved the workspace protocol in its peer metadata. It was never tagged
+  `latest`; use this build instead.
+
+## 0.3.0-alpha.18 - 2026-08-12
+
+- Companion release for `novoagents` 0.5.0-alpha.17. The hook runtime is
+  unchanged; the package carries an exact peer on the SDK version whose browser
+  run controller it binds.
+
+## 0.3.0-alpha.17 - 2026-08-12
+
+- Companion release for `novoagents` 0.5.0-alpha.16. The hook runtime is
+  unchanged; the package carries an exact peer on the SDK version whose browser
+  run controller it binds.
+
+## 0.3.0-alpha.16 - 2026-08-12
+
+- Companion release for `novoagents` 0.5.0-alpha.15. The hook runtime is
+  unchanged; the package carries an exact peer on the SDK version whose browser
+  run controller it binds.
+
+Earlier prerelease builds are unsupported. Their immutable package artifacts
+and Git history retain their release records.

package/README.md

@@ -48,26 +48,3 @@ If your host persists interaction requests independently of the stream,
 configure `interactionDiscovery: { list, intervalMs? }` on the controller.
 Discovery is generation-fenced, runs while the SSE connection is idle, and
 reconciles DB-only requests into the same canonical pending queue.
-
-## Migrating from 0.1.0-alpha.0
-
-- `createNovoRunStore` → `createNovoRunController` from `novoagents/browser`.
-- `BrowserRunTransport` → `NovoRunEventSource`; use
-  `createNovoHttpRunSource` for fetch/SSE routes.
-- `useNovoRun({ transport })` →
-  `useNovoRun({ createController, runKey })`.
-- `useNovoInteractions({ endpoint, run })` → configure the controller's
-  interaction transport, then call `useNovoInteractions(run.controller)`.
-- `resolveNovoInteractions` → `createHttpInteractionResolveTransport`.
-
-There are no compatibility aliases for the alpha API.
-
-## Publishing
-
-After publishing `novoagents`, publish with
-`pnpm publish --access public --tag alpha`: pnpm rewrites the `workspace:*`
-peer dependency on `novoagents` to the exact packed version. Publish the two
-alpha packages in lockstep so both `alpha` tags always form one compatible
-browser-controller installation. Do not publish the workspace source with
-`npm publish`; npm does not perform pnpm's workspace-protocol rewrite. Verify
-the registry peer metadata before moving `latest`.

package/dist/useNovoRun.js

@@ -1,11 +1,12 @@
 'use client';
-import { useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore, } from 'react';
 export const NOVO_IDLE_RUN_STATE = Object.freeze({
     messages: Object.freeze([]),
     status: 'queued',
     progress: null,
     pendingInteractions: Object.freeze([]),
     tasks: Object.freeze([]),
+    segments: Object.freeze([]),
     steps: Object.freeze([]),
     browserSessions: Object.freeze([]),
     warnings: Object.freeze([]),
@@ -21,7 +22,17 @@ function createControllerSlot() {
     const listeners = new Set();
     let controller;
     let unsubscribe;
+    let snapshot = {
+        controller: undefined,
+        runKey: UNOWNED_RUN_KEY,
+        state: NOVO_IDLE_RUN_STATE,
+    };
     const publish = () => {
+        snapshot = {
+            ...snapshot,
+            state: controller?.getSnapshot() ??
+                NOVO_IDLE_RUN_STATE,
+        };
         for (const listener of listeners)
             listener();
     };
@@ -30,15 +41,20 @@ function createControllerSlot() {
             listeners.add(listener);
             return () => listeners.delete(listener);
         },
-        getSnapshot: () => controller?.getSnapshot() ??
-            NOVO_IDLE_RUN_STATE,
+        getSnapshot: () => snapshot,
         getController: () => controller,
-        setController(next) {
-            if (controller === next)
+        setController(next, runKey = UNOWNED_RUN_KEY) {
+            if (controller === next && snapshot.runKey === runKey)
                 return;
             unsubscribe?.();
             controller = next;
             unsubscribe = next?.subscribe(publish);
+            snapshot = {
+                controller: next,
+                runKey,
+                state: next?.getSnapshot() ??
+                    NOVO_IDLE_RUN_STATE,
+            };
             publish();
         },
     };
@@ -50,11 +66,10 @@ function createControllerSlot() {
  */
 export function useNovoRun(options) {
     const factoryRef = useRef(options.createController);
-    factoryRef.current = options.createController;
-    const slotRef = useRef(undefined);
-    slotRef.current ??= createControllerSlot();
-    const slot = slotRef.current;
-    const ownedRunKeyRef = useRef(UNOWNED_RUN_KEY);
+    useEffect(() => {
+        factoryRef.current = options.createController;
+    }, [options.createController]);
+    const [slot] = useState(() => createControllerSlot());
     // Normalize before any dependency array: `enabled: undefined <-> true` and
     // `runKey: undefined <-> null` toggles are identity changes and must not
     // dispose and recreate a live controller.
@@ -66,14 +81,10 @@ export function useNovoRun(options) {
             return;
         }
         const controller = factoryRef.current();
-        ownedRunKeyRef.current = runKey;
-        slot.setController(controller);
+        slot.setController(controller, runKey);
         return () => {
             controller.stop();
             controller.dispose();
-            if (ownedRunKeyRef.current === runKey) {
-                ownedRunKeyRef.current = UNOWNED_RUN_KEY;
-            }
             if (slot.getController() === controller)
                 slot.setController(undefined);
         };
@@ -81,16 +92,16 @@ export function useNovoRun(options) {
     useEffect(() => {
         if (enabled &&
             options.autoStart !== false &&
-            ownedRunKeyRef.current === runKey) {
+            slot.getSnapshot().runKey === runKey) {
             void slot.getController()?.start();
         }
     }, [options.autoStart, enabled, runKey, slot]);
-    const observedState = useSyncExternalStore(slot.subscribe, slot.getSnapshot, () => NOVO_IDLE_RUN_STATE);
-    const ownsRenderedKey = enabled && ownedRunKeyRef.current === runKey;
+    const observed = useSyncExternalStore(slot.subscribe, slot.getSnapshot, () => IDLE_SLOT_SNAPSHOT);
+    const ownsRenderedKey = enabled && observed.runKey === runKey;
     const state = ownsRenderedKey
-        ? observedState
+        ? observed.state
         : NOVO_IDLE_RUN_STATE;
-    const controller = ownsRenderedKey ? slot.getController() : undefined;
+    const controller = ownsRenderedKey ? observed.controller : undefined;
     return useMemo(() => ({
         ...state,
         controller,
@@ -104,3 +115,8 @@ export function useNovoRun(options) {
     }), [controller, state]);
 }
 const UNOWNED_RUN_KEY = Symbol('unowned Novo run key');
+const IDLE_SLOT_SNAPSHOT = Object.freeze({
+    controller: undefined,
+    runKey: UNOWNED_RUN_KEY,
+    state: NOVO_IDLE_RUN_STATE,
+});

package/dist/useNovoRunSelector.js

@@ -1,47 +1,67 @@
 'use client';
-import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore, } from 'react';
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore, } from 'react';
 import { NOVO_IDLE_RUN_STATE } from './useNovoRun.js';
 /** Concurrent-safe selector binding with selector/equality identity support. */
 export function useNovoRunSelector(controller, selector, isEqual = Object.is) {
-    const committedSelection = useRef({
-        hasValue: false,
-    });
-    const idleState = NOVO_IDLE_RUN_STATE;
-    const [getSnapshot, getServerSnapshot] = useMemo(() => {
-        let hasMemo = false;
-        let memoizedState;
-        let memoizedSelection;
-        const select = (state) => {
-            if (!hasMemo) {
-                hasMemo = true;
-                memoizedState = state;
-                const nextSelection = selector(state);
-                const committed = committedSelection.current;
-                memoizedSelection =
-                    committed.hasValue && isEqual(committed.value, nextSelection)
-                        ? committed.value
-                        : nextSelection;
-                return memoizedSelection;
-            }
-            if (Object.is(memoizedState, state))
-                return memoizedSelection;
-            const nextSelection = selector(state);
-            memoizedState = state;
-            if (isEqual(memoizedSelection, nextSelection))
-                return memoizedSelection;
-            memoizedSelection = nextSelection;
-            return memoizedSelection;
-        };
-        const serverSelection = select(idleState);
-        return [
-            () => select(controller?.getSnapshot() ?? idleState),
-            () => serverSelection,
-        ];
-    }, [controller, isEqual, selector]);
+    const [committedSelection] = useState(() => createCommittedSelection());
+    const [getSnapshot, getServerSnapshot] = useMemo(() => createSelectionReader(controller, selector, isEqual, NOVO_IDLE_RUN_STATE, committedSelection), [committedSelection, controller, isEqual, selector]);
     const subscribe = useCallback((listener) => controller?.subscribe(listener) ?? (() => { }), [controller]);
     const selection = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
     useEffect(() => {
-        committedSelection.current = { hasValue: true, value: selection };
-    }, [selection]);
+        committedSelection.write(selection);
+    }, [committedSelection, selection]);
     return selection;
 }
+// Deliberately a mutable cell read during render (via getSnapshot) and
+// written from the commit effect, mirroring React's own
+// useSyncExternalStoreWithSelector shim. The hooks lint layer cannot see a
+// closure-held cell; do not "fix" this back into a ref, which it would flag.
+function createCommittedSelection() {
+    let committed = {
+        hasValue: false,
+    };
+    return {
+        read: () => committed,
+        write: (value) => {
+            committed = { hasValue: true, value };
+        },
+    };
+}
+function createSelectionReader(controller, selector, isEqual, idleState, committedSelection) {
+    let hasValue = false;
+    let value;
+    let memoizedState;
+    let hasServerValue = false;
+    let serverValue;
+    const select = (state) => {
+        if (Object.is(memoizedState, state) && hasValue)
+            return value;
+        const next = selector(state);
+        memoizedState = state;
+        if (!hasValue) {
+            hasValue = true;
+            const committed = committedSelection.read();
+            value =
+                committed.hasValue && isEqual(committed.value, next)
+                    ? committed.value
+                    : next;
+        }
+        else if (!isEqual(value, next)) {
+            value = next;
+        }
+        return value;
+    };
+    const selectServer = () => {
+        if (hasServerValue)
+            return serverValue;
+        const next = selector(idleState);
+        const committed = committedSelection.read();
+        serverValue =
+            committed.hasValue && isEqual(committed.value, next)
+                ? committed.value
+                : next;
+        hasServerValue = true;
+        return serverValue;
+    };
+    return [() => select(controller?.getSnapshot() ?? idleState), selectServer];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novoagents/react",
-  "version": "0.3.0-alpha.4",
+  "version": "0.3.0-alpha.40",
   "description": "Browser-safe React hooks for Novo Agents streams and interactions.",
   "license": "UNLICENSED",
   "type": "module",
@@ -23,19 +23,19 @@
     "access": "public"
   },
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "novoagents": "0.5.0-alpha.4"
+    "novoagents": "0.5.0-alpha.36",
+    "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@types/react": "19.2.17",
-    "@types/react-dom": "19.2.3",
-    "happy-dom": "20.11.1",
-    "react": "19.2.7",
-    "react-dom": "19.2.7",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.7",
+    "happy-dom": "20.14.0",
+    "novoagents": "0.5.0-alpha.36",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
     "typescript": "6.0.3",
-    "vite": "8.1.5",
-    "vitest": "5.0.0-beta.6",
-    "novoagents": "0.5.0-alpha.4"
+    "vite": "8.2.2",
+    "vitest": "5.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/check-dist.mjs",