@genesislcap/ai-assistant 15.24.2 → 15.26.0

package/dist/esm/suggestions/generate-suggestions.js

@@ -0,0 +1,123 @@
+import { __awaiter } from "tslib";
+import { logger } from '../utils/logger';
+/** Turns of transcript given to the model when suggesting follow-ups. */
+const HISTORY_WINDOW = 8;
+/**
+ * The capabilities block: what the assistant can do, so suggestions cannot promise more.
+ *
+ * Prefers the host's full agent list; falls back to the active agent's own tools when the caller
+ * has no cross-agent view.
+ */
+function capabilities(ctx, allAgentInfo) {
+    let agentContext = '';
+    let toolContext = '';
+    if (allAgentInfo === null || allAgentInfo === void 0 ? void 0 : allAgentInfo.length) {
+        const agentDescriptions = allAgentInfo
+            .map((agent) => {
+            const tools = agent.tools.map((t) => t.name).join(', ');
+            return `- ${agent.name} (${agent.description}): ${tools ? `(Tools: ${tools})` : 'No tools'}`;
+        })
+            .join('\n');
+        agentContext = `The assistant has the following capabilities:\n${agentDescriptions}`;
+        const allToolNames = [
+            ...new Set(allAgentInfo.flatMap((agent) => agent.tools.map((t) => t.name))),
+        ].join(', ');
+        toolContext = allToolNames
+            ? `You have access to the following tools across all agents: ${allToolNames}.`
+            : '';
+    }
+    else if (ctx.activeAgentName) {
+        const toolNames = ctx.toolDefinitions.map((tool) => tool.name).join(', ');
+        agentContext = `You are currently acting as the "${ctx.activeAgentName}" agent.`;
+        toolContext = toolNames ? `You have access to the following tools: ${toolNames}.` : '';
+    }
+    return agentContext || toolContext
+        ? `\n\n<capabilities>\n${[agentContext, toolContext]
+            .filter(Boolean)
+            .join('\n')}\n</capabilities>\nSuggestions must only cover what the agent is capable of. Do not suggest anything outside these capabilities.`
+        : '';
+}
+const OUTPUT_FORMAT = (count) => `\n\nOutput format (strict):\n` +
+    `- Exactly ${count} lines.\n` +
+    `- One suggestion per line.\n` +
+    `- No numbering, bullets, markdown, emojis, code blocks, or quotes around the suggestion.\n` +
+    `- No preamble, headings, summary, or commentary before or after the list.`;
+/**
+ * The system prompt sets the role only.
+ *
+ * Concrete instructions live in the user message *after* the transcript, so the context
+ * immediately preceding the model is "here is data, now do X" rather than "here is a dialogue,
+ * continue it". This matters for Anthropic — without it, Claude reads the transcript as an
+ * in-progress conversation and produces a normal assistant turn instead of a list.
+ */
+export const SUGGESTIONS_SYSTEM_PROMPT = 'You generate suggested prompts that a user could send to an AI assistant. ' +
+    'You never continue the conversation or roleplay as the assistant.';
+/** Build the user message: starter prompts for an empty transcript, follow-ups otherwise. */
+export function buildSuggestionsPrompt(ctx, history, prompt, count, allAgentInfo) {
+    const capabilitiesBlock = capabilities(ctx, allAgentInfo);
+    const guidanceBlock = prompt ? `\n\nAdditional guidance: "${prompt}"` : '';
+    if (history.length === 0) {
+        return (`Generate exactly ${count} brief starter prompts to show a user what an AI assistant can do. ` +
+            `Phrase each one as the user would write it. Keep them short and generic — do not invent specific names, IDs, or data (e.g. prefer "Search for a trade" over "Find all trades with Client A").` +
+            capabilitiesBlock +
+            guidanceBlock +
+            OUTPUT_FORMAT(count));
+    }
+    const conversationContext = history
+        .filter((m) => {
+        var _a, _b;
+        return (m.role === 'user' || m.role === 'assistant') &&
+            !((_a = m.toolCalls) === null || _a === void 0 ? void 0 : _a.length) &&
+            !m.thinking &&
+            !!((_b = m.content) === null || _b === void 0 ? void 0 : _b.trim());
+    })
+        .slice(-HISTORY_WINDOW)
+        .map((m) => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}`)
+        .join('\n');
+    return (`<conversation_history>\n${conversationContext}\n</conversation_history>\n\n` +
+        `The conversation above has ended. Do not continue it or respond as the assistant. ` +
+        `Generate exactly ${count} follow-up prompts the *user* might send next, phrased in first person as the user would write them. ` +
+        `The first ${Math.max(0, count - 1)} should be natural follow-ups to the last turn. ` +
+        `Do not invent specific names, IDs, or data values that do not appear in <conversation_history>.` +
+        capabilitiesBlock +
+        guidanceBlock +
+        OUTPUT_FORMAT(count));
+}
+/**
+ * Lenient parsing, as a backstop: even with the strict format above, models slip in numbering,
+ * bullets or surrounding markdown.
+ */
+export function parseSuggestions(text, count) {
+    return (text
+        .split('\n')
+        .map((s) => s.trim())
+        // leading bullets/numbers ("- ", "* ", "• ", "1. ", "1) ")
+        .map((s) => s.replace(/^([-*•]|\d+[.)])\s+/, ''))
+        // surrounding bold/italic markers
+        .map((s) => s.replace(/^[*_]{1,3}|[*_]{1,3}$/g, '').trim())
+        .filter((s) => s.length > 0)
+        .filter((s) => !/^[-=]{2,}$/.test(s))
+        .filter((s) => !/^here (are|is) /i.test(s))
+        .filter((s) => !s.endsWith(':'))
+        .slice(0, count));
+}
+/**
+ * Suggested prompts for the composer.
+ *
+ * Best-effort throughout: a default provider with no `prompt()` means no suggestions, not an
+ * error, because this is an out-of-turn UI helper.
+ */
+export function generateSuggestions(ctx, history, prompt, count, allAgentInfo) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const defaultProvider = ctx.registry.default();
+        if (!defaultProvider.prompt) {
+            logger.warn('ChatDriver: default AI provider does not implement prompt()');
+            return [];
+        }
+        const userMessage = buildSuggestionsPrompt(ctx, history, prompt, count, allAgentInfo);
+        const text = yield defaultProvider.prompt(userMessage, {
+            systemPrompt: SUGGESTIONS_SYSTEM_PROMPT,
+        });
+        return parseSuggestions(text, count);
+    });
+}

package/dist/esm/utils/agents-key.js

@@ -0,0 +1,24 @@
+/**
+ * A stable fingerprint for an agents array, compared against the installed driver's to decide
+ * whether an `agents` change needs the driver rebuilt.
+ *
+ * So it must change when the driver's tool surface would, and not otherwise: handler key order is
+ * sorted out, agent order is significant.
+ */
+export function agentsKey(agents) {
+    if (!(agents === null || agents === void 0 ? void 0 : agents.length))
+        return '';
+    return agents
+        .map((a) => {
+        var _a;
+        // Function-form handlers resolve per turn, so their key set is unknowable here. The marker
+        // still separates static from dynamic; two different resolvers are indistinguishable.
+        const toolNames = typeof a.toolHandlers === 'function'
+            ? '<fn>'
+            : Object.keys((_a = a.toolHandlers) !== null && _a !== void 0 ? _a : {})
+                .sort()
+                .join('+');
+        return `${a.name}[${toolNames}]`;
+    })
+        .join(',');
+}

package/dist/esm/utils/resolve-turn-input.js

@@ -0,0 +1,16 @@
+import { __awaiter } from "tslib";
+/**
+ * Resolve a config input that may be a static value or a per-turn resolver.
+ *
+ * `undefined` in, `undefined` out — an unset input stays unset rather than resolving to a default
+ * the caller never asked for.
+ */
+export function resolveTurnInput(input, ctx) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (input === undefined)
+            return undefined;
+        return typeof input === 'function'
+            ? input(ctx)
+            : input;
+    });
+}

package/docs/migration-GENC-1580.md

@@ -1,22 +1,29 @@
 # Migration Guide — GENC-1580 (agent lifecycle leaves the orchestrator)
 
-> ## ⚠️ Not shipped yet — do not action this guide
+> ## ⚠️ Partly shipped — the rename has not landed, so do not action the rename
 >
-> **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.
+> The structural half of this change is in. What is **not** in is the one part that would break
+> you: `ChatDriver.applyAgent` has not been renamed. It was held back deliberately, to land alone
+> as the last PR of GENC-1580 — the rename cannot be caught by a compiler in a JavaScript caller,
+> so it is worth scheduling rather than absorbing alongside a refactor.
 >
-> **In the package you are reading this in, the old API is still the live one:**
+> **What the package you are reading this in actually has:**
 >
 > | 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 |
+> | `ChatDriver.activateAgent` | ✓ — available, fires the lifecycle hooks |
+> | `ChatDriver.agentSession` | ✓ — available (`@internal`) |
+> | `getActiveAgent` / `primeRestoredAgentState` implemented by both drivers | ✓ — and `setPinnedAgent` / `setFlowOwner` are on the interface now, all four **optional** |
+> | `ChatDriver.installAgent` | ✗ — **still `ChatDriver.applyAgent`, unchanged** |
+> | `pinned-changed` is dispatched | ✗ — still dead wiring (§7.2 of `code-health.md`) |
 >
 > **Self-check, whatever version you are on:** if `installAgent` is not present on `ChatDriver`,
-> none of this has landed and you should change nothing.
+> the rename has not landed and you should not touch your `applyAgent` calls. §4 is also **not**
+> shipped — it carries its own notice. Everything else here is current.
+>
+> **Nothing you have today breaks on this release.** `applyAgent` keeps working, and every
+> `AiDriver` member this ticket touched is declared optional, so an implementor of that interface
+> is unaffected too.
 >
 > 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
@@ -110,45 +117,46 @@ session per conversation, and the inner driver outlives any routing decision mad
 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
+### 3. Four `AiDriver` members are implemented by both drivers
 
-These moved from optional to required, because `ChatDriver` now implements all four:
+`ChatDriver` now implements all four, so they are no longer orchestrator-only:
 
 | Member | Was | Now |
 | --- | --- | --- |
-| `getActiveAgent()` | `OrchestratingDriver` only | both |
-| `setPinnedAgent(name)` | `OrchestratingDriver` only | both |
-| `setFlowOwner(name)` | `OrchestratingDriver` only | both |
-| `primeRestoredAgentState(snapshots)` | `OrchestratingDriver` only | both |
+| `getActiveAgent?()` | `OrchestratingDriver` only | both |
+| `setPinnedAgent?(name)` | not on the interface | both |
+| `setFlowOwner?(name)` | not on the interface | 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.
+**Nothing to do, and nothing breaks.** All four are declared **optional**, so a third party
+implementing `AiDriver` is unaffected: two were already optional and two are new additions. Keep
+your `?.()` guards — they still type-check, and the interface makes no promise a caller can lean
+on yet.
 
-Callers can drop the optional-call guards:
+The `?` comes off in the same release as the `installAgent` rename, which is the only breaking
+change in this ticket. That is when the guards can go:
 
 ```ts
-// before
-const reserve = driver.getActiveAgent?.()?.contextReserve;
-
-// after
-const reserve = driver.getActiveAgent()?.contextReserve;
+// after the breaking release, not before
+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.
+Fourteen members on `AiDriver` remain optional. 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` — still not dispatched, still nothing to do
 
-### 4. `pinned-changed` is now actually dispatched
+> **Not in this release.** Described here because it is part of the intended contract; the code is
+> not written. Do not act on this section.
 
-`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.
+`setPinnedAgent` is a bare write that emits nothing, while the element registers a listener for
+`pinned-changed` and a comment asserting the driver does emit it. Neither half is right, and
+GENC-1580 did not change it: `AgentSession.setPinned` is still a plain assignment, and nothing in
+the package calls `dispatchEvent` with `pinned-changed`.
 
-`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.
+The intended fix is for the pin write to report a transition the owning driver dispatches, the way
+`flow-owner-changed` already works. Until then, a listener receives nothing — as before.
 
 ### 5. Stateful agents no longer depend on the orchestrator
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "15.24.2",
+  "version": "15.26.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.24.2",
-    "@genesislcap/genx": "15.24.2",
-    "@genesislcap/rollup-builder": "15.24.2",
-    "@genesislcap/ts-builder": "15.24.2",
-    "@genesislcap/uvu-playwright-builder": "15.24.2",
-    "@genesislcap/vite-builder": "15.24.2",
-    "@genesislcap/webpack-builder": "15.24.2",
+    "@genesislcap/foundation-testing": "15.26.0",
+    "@genesislcap/genx": "15.26.0",
+    "@genesislcap/rollup-builder": "15.26.0",
+    "@genesislcap/ts-builder": "15.26.0",
+    "@genesislcap/uvu-playwright-builder": "15.26.0",
+    "@genesislcap/vite-builder": "15.26.0",
+    "@genesislcap/webpack-builder": "15.26.0",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2",
     "esbuild": "0.25.12"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "15.24.2",
-    "@genesislcap/foundation-logger": "15.24.2",
-    "@genesislcap/foundation-notifications": "15.24.2",
-    "@genesislcap/foundation-redux": "15.24.2",
-    "@genesislcap/foundation-ui": "15.24.2",
-    "@genesislcap/foundation-utils": "15.24.2",
-    "@genesislcap/rapid-design-system": "15.24.2",
-    "@genesislcap/web-core": "15.24.2",
+    "@genesislcap/foundation-ai": "15.26.0",
+    "@genesislcap/foundation-logger": "15.26.0",
+    "@genesislcap/foundation-notifications": "15.26.0",
+    "@genesislcap/foundation-redux": "15.26.0",
+    "@genesislcap/foundation-ui": "15.26.0",
+    "@genesislcap/foundation-utils": "15.26.0",
+    "@genesislcap/rapid-design-system": "15.26.0",
+    "@genesislcap/web-core": "15.26.0",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },