@genesislcap/ai-assistant 15.23.3 → 15.24.0

package/dist/esm/main/meta-snapshot.js

@@ -0,0 +1,108 @@
+import { configDigest } from '../state/persistence/diagnostics';
+import { stripAgentHandlers } from '../utils/strip-agent-handlers';
+import { expandToolTree } from '../utils/tool-fold';
+/**
+ * The single `meta-snapshot` entry for right now — the export-time `meta` block
+ * (agent summary, active prompt/state, context + cost) plus the `dedupSignature`
+ * the forward-capture delta keys on.
+ *
+ * Built separately from the timeline entries because the download path needs a
+ * FRESH one on its own: the persisted stream only re-appends this block when the
+ * near-static config changes, so the newest stored snapshot's volatile half — the
+ * `context` figures especially — is typically frozen at the session's first flush.
+ *
+ * @internal
+ */
+export function buildMetaSnapshot(input) {
+    var _a, _b, _c, _d, _e, _f;
+    const timestamp = new Date().toISOString().replace(/:/g, '-');
+    let activeDebugSnapshot;
+    try {
+        activeDebugSnapshot = (_b = (_a = input.liveActiveAgent) === null || _a === void 0 ? void 0 : _a.getDebugSnapshot) === null || _b === void 0 ? void 0 : _b.call(_a);
+    }
+    catch (e) {
+        activeDebugSnapshot = `<getDebugSnapshot threw: ${e instanceof Error ? e.message : String(e)}>`;
+    }
+    const contextUsagePercent = input.contextTokens != null && input.contextLimit != null && input.contextLimit > 0
+        ? Math.round((input.contextTokens / input.contextLimit) * 100)
+        : undefined;
+    // The export-time `meta` block, carried on a `meta-snapshot` entry so it lives
+    // in the same forward stream (the latest one wins on reassembly, and the
+    // accumulated history exposes config/state evolution across the lifetime).
+    const metaSnapshot = {
+        kind: 'meta-snapshot',
+        timestamp: new Date().toISOString(),
+        meta: {
+            timestamp,
+            host: input.host,
+            // stripAgentHandlers drops every function-valued field (handlers, lifecycle
+            // hooks, onUnresolvedTool, function-form resolvers) AND object handler bags
+            // like an object-form `toolHandlers`, and recurses subAgents — no manual
+            // exclusion list to keep in sync. We only override toolDefinitions
+            // afterwards to expand the fold tree for the log.
+            agentSummary: (_c = input.agents) === null || _c === void 0 ? void 0 : _c.map((a) => {
+                var _a;
+                return (Object.assign(Object.assign({}, stripAgentHandlers(a)), { toolDefinitions: Array.isArray(a.toolDefinitions)
+                        ? typeof a.toolHandlers === 'function'
+                            ? // Static defs + dynamic handlers — can't walk fold tree
+                                // because the handler map isn't materialized at log time.
+                                a.toolDefinitions
+                            : expandToolTree(a.toolDefinitions, (_a = a.toolHandlers) !== null && _a !== void 0 ? _a : {})
+                        : typeof a.toolDefinitions === 'function'
+                            ? '<dynamic — resolved per turn>'
+                            : [] }));
+            }),
+            activeSystemPrompt: typeof ((_d = input.activeAgent) === null || _d === void 0 ? void 0 : _d.systemPrompt) === 'function'
+                ? '<dynamic — resolved per turn>'
+                : (_e = input.activeAgent) === null || _e === void 0 ? void 0 : _e.systemPrompt,
+            activePrimerHistory: (_f = input.activeAgent) === null || _f === void 0 ? void 0 : _f.primerHistory,
+            activeFoldStack: input.activeFoldStack,
+            // Context window + cost snapshot. `sessionCostUsd` is the chat-scoped
+            // total (per-message `cost` summed); the transport's lifetime cost is
+            // not included here because it pools other call sites (suggestions,
+            // criteria interpretation, etc.) and would be misleading next to the
+            // chat-only token counts.
+            context: {
+                model: input.activeModel,
+                contextTokens: input.contextTokens,
+                contextLimit: input.contextLimit,
+                contextUsagePercent,
+                sessionCostUsd: input.sessionCostUsd,
+                sessionTokensConsumed: input.sessionTokensConsumed,
+                // The per-bucket split alongside the total. Without it a log shows a large
+                // token count next to a small cost with no way to tell why — the answer is
+                // almost always that most of the prompt was a cache hit.
+                sessionUsage: input.sessionUsage,
+            },
+            // Snapshot captured fresh at log-export time — reflects state NOW, which
+            // may have transitioned since the last LLM call.
+            activeDebugSnapshot,
+            debug: input.debugState,
+        },
+    };
+    // Stable dedup signature for the forward-capture stream (GENC-1351 §5.8 / #12):
+    // the near-static config only. Excludes the volatile fields — the export
+    // `timestamp`, the per-turn `context` (tokens/cost), and the live
+    // `activeDebugSnapshot` — whose churn otherwise made the whole-`meta` dedup key
+    // differ on every throttled flush, so a bulky snapshot was re-appended each time
+    // instead of "only when the block actually changed". The volatile evolution is
+    // already in the timeline (turn snapshots + `context.updated` events), so the
+    // persister only needs a fresh meta-snapshot when the config/prompt changes.
+    // Consequence for the download path: the newest STORED snapshot's context/cost
+    // figures are stale, which is why `buildDownloadLog` appends a fresh one.
+    //
+    // DIGESTED rather than stored verbatim (GENC-1566). The projection is right; keeping a
+    // full copy of it was not. It is only ever compared for equality, and `agentSummary`
+    // alone was 159 KB in the session that prompted this — so each snapshot carried the
+    // block plus a stringified copy of most of it, and both went up the wire on every
+    // flush. See {@link configDigest} for the hash and why a collision is harmless here.
+    const m = metaSnapshot.meta;
+    metaSnapshot.dedupSignature = configDigest(JSON.stringify({
+        host: m.host,
+        agentSummary: m.agentSummary,
+        activeSystemPrompt: m.activeSystemPrompt,
+        activePrimerHistory: m.activePrimerHistory,
+        activeFoldStack: m.activeFoldStack,
+    }));
+    return metaSnapshot;
+}

