@genesislcap/ai-assistant 15.58.1 → 15.59.0

package/dist/esm/components/orchestrating-driver/orchestrating-driver.js

@@ -3,10 +3,12 @@ import { AIServiceError, BudgetExhaustedError } from '@genesislcap/foundation-ai
 import { validateStaticAgentProviders } from '../../config/validate-providers';
 import { recordMetaEvent } from '../../state/debug-event-log';
 import { reachesProvider } from '../../utils/context-tokens';
+import { DEFAULT_DELEGATE_FRAMING, frameDelegatedContent, } from '../../utils/delegated-message';
 import { transformHistoryForAgent } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
 import { messageUsage } from '../../utils/sum-usage';
-import { ChatDriver, REQUEST_CONTINUATION_TOOL, } from '../chat-driver/chat-driver';
+import { BaseDriverDecorator } from '../ai-driver/base-driver-decorator';
+import { ChatDriver, REQUEST_CONTINUATION_TOOL } from '../chat-driver/chat-driver';
 const DEFAULT_MAX_HANDOFFS = 3;
 const DEFAULT_CLASSIFIER_HISTORY_LENGTH = 4;
 const DEFAULT_CLASSIFIER_RETRIES = 2;
@@ -146,9 +148,19 @@ function buildFallbackSystemPrompt(fallback, specialists) {
  * and `ChatDriver`, classifying each user message and routing it to the right
  * specialist — each with its own focused system prompt, tools, and primer.
  *
+ * A {@link BaseDriverDecorator} over the `ChatDriver` it constructs (GENC-1485, GENC-1660): every
+ * `AiDriver` member and event it does not override passes straight through. Its inner driver is
+ * always one it built, never a composition choice, because routing reaches `ChatDriver`-only
+ * members (`installAgent`, `agentSession`, `getHistory`, `setProviderHistoryTransform`, the
+ * release flag and the `report…` exits). Other decorators go outside it.
+ *
  * @beta
  */
-export class OrchestratingDriver extends EventTarget {
+export class OrchestratingDriver extends BaseDriverDecorator {
+    /** The inner driver this one built and routes onto. */
+    get chatDriver() {
+        return this.inner;
+    }
     /**
      * The stateful-agent contract (§7.1): active agent, user pin, flow lock, restored state, and
      * the `onActivate` / `onDeactivate` hooks.
@@ -173,7 +185,7 @@ export class OrchestratingDriver extends EventTarget {
     }
     constructor(providerRegistry, agents, options = {}) {
         var _a, _b, _c, _d;
-        super();
+        super(OrchestratingDriver.createInner(providerRegistry, agents, options));
         this.providerRegistry = providerRegistry;
         this.agents = agents;
         /**
@@ -198,10 +210,6 @@ export class OrchestratingDriver extends EventTarget {
         this.classifierHistoryLength =
             (_c = options.classifierHistoryLength) !== null && _c !== void 0 ? _c : DEFAULT_CLASSIFIER_HISTORY_LENGTH;
         this.classifierRetries = (_d = options.classifierRetries) !== null && _d !== void 0 ? _d : DEFAULT_CLASSIFIER_RETRIES;
-        // Static-name validation: walk every agent (and nested sub-agents). Any
-        // `provider: '<name>'` that isn't registered, or resolves to a provider
-        // without `chat()`, throws now rather than at first turn.
-        validateStaticAgentProviders(agents, providerRegistry);
         // Specialists drive the classifier. `excludeFromClassifier` agents are still
         // resolvable by name (so manual pinning works) but never auto-routed.
         this.specialists = agents.filter(isSpecialist).filter((a) => !a.excludeFromClassifier);
@@ -212,151 +220,28 @@ export class OrchestratingDriver extends EventTarget {
         const rawFallback = fallbacks[0];
         this.fallback = rawFallback
             ? Object.assign(Object.assign({}, rawFallback), { systemPrompt: buildFallbackSystemPrompt(rawFallback, this.specialists) }) : undefined;
-        this.chatDriver = new ChatDriver(providerRegistry, {
+    }
+    /**
+     * Build the inner driver, after validating the agents' providers, so a bad config throws before
+     * a driver exists to subscribe to the registry. Static because it runs before `super()`.
+     */
+    static createInner(providerRegistry, agents, options = {}) {
+        var _a;
+        // Static-name validation: walk every agent (and nested sub-agents). Any
+        // `provider: '<name>'` that isn't registered, or resolves to a provider
+        // without `chat()`, throws now rather than at first turn.
+        validateStaticAgentProviders(agents, providerRegistry);
+        return new ChatDriver(providerRegistry, {
             maxToolIterations: options.maxToolIterations,
             maxFoldOperations: options.maxFoldOperations,
             maxTurnSnapshots: options.maxTurnSnapshots,
-            sessionKey: this.sessionKey,
+            sessionKey: (_a = options.sessionKey) !== null && _a !== void 0 ? _a : '',
             activityBus: options.activityBus,
             budgetExhaustedMessage: options.budgetExhaustedMessage,
             aiServiceErrorMessages: options.aiServiceErrorMessages,
-            // This driver releases after the turn so it can fire the host-facing events; see the option.
+            // A release ends this driver's handoff loop, so it acts on the flag itself; see the option.
             deferAgentRelease: true,
         });
-        // Proxy events from the shared driver
-        this.chatDriver.addEventListener('history-updated', (e) => {
-            this.dispatchEvent(new CustomEvent('history-updated', { detail: e.detail }));
-        });
-        this.chatDriver.addEventListener('sub-agent-history-updated', (e) => {
-            this.dispatchEvent(new CustomEvent('sub-agent-history-updated', { detail: e.detail }));
-        });
-        this.chatDriver.addEventListener('sub-agent-start', (e) => {
-            this.dispatchEvent(new CustomEvent('sub-agent-start', { detail: e.detail }));
-        });
-        this.chatDriver.addEventListener('sub-agent-stop', (e) => {
-            this.dispatchEvent(new CustomEvent('sub-agent-stop', { detail: e.detail }));
-        });
-        this.chatDriver.addEventListener('interaction-start', (e) => {
-            this.dispatchEvent(new CustomEvent('interaction-start', { detail: e.detail }));
-        });
-        this.chatDriver.addEventListener('interaction-stop', (e) => {
-            this.dispatchEvent(new CustomEvent('interaction-stop', { detail: e.detail }));
-        });
-        this.chatDriver.addEventListener('provider-changed', (e) => {
-            this.dispatchEvent(new CustomEvent('provider-changed', { detail: e.detail }));
-        });
-        // Post-resolve external cost. The host only ever holds THIS wrapper (`createDriver` returns
-        // one for any non-empty `agents`), so an event the inner driver raises and this list omits is
-        // an event the host never sees: `recordExternalCost` still delegates and the money still lands
-        // on the message, but the totals never refresh and the save is never scheduled — and in the
-        // flow this exists for the interaction is the last thing in the session, so "stale until the
-        // next history change" means permanently. Reviewer catch on #2474.
-        this.chatDriver.addEventListener('external-cost-recorded', (e) => {
-            this.dispatchEvent(new CustomEvent('external-cost-recorded', { detail: e.detail }));
-        });
-    }
-    resolveInteraction(interactionId, result) {
-        this.chatDriver.resolveInteraction(interactionId, result);
-    }
-    /** Delegated for the same reason as `resolveInteraction`: the history that owns the
-     *  interaction — and therefore the cost — lives on the wrapped driver, not here. */
-    recordExternalCost(interactionId, costUsd) {
-        return this.chatDriver.recordExternalCost(interactionId, costUsd);
-    }
-    getInteractionContext(interactionId) {
-        return this.chatDriver.getInteractionContext(interactionId);
-    }
-    isBusy() {
-        return this.chatDriver.isBusy();
-    }
-    /** Currently active provider name from the underlying ChatDriver. */
-    getActiveProviderName() {
-        return this.chatDriver.getActiveProviderName();
-    }
-    /**
-     * Pins routing to a specific agent by name. While pinned, the classifier is
-     * skipped and the continuation tool is hidden from the agent's tool list, so
-     * the agent cannot quietly hand back to the orchestrator. Pass `null` to
-     * return to automatic routing.
-     */
-    setPinnedAgent(name) {
-        this.agentSession.setPinned(name);
-    }
-    /**
-     * Set the flow-owner lock — used to restore state from Redux on driver
-     * reconstruction (agents-array changes, pop-in/pop-out). Not intended for
-     * external callers to manipulate routing; that's what `setPinnedAgent` is
-     * for.
-     */
-    setFlowOwner(name) {
-        this.agentSession.setFlowOwner(name);
-    }
-    loadHistory(messages) {
-        this.chatDriver.loadHistory(messages);
-    }
-    getRawHistory() {
-        return this.chatDriver.getHistory();
-    }
-    /**
-     * Delegates to the inner {@link ChatDriver} — condensation policies are registered there, so it
-     * is the only object that knows which payloads the model has stopped seeing (GENC-1566).
-     *
-     * **This forward is the whole feature, for any multi-agent host.** `AiDriver` declares
-     * `getHistoryForPersistence` optional, and `SessionPersister` calls it through `?.`, falling back
-     * to {@link OrchestratingDriver.getRawHistory}. This class does NOT extend `ChatDriver` — it
-     * wraps one — so without an explicit forward the optional call resolves to `undefined` and every
-     * host on an orchestrating driver silently keeps persisting the full payloads. Measured exactly
-     * that way on a Create run: 10 `context.condensed` events fired, and the session still stored
-     * the two largest `read_context` results at 26,907 and 23,060 chars. The method existed, the
-     * tests passed, and the feature did nothing.
-     */
-    getHistoryForPersistence() {
-        return this.chatDriver.getHistoryForPersistence();
-    }
-    /**
-     * Delegates to the inner {@link ChatDriver}, which owns the condensation registry and clocks
-     * (GENC-1632). The forward matters for the same reason as `getHistoryForPersistence` above: the
-     * persister reaches it through `?.`, so a missing forward would compile, pass the ChatDriver
-     * tests, and do nothing for every orchestrated host — which is every host with an agents array.
-     */
-    getCondensePoliciesForPersistence(messages) {
-        return this.chatDriver.getCondensePoliciesForPersistence(messages);
-    }
-    /**
-     * Delegates to the inner {@link ChatDriver} (GENC-1632). The deferred activation stamp it
-     * performs is taken by the inner driver's `installAgent`, which this driver's own
-     * `installAgent` always reaches, so nothing extra is needed here.
-     */
-    restoreCondensePolicies(entries) {
-        return this.chatDriver.restoreCondensePolicies(entries);
-    }
-    /** {@inheritDoc AiDriver.setContextGuard} */
-    setContextGuard(policy) {
-        this.chatDriver.setContextGuard(policy);
-    }
-    /** {@inheritDoc AiDriver.compact} */
-    compact(options) {
-        return this.chatDriver.compact(options);
-    }
-    /** {@inheritDoc AiDriver.canCompact} */
-    canCompact(options) {
-        return this.chatDriver.canCompact(options);
-    }
-    /** {@inheritDoc AiDriver.getPreambleTokens} */
-    getPreambleTokens() {
-        return this.chatDriver.getPreambleTokens();
-    }
-    /** {@inheritDoc AiDriver.getCompactionPlan} */
-    getCompactionPlan(options) {
-        return this.chatDriver.getCompactionPlan(options);
-    }
-    /** Delegates to the inner {@link ChatDriver} — turns are captured there. */
-    getTurnSnapshots() {
-        return this.chatDriver.getTurnSnapshots();
-    }
-    /** Delegates to the inner {@link ChatDriver} — interactions resolve there, so it holds the buffer. */
-    getExternalDiagnostics() {
-        return this.chatDriver.getExternalDiagnostics();
     }
     getSuggestions(history, prompt, count, allAgentInfo) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -375,10 +260,18 @@ export class OrchestratingDriver extends EventTarget {
             return this.chatDriver.getSuggestions(history, prompt, count, agentInfo);
         });
     }
-    sendMessage(input, attachments) {
+    sendMessage(input, attachments, options) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            // Who it is from travels with every copy of the message this method makes (GENC-1660).
+            const delegated = (options === null || options === void 0 ? void 0 : options.delegate)
+                ? {
+                    delegate: options.delegate,
+                    delegateFraming: (_a = options.delegateFraming) !== null && _a !== void 0 ? _a : DEFAULT_DELEGATE_FRAMING,
+                }
+                : {};
             try {
-                return yield this.runOrchestratedTurn(input, attachments);
+                return yield this.runOrchestratedTurn(input, attachments, options, delegated);
             }
             catch (e) {
                 // The classifier calls the provider directly, outside any ChatDriver turn,
@@ -398,7 +291,7 @@ export class OrchestratingDriver extends EventTarget {
                 // snapshot, and the history sent to the model once the budget is raised.
                 const pendingUserMessage = this.userMessageAppended
                     ? undefined
-                    : Object.assign({ role: 'user', content: input }, (attachments ? { attachments } : {}));
+                    : Object.assign(Object.assign({ role: 'user', content: input }, (attachments ? { attachments } : {})), delegated);
                 if (e instanceof BudgetExhaustedError) {
                     return this.chatDriver.reportBudgetExhausted(e, pendingUserMessage);
                 }
@@ -410,7 +303,7 @@ export class OrchestratingDriver extends EventTarget {
             }
         });
     }
-    runOrchestratedTurn(input, attachments) {
+    runOrchestratedTurn(input, attachments, options, delegated) {
         return __awaiter(this, void 0, void 0, function* () {
             this.cancelled = false;
             this.userMessageAppended = false;
@@ -418,7 +311,7 @@ export class OrchestratingDriver extends EventTarget {
             // Emit the user message immediately so the UI reflects it during the classify
             // round-trip — without this the chat appears frozen until classify returns.
             this.dispatchEvent(new CustomEvent('history-updated', {
-                detail: [...history, { role: 'user', content: input, attachments }],
+                detail: [...history, Object.assign({ role: 'user', content: input, attachments }, delegated)],
             }));
             const pinned = this.resolvePinnedAgent();
             if (!pinned)
@@ -432,7 +325,7 @@ export class OrchestratingDriver extends EventTarget {
                 routed = { agent: pinned, decision: 'pinned' };
             }
             else {
-                routed = yield this.classify(input, history, this.activeAgent);
+                routed = yield this.classify(delegated.delegate ? frameDelegatedContent(input, delegated.delegateFraming) : input, history, this.activeAgent);
             }
             let currentAgent = routed.agent;
             let isHandoff = false;
@@ -503,7 +396,7 @@ export class OrchestratingDriver extends EventTarget {
                     // handoff classify) sees the append as done.
                     this.userMessageAppended = true;
                     // oxlint-disable-next-line no-await-in-loop
-                    result = yield this.chatDriver.sendMessage(input, attachments);
+                    result = yield this.chatDriver.sendMessage(input, attachments, options);
                 }
                 lastResult = result;
                 // Release check: a stateful agent called `releaseAgent` from a terminal
@@ -559,20 +452,11 @@ export class OrchestratingDriver extends EventTarget {
             // install — leaves it shown only by the optimistic dispatch above, and it would vanish on the
             // next update and from a reload. Kept, as the budget wall keeps it (see sendMessage).
             if (this.cancelled && !this.userMessageAppended) {
-                this.chatDriver.reportStoppedBeforeTurn(Object.assign({ role: 'user', content: input }, (attachments ? { attachments } : {})));
+                this.chatDriver.reportStoppedBeforeTurn(Object.assign(Object.assign({ role: 'user', content: input }, (attachments ? { attachments } : {})), delegated));
             }
             return (lastResult === null || lastResult === void 0 ? void 0 : lastResult.reason) === 'done' ? lastResult : { reason: 'done' };
         });
     }
-    continueFromHistory(transientPrimer, options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            return this.chatDriver.continueFromHistory(transientPrimer, options);
-        });
-    }
-    /** {@inheritDoc AiDriver.primeRestoredAgentState} */
-    primeRestoredAgentState(snapshots) {
-        this.agentSession.primeRestoredStates(snapshots);
-    }
     /** {@inheritDoc AiDriver.canRestoreFlowOwner} */
     canRestoreFlowOwner(agentName) {
         return this.agents.some((a) => a.name === agentName);
@@ -589,6 +473,10 @@ export class OrchestratingDriver extends EventTarget {
      * to classify, and a restored lock already says which agent owns the flow. `continueFromHistory`
      * on its own would not do — it neither routes nor installs, so it would run on whatever agent
      * happened to be installed (none, straight after a reload).
+     *
+     * Looks the owner up in its own agents list, so the `agent` argument is not needed and is
+     * ignored; and does not delegate to the inner driver's resume, which would install the agent
+     * undecorated.
      */
     resumeRestoredFlow(resumeNote) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -659,19 +547,12 @@ export class OrchestratingDriver extends EventTarget {
         }
         return winner ? Object.assign(Object.assign({}, winner), { agentName, basis: 'reachable-max' }) : undefined;
     }
-    /** {@inheritDoc AiDriver.getActiveAgent} */
-    getActiveAgent() {
-        return this.agentSession.getActive();
-    }
     installAgent(agent) {
         return __awaiter(this, void 0, void 0, function* () {
             // The transition — handoff record, lifecycle hooks, restored state, flow lock — belongs to
-            // the session. What is left below is this driver's own job: what the agent may route to, and
-            // what the transcript says happened.
-            const { previousAgent, flowOwnerChangedTo } = yield this.agentSession.activate(agent);
-            if (flowOwnerChangedTo !== undefined) {
-                this.dispatchEvent(new CustomEvent('flow-owner-changed', { detail: flowOwnerChangedTo }));
-            }
+            // the session, and the inner driver raises its events (GENC-1485). What is left below is this
+            // driver's own job: what the agent may route to, and what the transcript says happened.
+            const { previousAgent } = yield this.agentSession.activate(agent);
             // Terminal agents do not get the cross-agent handoff tool. Four cases:
             //   • fallback     — already a leaf; handoff would loop
             //   • user-pinned  — user explicitly selected this agent; do not auto-route away
@@ -707,13 +588,12 @@ export class OrchestratingDriver extends EventTarget {
             this.chatDriver.setProviderHistoryTransform((h) => transformHistoryForAgent(h, agent.name));
             this.chatDriver.installAgent(agentToApply);
             this.dispatchEvent(new CustomEvent('orchestrating-stop'));
-            this.dispatchEvent(new CustomEvent('agent-changed', { detail: agent }));
         });
     }
     /**
-     * Release the current stateful agent: fire `onDeactivate`, clear the
-     * flow-owner lock, dispatch events so the host (and Redux) reflect the
-     * unlocked state. Called automatically when a tool handler invokes
+     * Release the current stateful agent: fire `onDeactivate` and clear the flow-owner lock. The
+     * inner driver raises the events from the session's transition, so the host (and Redux) reflect
+     * the unlocked state (GENC-1485). Called automatically when a tool handler invokes
      * `context.releaseAgent`.
      *
      * The user-pin (`pinnedAgentName`) is intentionally *not* cleared — a user
@@ -723,14 +603,7 @@ export class OrchestratingDriver extends EventTarget {
      */
     releaseActiveAgent() {
         return __awaiter(this, void 0, void 0, function* () {
-            const released = yield this.agentSession.release();
-            if (!released)
-                return;
-            if (released.flowOwnerChangedTo !== undefined) {
-                this.dispatchEvent(new CustomEvent('flow-owner-changed', { detail: released.flowOwnerChangedTo }));
-            }
-            this.dispatchEvent(new CustomEvent('agent-released', { detail: released.previousAgent }));
-            this.dispatchEvent(new CustomEvent('agent-changed', { detail: undefined }));
+            yield this.agentSession.release();
         });
     }
     /**
@@ -755,6 +628,7 @@ export class OrchestratingDriver extends EventTarget {
             yield this.agentSession.dispose();
             // Tear down the inner driver too, so any in-flight provider request aborts.
             yield this.chatDriver.dispose();
+            this.detach();
         });
     }
     /**
@@ -796,9 +670,12 @@ export class OrchestratingDriver extends EventTarget {
             .filter((m) => { var _a; return !!((_a = m.content) === null || _a === void 0 ? void 0 : _a.trim()); })
             .slice(-this.classifierHistoryLength)
             .map((m) => {
-            var _a;
+            var _a, _b;
             const speaker = m.role === 'user' ? 'User' : 'Assistant';
-            const content = (_a = m.content) !== null && _a !== void 0 ? _a : '';
+            // A delegated message is framed for the router as for every model (GENC-1660).
+            const content = m.role === 'user' && m.delegate
+                ? frameDelegatedContent((_a = m.content) !== null && _a !== void 0 ? _a : '', m.delegateFraming)
+                : ((_b = m.content) !== null && _b !== void 0 ? _b : '');
             const body = content.length > CLASSIFIER_MESSAGE_CHARS
                 ? `${content.slice(0, CLASSIFIER_MESSAGE_CHARS)}…`
                 : content;
@@ -1019,20 +896,19 @@ export class OrchestratingDriver extends EventTarget {
     }
 }
 /**
- * Narrow a driver to an orchestrator, or `undefined` for a bare `ChatDriver`.
+ * The orchestrator in a driver's decorator stack, or `undefined` when there is none (a bare
+ * `ChatDriver`, possibly decorated).
  *
- * **The one place in the package that tests for this type** (`docs/code-health.md`
- * §11.2 constraint 3). Orchestration-only capabilities — the agent pin, the
- * flow-owner lock, the context guard — are reached through it, so when §7.1 lifts
- * those onto `AiDriver` and they stop being orchestrator-only, this function is
- * what changes rather than every consumer.
- *
- * Lives beside the class rather than on the assistant element because two modules
- * need it: the element (for its own driver) and the session persister (for the
- * driver it restores into), and a private element accessor cannot serve both.
+ * **The one place in the package that tests for this type** (`docs/code-health.md` §11.2
+ * constraint 3). Since GENC-1660 nothing behavioural goes through it: the agent pin, the
+ * flow-owner lock, the context guard and the lifecycle events are all reached on `AiDriver`
+ * itself, which every decorator forwards. What is left is labelling — the host's `driverKind`
+ * in its log lines — and it looks through decorators so that label stays true behind one.
  *
  * @internal
  */
 export function asOrchestrator(driver) {
-    return driver instanceof OrchestratingDriver ? driver : undefined;
+    if (!driver)
+        return undefined;
+    return BaseDriverDecorator.layers(driver).find((layer) => layer instanceof OrchestratingDriver);
 }

package/dist/esm/index.js

@@ -17,6 +17,7 @@ export * from './provider/ai-provider-switcher';
 export * from './provider/tiered-provider-switcher';
 export * from './provider/assistant-app-settings';
 export * from './utils/tool-fold';
+export { DEFAULT_DELEGATE_FRAMING, isDelegated, } from './utils/delegated-message';
 export { assistantSettingsSectionTitleStyles } from './styles/settings-section';
 // MARKDOWN_EXPORTPARTS travels with the component: a host rendering `<ai-chat-markdown>` in its
 // own shadow root has to forward its parts, and hand-copying the list is how it drifts.