@deepseek-harness-tui/dsh-tui 0.6.0 → 0.7.0

package/lib/types/dsh-adapter/providerWizard.js

@@ -0,0 +1,332 @@
+/**
+ * `/provider` wizard — interactively adds an LLM provider route at runtime.
+ *
+ * The wizard is a sequence of `QuestionStore` asks (the same panel the
+ * model-facing `ask_user_question` tool uses), so it needs no UI state of
+ * its own. All side effects go through {@link ProviderSetupHost}, which the
+ * channel implements over the dsh settings/credentials/llm seams:
+ *
+ *   profile → settings `llm-pi-ai.providers.<route>` (dsh-llm-pi-ai watches
+ *             the section and registers the route without a restart)
+ *   key     → credentials store (`~/.dsh/.credentials.yaml`, 0600), named by
+ *             the derived `<ROUTE>_API_KEY` env-style ref the profile's
+ *             `apiKeyEnv` points at
+ *
+ * The module is React-free so `scripts/verify-provider-wizard.mjs` can drive
+ * it headless with a stubbed host and scripted answers.
+ */
+import { t } from '../i18n.js';
+import { UserQuestionError, } from '@deepseek-ai/dsh-user-questions';
+/** Route id rule shared with the dsh configuration surface (web Models page). */
+export const PROVIDER_ROUTE_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/** Wire protocols dsh-llm-pi-ai can serve on a manually declared route. */
+export const PROVIDER_PROTOCOLS = [
+    'openai-completions',
+    'openai-responses',
+    'anthropic-messages',
+];
+/**
+ * Derive the credential ref for a route, matching the official web UI
+ * convention so TUI- and web-added providers resolve the same key.
+ */
+export function deriveKeyRef(route) {
+    return `${route.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_API_KEY`;
+}
+/** Max attempts for validated free-text prompts before giving up. */
+const MAX_RETRY = 3;
+function answerText(answer, id) {
+    return answer.answers.find(item => item.id === id)?.custom?.trim() ?? '';
+}
+function answerSelected(answer, id) {
+    return answer.answers.find(item => item.id === id)?.selected ?? [];
+}
+function optionQuestion(id, question, options, extra) {
+    const item = {
+        id,
+        question,
+        header: '/provider',
+        options: options.map(option => ({ ...option })),
+        ...(extra?.detail !== undefined ? { detail: extra.detail } : {}),
+        ...(extra?.multiSelect ? { multiSelect: true } : {}),
+        ...(extra?.hideCustomInput ? { hideCustomInput: true } : {}),
+    };
+    return item;
+}
+function textQuestion(id, question, detail) {
+    return {
+        id,
+        question,
+        header: '/provider',
+        ...(detail !== undefined ? { detail } : {}),
+    };
+}
+/**
+ * Run the add-provider wizard. Resolves 'cancelled' when the user dismisses
+ * any question (Esc) — nothing has been written at that point by design:
+ * all asks complete before the first side effect.
+ */
+export async function runProviderWizard(deps) {
+    const { host, ask, notify, pushLocal } = deps;
+    try {
+        // ── 1. mode ────────────────────────────────────────────────────────
+        const modeAnswer = await ask({
+            questions: [optionQuestion('mode', t('provider-q-mode'), [
+                    { label: t('provider-opt-catalog'), description: t('provider-opt-catalog-desc') },
+                    { label: t('provider-opt-custom'), description: t('provider-opt-custom-desc') },
+                ], { hideCustomInput: true })],
+        });
+        const isCatalog = answerSelected(modeAnswer, 'mode')[0] === t('provider-opt-catalog');
+        // ── 2. route ───────────────────────────────────────────────────────
+        let route = '';
+        if (isCatalog) {
+            const candidates = host.listCatalogProviders();
+            if (candidates.length > 0) {
+                const otherLabel = t('provider-opt-other-route');
+                const catalogAnswer = await ask({
+                    questions: [optionQuestion('catalog', t('provider-q-catalog'), [
+                            ...candidates.map(candidate => ({
+                                label: candidate.provider,
+                                description: candidate.displayName,
+                            })),
+                            { label: otherLabel, description: t('provider-opt-other-route-desc') },
+                        ], { hideCustomInput: true })],
+                });
+                const pick = answerSelected(catalogAnswer, 'catalog')[0];
+                if (pick !== undefined && pick !== otherLabel)
+                    route = pick;
+            }
+        }
+        if (route === '') {
+            route = await promptRouteId(ask, notify);
+            if (route === '')
+                return 'cancelled';
+        }
+        // ── 3. API key (own batch so redact covers exactly the secret) ─────
+        const keyAnswer = await ask({
+            questions: [textQuestion('apikey', t('provider-q-apikey'), t('provider-q-apikey-detail'))],
+        }, { redact: true });
+        const apiKey = answerText(keyAnswer, 'apikey');
+        // ── 4. endpoint / protocol ─────────────────────────────────────────
+        let baseURL;
+        let api;
+        if (isCatalog) {
+            const choiceAnswer = await ask({
+                questions: [optionQuestion('baseurl-choice', t('provider-q-baseurl-choice'), [
+                        { label: t('provider-opt-baseurl-skip') },
+                        { label: t('provider-opt-baseurl-input') },
+                    ], { hideCustomInput: true })],
+            });
+            if (answerSelected(choiceAnswer, 'baseurl-choice')[0] === t('provider-opt-baseurl-input')) {
+                const urlAnswer = await ask({
+                    questions: [textQuestion('baseurl', t('provider-q-baseurl'))],
+                });
+                baseURL = answerText(urlAnswer, 'baseurl');
+            }
+        }
+        else {
+            const endpointAnswer = await ask({
+                questions: [
+                    textQuestion('baseurl', t('provider-q-baseurl')),
+                    optionQuestion('protocol', t('provider-q-protocol'), [
+                        { label: 'openai-completions', description: t('provider-protocol-completions-desc') },
+                        { label: 'openai-responses', description: t('provider-protocol-responses-desc') },
+                        { label: 'anthropic-messages', description: t('provider-protocol-anthropic-desc') },
+                    ], { hideCustomInput: true }),
+                ],
+            });
+            baseURL = answerText(endpointAnswer, 'baseurl');
+            api = answerSelected(endpointAnswer, 'protocol')[0];
+        }
+        // ── 5. model discovery (draft credential, nothing persisted) ───────
+        notify(t('provider-discovery-running'));
+        const discovered = await host.discoverModels({
+            ...(isCatalog ? { provider: route } : {}),
+            ...(baseURL !== undefined && baseURL !== '' ? { baseURL } : {}),
+            ...(api !== undefined ? { api } : {}),
+            apiKey,
+        }).catch(() => []);
+        // ── 6. model selection ─────────────────────────────────────────────
+        let models = [];
+        let discoveredById = new Map();
+        if (discovered.length > 0) {
+            discoveredById = new Map(discovered.map(model => [model.id, model]));
+            const modelsAnswer = await ask({
+                questions: [optionQuestion('models', t('provider-q-models'), discovered.map(model => ({
+                        label: model.id,
+                        description: [
+                            model.name ?? '',
+                            model.contextWindow !== undefined ? `${model.contextWindow}` : '',
+                        ].filter(part => part !== '').join(' · ') || undefined,
+                    })), { multiSelect: true })],
+            });
+            models = mergeModelIds(answerSelected(modelsAnswer, 'models'), answerText(modelsAnswer, 'models'));
+        }
+        else {
+            notify(t('provider-discovery-failed'), { color: 'warning' });
+            for (let attempt = 0; attempt < MAX_RETRY && models.length === 0; attempt += 1) {
+                const fallbackAnswer = await ask({
+                    questions: [textQuestion('models-fallback', t('provider-q-models-fallback'))],
+                });
+                models = mergeModelIds([], answerText(fallbackAnswer, 'models-fallback'));
+                if (models.length === 0)
+                    notify(t('provider-models-required'), { color: 'warning' });
+            }
+            if (models.length === 0)
+                return 'cancelled';
+        }
+        if (!isCatalog && models.length === 0) {
+            // A manual route without models fails the adapter validation; the
+            // loops above should prevent this, but guard before writing.
+            notify(t('provider-models-required'), { color: 'error' });
+            return 'cancelled';
+        }
+        // ── 7. confirm ─────────────────────────────────────────────────────
+        const ref = deriveKeyRef(route);
+        const shadowed = host.envShadows(ref);
+        const summaryLines = buildSummaryLines({
+            route, ref, shadowed, baseURL, api, models, isCatalog,
+        });
+        const detail = host.routeExists(route)
+            ? `${summaryLines.join('\n')}\n${t('provider-route-exists-warning')}`
+            : summaryLines.join('\n');
+        const confirmAnswer = await ask({
+            questions: [optionQuestion('confirm', t('provider-q-confirm'), [
+                    { label: t('provider-opt-confirm-write') },
+                    { label: t('provider-opt-confirm-cancel') },
+                ], { detail, hideCustomInput: true })],
+        });
+        if (answerSelected(confirmAnswer, 'confirm')[0] !== t('provider-opt-confirm-write')) {
+            notify(t('provider-cancelled'));
+            return 'cancelled';
+        }
+        // ── 8. persist: credential first (rollbackable), then the profile ──
+        let wroteCredential = false;
+        let previousCredential;
+        if (!shadowed) {
+            // Capture any pre-existing value BEFORE overwriting: when the profile
+            // write below fails, rollback must restore it — an unconditional unset
+            // would destroy the old key of the route being overwritten.
+            previousCredential = await host.readCredential(ref);
+            await host.writeCredential(ref, apiKey);
+            wroteCredential = true;
+        }
+        const profile = buildProfile({ isCatalog, ref, baseURL, api, models, discoveredById });
+        try {
+            await host.writeProfile(route, profile);
+        }
+        catch (error) {
+            if (wroteCredential) {
+                try {
+                    if (previousCredential !== undefined) {
+                        await host.writeCredential(ref, previousCredential);
+                    }
+                    else {
+                        await host.removeCredential(ref);
+                    }
+                    notify(t('provider-rollback-ok'));
+                }
+                catch {
+                    notify(t('provider-rollback-failed'), { color: 'warning' });
+                }
+            }
+            const err = error instanceof Error ? error.message : String(error);
+            notify(t('provider-write-failed', { err }), { color: 'error', timeoutMs: 8000 });
+            return 'failed';
+        }
+        // ── 9. success: transcript summary + optional live switch ──────────
+        pushLocal('/provider', [
+            ...summaryLines,
+            ...(deps.working() || models.length === 0
+                ? [t('provider-switch-hint')]
+                : []),
+        ]);
+        notify(t('provider-success', { route }), { color: 'success' });
+        if (!deps.working() && models.length > 0) {
+            const target = models[0];
+            const switchAnswer = await ask({
+                questions: [optionQuestion('switch', t('provider-q-switch'), [
+                        { label: t('provider-opt-switch-now', { model: target }) },
+                        { label: t('provider-opt-switch-keep') },
+                    ], { hideCustomInput: true })],
+            });
+            if (answerSelected(switchAnswer, 'switch')[0] === t('provider-opt-switch-now', { model: target })) {
+                await deps.switchModel(route, target);
+            }
+        }
+        return 'added';
+    }
+    catch (error) {
+        if (error instanceof UserQuestionError) {
+            notify(t('provider-cancelled'));
+            return 'cancelled';
+        }
+        const err = error instanceof Error ? error.message : String(error);
+        notify(t('provider-write-failed', { err }), { color: 'error', timeoutMs: 8000 });
+        return 'failed';
+    }
+}
+/** Prompt for a route id until it validates or the retry budget runs out. */
+async function promptRouteId(ask, notify) {
+    for (let attempt = 0; attempt < MAX_RETRY; attempt += 1) {
+        const answer = await ask({
+            questions: [textQuestion('route-id', t('provider-q-route-id'), t('provider-q-route-id-detail'))],
+        });
+        const route = answerText(answer, 'route-id');
+        if (PROVIDER_ROUTE_ID.test(route))
+            return route;
+        notify(t('provider-route-id-invalid'), { color: 'warning' });
+    }
+    return '';
+}
+/** Merge multi-select picks with comma/space-separated custom input, deduped. */
+function mergeModelIds(selected, custom) {
+    const ids = [...selected];
+    for (const piece of custom.split(/[,，\s]+/)) {
+        const id = piece.trim();
+        if (id !== '' && !ids.includes(id))
+            ids.push(id);
+    }
+    return ids;
+}
+function buildSummaryLines(input) {
+    const lines = [t('provider-line-route', { route: input.route })];
+    lines.push(input.shadowed
+        ? t('provider-line-keyref-env', { ref: input.ref })
+        : t('provider-line-keyref', { ref: input.ref }));
+    if (input.baseURL !== undefined && input.baseURL !== '') {
+        lines.push(t('provider-line-baseurl', { url: input.baseURL }));
+    }
+    if (input.api !== undefined)
+        lines.push(t('provider-line-protocol', { api: input.api }));
+    lines.push(input.models.length > 0
+        ? t('provider-line-models', { models: input.models.join(', ') })
+        : t('provider-line-models-catalog'));
+    return lines;
+}
+function buildProfile(input) {
+    const profile = { apiKeyEnv: input.ref };
+    if (input.baseURL !== undefined && input.baseURL !== '')
+        profile['baseURL'] = input.baseURL;
+    if (input.isCatalog) {
+        // `models` replaces the catalog when present; omit it to keep the whole
+        // catalog served.
+        if (input.models.length > 0) {
+            profile['models'] = input.models.map(id => ({ id }));
+        }
+        return profile;
+    }
+    profile['api'] = input.api;
+    profile['models'] = input.models.map(id => {
+        const discovered = input.discoveredById.get(id);
+        return {
+            id,
+            ...(discovered?.contextWindow !== undefined
+                ? { contextWindow: discovered.contextWindow }
+                : {}),
+            ...(discovered?.maxTokens !== undefined
+                ? { maxTokens: discovered.maxTokens }
+                : {}),
+        };
+    });
+    return profile;
+}

package/lib/types/{questions.d.ts → dsh-adapter/questions.d.ts}

@@ -74,12 +74,17 @@ export declare class QuestionStore {
     private rebuildSnapshot;
     /**
      * Provider entry point — called by `ctx.userQuestions.ask()` when the
-     * model runs the `ask_user_question` tool.
+     * model runs the `ask_user_question` tool, and by local wizards (e.g.
+     * `/provider`) driving the same panel.
      * @param request - The ask request: questions plus optional abort signal.
+     * @param options - `redact` hides answer text from the transcript summary
+     *   (use for batches that collect secrets such as API keys).
      * @returns A promise settling with the collected answers when the user
      *   submits the batch, or rejecting when the ask is interrupted.
      */
-    ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>;
+    ask(request: AskUserQuestionRequest, options?: {
+        redact?: boolean;
+    }): Promise<AskUserQuestionAnswer>;
     /** Advance to the next queued ask, if any. */
     private startNext;
     /**

package/lib/types/dsh-adapter/questions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"questions.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/questions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAEL,KAAK,qBAAqB,EAE1B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC5B,MAAM,iCAAiC,CAAA;AAExC;mEACmE;AACnE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAsBD,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAA;IACtC,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAClC;AAqCD;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAClD,OAAO,CAAC,QAAQ,CAAI;IACpB,yEAAyE;IACzE,OAAO,CAAC,SAAS,CAAwB;IACzC;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAgC;IAErD;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C;;;OAGG;IACH,WAAW,IAAI,gBAAgB,GAAG,IAAI;IAItC;;;OAGG;IACH,aAAa,IAAI,eAAe,EAAE;IAMlC,OAAO,CAAC,IAAI;IAIZ,sEAAsE;IACtE,OAAO,CAAC,eAAe;IAgBvB;;;;;;;;;OASG;IACH,GAAG,CAAC,OAAO,EAAE,sBAAsB,EAC/B,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA8BnE,8CAA8C;IAC9C,OAAO,CAAC,SAAS;IAOjB;;;;OAIG;IACH,aAAa,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAwBjD,6DAA6D;IAC7D,aAAa,IAAI,IAAI;IAUrB,+DAA+D;IAC/D,SAAS,IAAI,IAAI;IASjB,wEAAwE;IACxE,OAAO,CAAC,MAAM;IAOd,yEAAyE;IACzE,OAAO,CAAC,IAAI;CAMb"}

package/lib/types/{questions.js → dsh-adapter/questions.js}

@@ -11,7 +11,7 @@
  * arrive one at a time in practice (the tool blocks until answered), but
  * concurrent asks from subagents are drained FIFO.
  */
-import { t } from './i18n.js';
+import { t } from '../i18n.js';
 import { UserQuestionError, } from '@deepseek-ai/dsh-user-questions';
 const ASK_ABORTED = 'ASK_ABORTED';
 /**
@@ -30,10 +30,14 @@ function clip(text, max = 140) {
 function buildSummary(pending) {
     const lines = pending.answers.map(answer => {
         const question = pending.request.questions.find(q => q.id === answer.id);
-        const labels = answer.selected.join('、');
-        const text = answer.custom !== undefined && answer.custom !== ''
-            ? labels === '' ? answer.custom : `${labels}：${answer.custom}`
-            : labels;
+        const text = pending.redact
+            ? '••••••'
+            : (() => {
+                const labels = answer.selected.join('、');
+                return answer.custom !== undefined && answer.custom !== ''
+                    ? labels === '' ? answer.custom : `${labels}：${answer.custom}`
+                    : labels;
+            })();
         return `· ${question?.question ?? answer.id} → ${clip(text)}`;
     });
     const total = pending.request.questions.length;
@@ -109,18 +113,22 @@ export class QuestionStore {
     }
     /**
      * Provider entry point — called by `ctx.userQuestions.ask()` when the
-     * model runs the `ask_user_question` tool.
+     * model runs the `ask_user_question` tool, and by local wizards (e.g.
+     * `/provider`) driving the same panel.
      * @param request - The ask request: questions plus optional abort signal.
+     * @param options - `redact` hides answer text from the transcript summary
+     *   (use for batches that collect secrets such as API keys).
      * @returns A promise settling with the collected answers when the user
      *   submits the batch, or rejecting when the ask is interrupted.
      */
-    ask(request) {
+    ask(request, options) {
         return new Promise((resolve, reject) => {
             const pending = {
                 request,
                 batchId: ++this.batchSeq,
                 index: 0,
                 answers: [],
+                ...(options?.redact ? { redact: true } : {}),
                 resolve,
                 reject,
                 onAbort: () => {

package/lib/types/dsh-adapter/sideQuestion.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Side Question (`/btw`) — CC's btw.tsx/sideQuestion.ts semantics on the
+ * dsh call primitives: a single-turn, TOOL-LESS LLM call replaying the
+ * live session's derived history (prompt-cache reuse, compaction-style
+ * auxiliary call) plus one wrapped user message. The answer never enters
+ * the session log — it is pure UI state in the Chat screen.
+ *
+ * @module
+ */
+import { type StreamChunk } from '@deepseek-ai/dsh-llm';
+/**
+ * Wrap a side question with the single-response, no-tools contract (CC's
+ * wording): a lightweight instance sharing the conversation context, the
+ * main agent uninterrupted, no promises of action, no looking things up.
+ */
+export declare function wrapSideQuestion(question: string): string;
+/** Outcome of one side question: the visible text answer, or an error. */
+export interface SideQuestionOutcome {
+    answer: string | null;
+    error?: string;
+}
+/**
+ * Run one side-question call: stream the assembled options, fold chunks
+ * through the shared BlockAssembler, and surface the assembled text
+ * blocks as the answer. `onText` receives visible text deltas only
+ * (reasoning deltas are ignored — a side question wants the quick answer).
+ */
+export declare function runSideQuestion(params: {
+    /** `ctx.llm.stream` (bound); the options below pass through verbatim. */
+    stream: (options: object) => AsyncIterable<StreamChunk>;
+    /** Assembled GenerateOptions — no `tools` field, ever. */
+    options: object;
+    /** Streaming display hook (text deltas only). */
+    onText?: (delta: string) => void;
+    /** Cancellation: aborting yields `{answer: null}` with no error text. */
+    signal?: AbortSignal;
+}): Promise<SideQuestionOutcome>;
+//# sourceMappingURL=sideQuestion.d.ts.map

package/lib/types/dsh-adapter/sideQuestion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sideQuestion.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/sideQuestion.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAEvE;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAmBzD;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,yEAAyE;IACzE,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,aAAa,CAAC,WAAW,CAAC,CAAA;IACvD,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAA;IACf,iDAAiD;IACjD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,yEAAyE;IACzE,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAuB/B"}

package/lib/types/dsh-adapter/sideQuestion.js

@@ -0,0 +1,69 @@
+/**
+ * Side Question (`/btw`) — CC's btw.tsx/sideQuestion.ts semantics on the
+ * dsh call primitives: a single-turn, TOOL-LESS LLM call replaying the
+ * live session's derived history (prompt-cache reuse, compaction-style
+ * auxiliary call) plus one wrapped user message. The answer never enters
+ * the session log — it is pure UI state in the Chat screen.
+ *
+ * @module
+ */
+import { BlockAssembler } from '@deepseek-ai/dsh-llm';
+/**
+ * Wrap a side question with the single-response, no-tools contract (CC's
+ * wording): a lightweight instance sharing the conversation context, the
+ * main agent uninterrupted, no promises of action, no looking things up.
+ */
+export function wrapSideQuestion(question) {
+    return `<system-reminder>This is a side question from the user. You must answer this question directly in a single response.
+
+IMPORTANT CONTEXT:
+- You are a separate, lightweight agent spawned to answer this one question
+- The main agent is NOT interrupted - it continues working independently in the background
+- You share the conversation context but are a completely separate instance
+- Do NOT reference being interrupted or what you were "previously doing" - that framing is incorrect
+
+CRITICAL CONSTRAINTS:
+- You have NO tools available - you cannot read files, run commands, search, or take any actions
+- This is a one-off response - there will be no follow-up turns
+- You can ONLY provide information based on what you already know from the conversation context
+- NEVER say things like "Let me try...", "I'll now...", "Let me check...", or promise to take any action
+- If you don't know the answer, say so - do not offer to look it up or investigate
+
+Simply answer the question with the information you have.</system-reminder>
+
+${question}`;
+}
+/**
+ * Run one side-question call: stream the assembled options, fold chunks
+ * through the shared BlockAssembler, and surface the assembled text
+ * blocks as the answer. `onText` receives visible text deltas only
+ * (reasoning deltas are ignored — a side question wants the quick answer).
+ */
+export async function runSideQuestion(params) {
+    const { stream, options, onText, signal } = params;
+    const assembler = new BlockAssembler();
+    try {
+        for await (const chunk of stream(options)) {
+            assembler.push(chunk);
+            if (chunk.type === 'text-delta' && chunk.text)
+                onText?.(chunk.text);
+        }
+    }
+    catch (error) {
+        if (signal?.aborted)
+            return { answer: null };
+        return { answer: null, error: error instanceof Error ? error.message : String(error) };
+    }
+    const finish = assembler.finish;
+    if (finish.kind === 'error' || finish.kind === 'aborted') {
+        return { answer: null, error: finish.failure.message };
+    }
+    const answer = assembler.blocks()
+        .filter((block) => block.type === 'text')
+        .map(block => block.text)
+        .join('')
+        .trim();
+    if (answer === '')
+        return { answer: null, error: 'No response received' };
+    return { answer };
+}

package/lib/types/dsh-adapter/trajectory/aggregate.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Trajectory aggregate — the hotspot view's data and the session totals.
+ *
+ * The ledger answers "what happened, in order". This module answers the other
+ * question a long session raises: **where did the time go**. Chronological
+ * order is the worst order for that, so everything here is grouped and ranked
+ * instead: cost per tool, cost per model phase (decode vs. waiting for the
+ * first token vs. retry backoff), cost per turn.
+ *
+ * Three details make the numbers trustworthy rather than merely plausible:
+ *
+ * - **Own duration only.** A turn's cost is its own bracket, never the sum of
+ *   its children — summing both would double-count every tool inside it.
+ * - **No fabricated spans.** A step that produced no `assistant/chunk` (the
+ *   request failed, or the log predates chunk capture) contributes no TTFT and
+ *   no decode sample rather than a zero that would drag the average down.
+ * - **Bursts expand.** A folded run is one ledger row but N calls; the counts
+ *   and totals here are over calls, so `count` matches what actually ran.
+ */
+import type { HotspotRow, HotspotSort, TrajAggregate, TrajNode } from './types.js';
+import type { TrajBuild } from './projection.js';
+/**
+ * Visit every logical call in ledger order, expanding burst rows.
+ *
+ * @param nodes - The folded ledger.
+ * @param visit - Receives each call node plus the ledger index of the row it
+ *   is displayed under (the burst row's index, for folded members).
+ */
+export declare function forEachCall(nodes: readonly TrajNode[], visit: (node: TrajNode, ledgerIndex: number) => void): void;
+/**
+ * Rank hotspot rows by the active sort key.
+ *
+ * Ties break on label so the order is total — an unstable order would make
+ * rows jump between frames while the session streams.
+ */
+export declare function sortRows(rows: readonly HotspotRow[], sort: HotspotSort): HotspotRow[];
+/**
+ * Derive the hotspot groups and session totals from a projection.
+ *
+ * @param build - The current projection.
+ * @param sort - Ranking key for the tool and turn groups.
+ * @returns Ranked groups plus the counters the scene header and status badge
+ *   read. Pure: nothing here mutates the build.
+ */
+export declare function aggregate(build: TrajBuild, sort?: HotspotSort): TrajAggregate;
+//# sourceMappingURL=aggregate.d.ts.map

package/lib/types/dsh-adapter/trajectory/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/trajectory/aggregate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAA0B,MAAM,YAAY,CAAA;AAC1G,OAAO,KAAK,EAAc,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAK5D;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,KAAK,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,GACnD,IAAI,CASN;AAqCD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE,CAIrF;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,GAAE,WAAwB,GAAG,aAAa,CAuGzF"}