package/dist/esm/state/persistence/session-persister.js

@@ -1,5 +1,5 @@
 import { __awaiter } from "tslib";
-import { OrchestratingDriver } from '../../components/orchestrating-driver/orchestrating-driver';
+import { asOrchestrator } from '../../components/orchestrating-driver/orchestrating-driver';
 import { flattenSubAgentMessages } from '../../utils/flatten-sub-agent-messages';
 import { logger } from '../../utils/logger';
 import { isSessionNoticeMarker, SESSION_RESTORE_FAILED_LABEL, SESSION_RESTORED_LABEL, } from '../../utils/message-partition';
@@ -639,9 +639,10 @@ export class SessionPersister {
                 // (flow-owned but unpinned) — `resolvePinnedAgent` reads `flowOwnerAgentName ??
                 // pinnedAgentName`, so restoring both resumes the flow without re-classifying, and the
                 // driver's routing agrees with the restored (picker-locked) store state.
-                if (driver instanceof OrchestratingDriver) {
-                    driver.setPinnedAgent((_d = snapshot.pinnedAgentName) !== null && _d !== void 0 ? _d : null);
-                    driver.setFlowOwner((_e = snapshot.flowOwnerAgentName) !== null && _e !== void 0 ? _e : null);
+                const orchestrator = asOrchestrator(driver);
+                if (orchestrator) {
+                    orchestrator.setPinnedAgent((_d = snapshot.pinnedAgentName) !== null && _d !== void 0 ? _d : null);
+                    orchestrator.setFlowOwner((_e = snapshot.flowOwnerAgentName) !== null && _e !== void 0 ? _e : null);
                 }
                 logger.debug('Session restored', { key, messages: messages.length });
             }

package/docs/migration-GENC-1580.md

@@ -0,0 +1,209 @@
+# Migration Guide — GENC-1580 (agent lifecycle leaves the orchestrator)
+
+> ## ⚠️ Not shipped yet — do not action this guide
+>
+> **Nothing described below has landed.** This guide was written ahead of the change so the public
+> delta could be agreed before any code moved, and it is published early only so that agreement is
+> reviewable. It describes an *intended* contract.
+>
+> **In the package you are reading this in, the old API is still the live one:**
+>
+> | This guide says | Actually available today |
+> | --- | --- |
+> | `ChatDriver.installAgent` | ✗ — still `ChatDriver.applyAgent`, unchanged |
+> | `ChatDriver.activateAgent` | ✗ — does not exist |
+> | `ChatDriver.agentSession` | ✗ — does not exist |
+> | `pinned-changed` is dispatched | ✗ — still dead wiring |
+>
+> **Self-check, whatever version you are on:** if `installAgent` is not present on `ChatDriver`,
+> none of this has landed and you should change nothing.
+>
+> GENC-1580 ships in more than one PR. The first delivered an internal decomposition of `main.ts`
+> only — five feature controllers, no public API change of any kind. **The agent-lifecycle work
+> described here comes in a later PR under the same ticket**, and this notice is removed in the
+> same change that makes the guide true.
+>
+> ---
+>
+> When it does land: **config-compatible — no changes required to `chatConfig`, `agents`, or
+> `persistence`.** No element property, attribute, event or `::part()` changes. Nothing about which
+> driver runs your agents changes, so **no runtime behaviour changes**.
+>
+> You will need to read this if you call `ChatDriver` directly, or if you implement `AiDriver`
+> yourself. If you only configure the element, there is nothing here for you.
+>
+> All surfaces below are `@beta` unless marked otherwise.
+
+---
+
+## Why
+
+Stateful agents — anything built with `defineStatefulAgent`, or any `AgentConfig` declaring
+`onActivate`/`onDeactivate` — only worked under `OrchestratingDriver`. That was not a design
+decision; it was where the code happened to live.
+
+The contract was split across both drivers. `ChatDriver` **raised** the signals: it offers
+`releaseAgent` to tool handlers and records the call via `getAgentReleaseRequested()`.
+`OrchestratingDriver` was the only thing that **acted** on them — the only caller of
+`onActivate`/`onDeactivate`, the only holder of the restored-state images that reach an agent's
+`init` as `ctx.restored`, and the only implementer of `getActiveAgent()`, through which
+`serialize()` and `getDebugSnapshot()` are reached.
+
+The visible consequence was that the element routed *every* agents-configured session through the
+orchestrator — even a single agent with no routing to do — purely so the hooks would fire. A
+session with no agents at all got a bare `ChatDriver` and could not host a stateful agent.
+
+This change moves that lifecycle into an `AgentSession` that both drivers own, so the capability no
+longer depends on which driver you got.
+
+## What changed
+
+### 1. `ChatDriver.applyAgent` is renamed to `installAgent`
+
+**This is the only breaking change in this release.** `applyAgent` was public `@beta` and appeared
+in the published type rollup.
+
+```ts
+// before
+driver.applyAgent(config);
+
+// after
+driver.installAgent(config);
+```
+
+The behaviour is byte-identical: it installs an agent's system prompt, tool definitions, tool
+handlers and per-agent provider settings. It does **not** fire lifecycle hooks, and it never did.
+
+It was renamed because a new sibling now does:
+
+```ts
+/** Fire `onDeactivate`/`onActivate`, consume any restored state, then install. */
+await driver.activateAgent(config);
+```
+
+Two methods called `applyAgent` and `activateAgent`, one firing hooks and one not, is a footgun —
+and a demonstrated one. The hookless method is what `invokeSubAgent` calls, which is why sub-agent
+lifecycle hooks have never fired (see [Known remaining](#known-remaining-sub-agent-lifecycle)). The
+name `installAgent` says what it does, so the next reader has to choose deliberately.
+
+**Which one do you want?** If you are driving a single agent yourself and it has lifecycle hooks or
+state to restore, `activateAgent`. If you are re-applying a per-turn tool surface on an agent
+already activated, `installAgent`.
+
+### 2. `ChatDriver.agentSession` is exposed
+
+```ts
+/** @internal */
+readonly agentSession: AgentSession;
+```
+
+`AgentSession` owns one conversation's agent lifecycle: the live active `AgentConfig`, the
+`onActivate`/`onDeactivate` hooks, the pin and flow-owner locks, and the restored state images
+waiting to be handed back. It knows nothing about drivers, routing or history.
+
+It is **public but tagged `@internal`** — `OrchestratingDriver` reaches through the inner driver to
+it, so it cannot be private, but it is not a supported surface and may change without a migration
+guide. Prefer the delegating methods on the driver (§3) over touching it.
+
+It is reached through `ChatDriver` rather than owned separately by each driver because there is one
+session per conversation, and the inner driver outlives any routing decision made above it. That
+also puts `getAgentReleaseRequested()` and the session that responds to it in the same object,
+which is the coupling that used to span two classes.
+
+### 3. Four `AiDriver` members are no longer optional
+
+These moved from optional to required, because `ChatDriver` now implements all four:
+
+| Member | Was | Now |
+| --- | --- | --- |
+| `getActiveAgent()` | `OrchestratingDriver` only | both |
+| `setPinnedAgent(name)` | `OrchestratingDriver` only | both |
+| `setFlowOwner(name)` | `OrchestratingDriver` only | both |
+| `primeRestoredAgentState(snapshots)` | `OrchestratingDriver` only | both |
+
+**If you implement `AiDriver` yourself, this is a breaking change** — you must add all four.
+Delegate to an `AgentSession` if you want the standard semantics, or return `undefined` / no-op if
+your driver genuinely owns no agents.
+
+Callers can drop the optional-call guards:
+
+```ts
+// before
+const reserve = driver.getActiveAgent?.()?.contextReserve;
+
+// after
+const reserve = driver.getActiveAgent()?.contextReserve;
+```
+
+The remaining ten optional members on `AiDriver` are unchanged. They are a separate problem, and
+`ai-driver.ts` still carries a doc comment claiming the element depends only on this interface,
+which is not yet true.
+
+### 4. `pinned-changed` is now actually dispatched
+
+`setPinnedAgent()` was a bare assignment that emitted nothing, while the element registered a
+listener for `pinned-changed` and a comment asserting the driver did emit it. Neither half was
+right.
+
+`AgentSession.setPinnedAgent()` now emits `pinned-changed` with `string | null`, on the owning
+driver. If you were listening for it and quietly receiving nothing, you will now receive events.
+If you were not, nothing changes — the element's own pin path writes through its
+`pinnedAgentName` setter and guards against the redundant round-trip.
+
+### 5. Stateful agents no longer depend on the orchestrator
+
+`onActivate`, `onDeactivate`, `ctx.restored`, `serialize()`, `getDebugSnapshot()` and
+`releaseAgent` now work identically under either driver.
+
+**This is a capability, not yet a behaviour change.** Driver selection is deliberately untouched in
+this release: a configured `agents` array still gets `OrchestratingDriver`, exactly as before, and
+a single-agent session still pays for a classifier that short-circuits. Making the element choose a
+bare `ChatDriver` for a single agent is a follow-up, precisely because it *would* change runtime
+behaviour on the session-restore path and deserves its own release to be judged against.
+
+## What did not change
+
+- Every `chatConfig`, `agents` and `persistence` option, and every element property, attribute,
+  method, event and `::part()`.
+- Which driver runs your agents. `agents.length > 0` still means `OrchestratingDriver`.
+- The order and timing of lifecycle hooks: outgoing `onDeactivate` is awaited before incoming
+  `onActivate`; a hook that throws is logged and swallowed rather than stranding the turn; a
+  restored image is consumed exactly once per activation.
+- Which agent owns a flow. Stateful agents still auto-lock on activation, still hold the lock
+  across turns, and still release only via `releaseAgent` or teardown. The user pin still survives
+  a release.
+- `OrchestratingDriver`'s routing: classification, handoffs, the handoff cap, terminality rules,
+  the continuation tool, and per-agent history masking.
+- `OrchestratingDriver.applyAgent` — it was already private, and stays private. It shrinks, but its
+  name and signature are not part of any contract.
+- Session persistence and restore, including the shape written to the persistence provider.
+
+## Known remaining: sub-agent lifecycle
+
+**A stateful agent used as a sub-agent still gets no lifecycle hooks.** `invokeSubAgent` installs
+the child with the hookless path and tears it down with `dispose()`, so `onActivate` and
+`onDeactivate` never fire for it and its `serialize()` is never persisted.
+
+This has the same root cause and is deliberately out of scope, because fixing it needs decisions
+this refactor should not be making on its own:
+
+- Should a child's `onActivate` fire at all, given the parent already activated an agent?
+- What `sessionKey` does a child's lifecycle context carry?
+- Does a child's serialized state belong in the session snapshot, and under what key?
+
+Until that is settled, treat lifecycle hooks as a top-level-agent feature. A stateful agent
+invoked as a sub-agent will run its tools correctly but will not initialise or tear down state.
+
+## Internal reorganisation
+
+This release also splits the two largest modules. None of it is consumer-visible through the
+package's entry points (`.`, `./config`, `./chat-driver`, `./react`), but if you deep-import from
+`dist/esm/...` — which is unsupported — paths have moved:
+
+- `chat-driver.ts` sheds its turn-failure taxonomy, interaction handling, turn recording, turn
+  setup, fold machinery and provider resolution into sibling modules.
+- `main.ts` sheds the settings modal, composer controls, cost ledger, budget latching, context gate
+  and diagnostics assembly into controllers.
+
+See [`code-health.md`](./code-health.md) for the analysis behind the split. That file is excluded
+from the published package.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "15.23.3",
+  "version": "15.24.0",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -74,26 +74,26 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.23.3",
-    "@genesislcap/genx": "15.23.3",
-    "@genesislcap/rollup-builder": "15.23.3",
-    "@genesislcap/ts-builder": "15.23.3",
-    "@genesislcap/uvu-playwright-builder": "15.23.3",
-    "@genesislcap/vite-builder": "15.23.3",
-    "@genesislcap/webpack-builder": "15.23.3",
+    "@genesislcap/foundation-testing": "15.24.0",
+    "@genesislcap/genx": "15.24.0",
+    "@genesislcap/rollup-builder": "15.24.0",
+    "@genesislcap/ts-builder": "15.24.0",
+    "@genesislcap/uvu-playwright-builder": "15.24.0",
+    "@genesislcap/vite-builder": "15.24.0",
+    "@genesislcap/webpack-builder": "15.24.0",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2",
     "esbuild": "0.25.12"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "15.23.3",
-    "@genesislcap/foundation-logger": "15.23.3",
-    "@genesislcap/foundation-notifications": "15.23.3",
-    "@genesislcap/foundation-redux": "15.23.3",
-    "@genesislcap/foundation-ui": "15.23.3",
-    "@genesislcap/foundation-utils": "15.23.3",
-    "@genesislcap/rapid-design-system": "15.23.3",
-    "@genesislcap/web-core": "15.23.3",
+    "@genesislcap/foundation-ai": "15.24.0",
+    "@genesislcap/foundation-logger": "15.24.0",
+    "@genesislcap/foundation-notifications": "15.24.0",
+    "@genesislcap/foundation-redux": "15.24.0",
+    "@genesislcap/foundation-ui": "15.24.0",
+    "@genesislcap/foundation-utils": "15.24.0",
+    "@genesislcap/rapid-design-system": "15.24.0",
+    "@genesislcap/web-core": "15.24.0",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },