@askdkc/dsh-cli 0.11.3

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

@@ -0,0 +1,51 @@
+/**
+ * User-question answerer compatibility.
+ *
+ * Legacy rc.2 exposes one global `registerProvider` seat. The 0.1.2 line removed that
+ * API in favour of a scope-aware `user-questions/request` waterfall. Keep the
+ * capability probe and both registration paths here so the TUI bootstrap only
+ * consumes a small prepared-registration result.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AskUserQuestionAnswer, AskUserQuestionRequest } from '@deepseek-ai/dsh-user-questions';
+import { type QuestionProviderYieldDecision } from './providerGuard.js';
+export interface QuestionAnswerer {
+    ask(request: AskUserQuestionRequest, options?: {
+        redact?: boolean;
+    }): Promise<AskUserQuestionAnswer>;
+}
+export type PreparedQuestionAnswerer = {
+    readonly kind: 'legacy';
+    /** Present only when another component already owns the provider seat. */
+    readonly yieldDecision?: QuestionProviderYieldDecision;
+} | {
+    readonly kind: 'waterfall';
+    /** Bind ownership after the mutable channel has been created. */
+    register(owner: {
+        readonly agentId: string;
+    }): () => void;
+};
+/**
+ * Prepare the answerer against whichever upstream API the active package
+ * exposes. The legacy path registers immediately and binds the returned
+ * disposer to this TUI fiber. The waterfall path returns a late binder because
+ * channel.agentId changes across `/new`, `/resume`, and rewind.
+ *
+ * Agentless waterfall requests are claimed deliberately: dsh-auth's `/auth`
+ * wizard asks through the same service without an agent. Foreign-agent
+ * requests continue to the next answerer.
+ *
+ * Security scope (#586): the provider-seat guard (DUPLICATE_PROVIDER probe +
+ * private symbol check) exists ONLY on the legacy path. The waterfall has no
+ * seat. Agent-bearing requests are scope-filtered; agentless requests such as
+ * dsh-auth `/auth` are dispatched without a scope carrier. Under the answerer
+ * contract, the first eligible listener that returns instead of delegating
+ * with `next()` claims the request. Cordis waterfall is around middleware,
+ * however: an outer listener can call `next()` and then observe, replace, or
+ * reject the downstream result, while `{ prepend: true }` inserts a listener
+ * at the front. Upstream exposes no supported way to discover or reserve an
+ * exclusive claimant, so the legacy guard and its warning cannot be
+ * reproduced here.
+ */
+export declare function prepareQuestionAnswerer(ctx: Context, service: unknown, answerer: QuestionAnswerer): PreparedQuestionAnswerer;
+//# sourceMappingURL=questions-answerer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"questions-answerer.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/questions-answerer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,iCAAiC,CAAA;AACxC,OAAO,EAIL,KAAK,6BAA6B,EACnC,MAAM,oBAAoB,CAAA;AAE3B,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,OAAO,EAAE,sBAAsB,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAA;CACrG;AAoBD,MAAM,MAAM,wBAAwB,GAChC;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,CAAC,EAAE,6BAA6B,CAAA;CACvD,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,IAAI,CAAA;CAC1D,CAAA;AAML;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,gBAAgB,GACzB,wBAAwB,CA2B1B"}

package/lib/types/dsh-adapter/questions-answerer.js

@@ -0,0 +1,64 @@
+/**
+ * User-question answerer compatibility.
+ *
+ * Legacy rc.2 exposes one global `registerProvider` seat. The 0.1.2 line removed that
+ * API in favour of a scope-aware `user-questions/request` waterfall. Keep the
+ * capability probe and both registration paths here so the TUI bootstrap only
+ * consumes a small prepared-registration result.
+ */
+import { decideQuestionProviderYield, incumbentQuestionProviderId, tagTuiQuestionProvider, } from './providerGuard.js';
+function secretRequest(request) {
+    return request.questions.some(question => question.id === 'dsh-auth-secret');
+}
+function hasLegacyProvider(service) {
+    return typeof service.registerProvider === 'function';
+}
+/**
+ * Prepare the answerer against whichever upstream API the active package
+ * exposes. The legacy path registers immediately and binds the returned
+ * disposer to this TUI fiber. The waterfall path returns a late binder because
+ * channel.agentId changes across `/new`, `/resume`, and rewind.
+ *
+ * Agentless waterfall requests are claimed deliberately: dsh-auth's `/auth`
+ * wizard asks through the same service without an agent. Foreign-agent
+ * requests continue to the next answerer.
+ *
+ * Security scope (#586): the provider-seat guard (DUPLICATE_PROVIDER probe +
+ * private symbol check) exists ONLY on the legacy path. The waterfall has no
+ * seat. Agent-bearing requests are scope-filtered; agentless requests such as
+ * dsh-auth `/auth` are dispatched without a scope carrier. Under the answerer
+ * contract, the first eligible listener that returns instead of delegating
+ * with `next()` claims the request. Cordis waterfall is around middleware,
+ * however: an outer listener can call `next()` and then observe, replace, or
+ * reject the downstream result, while `{ prepend: true }` inserts a listener
+ * at the front. Upstream exposes no supported way to discover or reserve an
+ * exclusive claimant, so the legacy guard and its warning cannot be
+ * reproduced here.
+ */
+export function prepareQuestionAnswerer(ctx, service, answerer) {
+    if (!hasLegacyProvider(service)) {
+        const events = ctx;
+        return {
+            kind: 'waterfall',
+            register: owner => events.on('user-questions/request', (request, next) => {
+                if (request.agent !== undefined && String(request.agent.id) !== owner.agentId)
+                    return next();
+                return answerer.ask(request, { redact: secretRequest(request) });
+            }),
+        };
+    }
+    const provider = { ask: request => answerer.ask(request, { redact: secretRequest(request) }) };
+    tagTuiQuestionProvider(provider);
+    try {
+        ctx.effect(() => service.registerProvider(provider), 'dsh-tui.questions.legacy-provider');
+        return { kind: 'legacy' };
+    }
+    catch (error) {
+        if (error.code !== 'DUPLICATE_PROVIDER')
+            throw error;
+        return {
+            kind: 'legacy',
+            yieldDecision: decideQuestionProviderYield(incumbentQuestionProviderId(service)),
+        };
+    }
+}

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

@@ -0,0 +1,130 @@
+/**
+ * Ask-user-question store — the UI-side half of the DSH user-interaction
+ * seam (`ctx.userQuestions`). The harness's model-facing
+ * `ask_user_question` tool calls `UserQuestionService.ask()`, which
+ * forwards to the provider registered here; this store parks the request,
+ * surfaces one question at a time to the TUI questionnaire, and settles the
+ * harness promise when the user answers,
+ * cancels, or the owning tool's abort signal fires.
+ *
+ * Queue semantics mirror the official dsh-tui chat/questions machine: asks
+ * arrive one at a time in practice (the tool blocks until answered), but
+ * concurrent asks from subagents are drained FIFO.
+ */
+import { compositionRoot } from './host-access.js';
+import { type AdapterRuntimeOptions } from '../adapter/kernel/runtime.js';
+import { type AskUserQuestionAnswer, type AskUserQuestionItem, type AskUserQuestionRequest } from '@deepseek-ai/dsh-user-questions';
+/** One answered question as the panel submits it: selected option labels
+ *  plus optional free-text (the dsh protocol's "Other" answer). */
+export interface QuestionSelection {
+    readonly selected: string[];
+    readonly custom?: string;
+}
+/**
+ * In-progress answer state kept while navigating between questions. Drafts
+ * are deliberately separate from committed answers: leaving a question
+ * should preserve what the user typed without making it count as answered.
+ */
+export type QuestionDraft = QuestionSelection;
+/** What the TUI renders while a question is pending. */
+export interface QuestionSnapshot {
+    /** Stable key so the panel remounts (fresh selection state) per question. */
+    readonly key: string;
+    readonly question: AskUserQuestionItem;
+    /** 1-based position within the batch. */
+    readonly position: number;
+    /** Total questions in the batch. */
+    readonly total: number;
+    /** Questions answered before the current one. */
+    readonly answered: number;
+    /** Previously saved answer or draft for the current question. */
+    readonly draft?: QuestionDraft;
+    /** Whether Esc should navigate to the previous question. */
+    readonly canGoBack: boolean;
+}
+/** Completed batch summary, pushed into the transcript by the caller. */
+export interface QuestionSummary {
+    readonly title: string;
+    readonly lines: readonly string[];
+}
+/** Host-only registration used by the TUI plugin bootstrap. */
+export declare function bindQuestionStore(ctx: Parameters<typeof compositionRoot>[0], store: QuestionStore): void;
+/** Host-only lookup used by the presentation Port bridge. */
+export declare function getQuestionStore(ctx: Parameters<typeof compositionRoot>[0]): QuestionStore | undefined;
+/**
+ * Ask-user-question store: parks asks from the harness's user-interaction
+ * seam, surfaces one question at a time to the TUI, and settles each ask
+ * when the user answers or the batch is interrupted. The TUI subscribes for
+ * re-renders and answers via {@link QuestionStore.answerCurrent}.
+ */
+export declare class QuestionStore {
+    private readonly runtime;
+    constructor(runtime?: AdapterRuntimeOptions);
+    private readonly queue;
+    private active;
+    private readonly listeners;
+    private batchSeq;
+    /** Completed batch summaries, drained by the TUI into the transcript. */
+    private summaries;
+    /**
+     * Cached snapshot: useSyncExternalStore requires a stable reference while
+     * nothing changed (a fresh object per call would loop re-renders).
+     */
+    private snapshotCache;
+    /**
+     * Subscribe to store changes (useSyncExternalStore contract).
+     * @param listener - Called after every mutation that changes the snapshot.
+     * @returns An unsubscribe function removing the listener.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * The question the TUI should render now, or null when idle.
+     * @returns The cached snapshot; the reference is stable between mutations.
+     */
+    getSnapshot(): QuestionSnapshot | null;
+    /**
+     * Take (and clear) every completed batch summary for the transcript.
+     * @returns The summaries collected since the last take.
+     */
+    takeSummaries(): QuestionSummary[];
+    private emit;
+    /** Rebuild the cached snapshot after any mutation of active/index. */
+    private rebuildSnapshot;
+    /**
+     * Provider entry point — called by `ctx.userQuestions.ask()` when the
+     * 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, options?: {
+        redact?: boolean;
+    }): Promise<AskUserQuestionAnswer>;
+    /** Advance to the next queued ask, if any. */
+    private startNext;
+    /**
+     * The user submitted an answer for the current question; replaces any
+     * previous answer at that position, advances the batch, and settles it once
+     * every question is answered.
+     * @param selection - Selected option labels plus optional custom text.
+     */
+    answerCurrent(selection: QuestionSelection): void;
+    /**
+     * Navigate to the previous question without cancelling the batch. The
+     * caller supplies the panel's current draft so partially typed text can be
+     * restored when the user returns.
+     */
+    backCurrent(draft?: QuestionDraft): void;
+    /** The user interrupted the questionnaire (Esc / Ctrl+C). */
+    cancelCurrent(): void;
+    /** Reject the active and all queued asks (plugin teardown). */
+    rejectAll(): void;
+    /** User-initiated cancel — the asker learns the user wants to speak. */
+    private cancel;
+    /** Harness-side interruption — abort signal fired or plugin teardown. */
+    private fail;
+}
+//# sourceMappingURL=questions.d.ts.map

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":"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"}

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

@@ -0,0 +1,282 @@
+/**
+ * Ask-user-question store — the UI-side half of the DSH user-interaction
+ * seam (`ctx.userQuestions`). The harness's model-facing
+ * `ask_user_question` tool calls `UserQuestionService.ask()`, which
+ * forwards to the provider registered here; this store parks the request,
+ * surfaces one question at a time to the TUI questionnaire, and settles the
+ * harness promise when the user answers,
+ * cancels, or the owning tool's abort signal fires.
+ *
+ * Queue semantics mirror the official dsh-tui chat/questions machine: asks
+ * 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 { compositionRoot } from './host-access.js';
+import { assertCapabilityShadowPolicy, defaultAdapterRuntime, } from '../adapter/kernel/runtime.js';
+import { UserQuestionError, } from '@deepseek-ai/dsh-user-questions';
+const questionStores = new WeakMap();
+/** Host-only registration used by the TUI plugin bootstrap. */
+export function bindQuestionStore(ctx, store) {
+    const root = compositionRoot(ctx);
+    questionStores.set(root, store);
+}
+/** Host-only lookup used by the presentation Port bridge. */
+export function getQuestionStore(ctx) {
+    const root = compositionRoot(ctx);
+    return questionStores.get(root);
+}
+const ASK_ABORTED = 'ASK_ABORTED';
+/**
+ * User-initiated cancel (Esc / Ctrl+C in the panel). dsh-plan-mode keys on
+ * this code to report "the user dismissed the plan review to speak instead"
+ * rather than the generic abort message, so user cancels must be told apart
+ * from harness aborts (signal fired) and teardown rejects.
+ */
+const ASK_CANCELLED = 'ASK_CANCELLED';
+/** Truncate a long answer line for the transcript summary. */
+function clip(text, max = 140) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max)}…`;
+}
+function isDefined(value) {
+    return value !== undefined;
+}
+function copyDraft(draft) {
+    return {
+        selected: [...draft.selected],
+        ...(draft.custom !== undefined ? { custom: draft.custom } : {}),
+    };
+}
+function selectionFromAnswer(answer) {
+    return copyDraft(answer);
+}
+function buildSummary(pending) {
+    const lines = pending.request.questions.flatMap((question, index) => {
+        const answer = pending.answers[index];
+        if (answer === undefined)
+            return [];
+        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} → ${clip(text)}`;
+    });
+    const total = pending.request.questions.length;
+    return {
+        title: t('questionnaire-answered', { total }),
+        lines,
+    };
+}
+/**
+ * Ask-user-question store: parks asks from the harness's user-interaction
+ * seam, surfaces one question at a time to the TUI, and settles each ask
+ * when the user answers or the batch is interrupted. The TUI subscribes for
+ * re-renders and answers via {@link QuestionStore.answerCurrent}.
+ */
+export class QuestionStore {
+    runtime;
+    constructor(runtime = defaultAdapterRuntime()) {
+        this.runtime = runtime;
+    }
+    queue = [];
+    active;
+    listeners = new Set();
+    batchSeq = 0;
+    /** Completed batch summaries, drained by the TUI into the transcript. */
+    summaries = [];
+    /**
+     * Cached snapshot: useSyncExternalStore requires a stable reference while
+     * nothing changed (a fresh object per call would loop re-renders).
+     */
+    snapshotCache = null;
+    /**
+     * Subscribe to store changes (useSyncExternalStore contract).
+     * @param listener - Called after every mutation that changes the snapshot.
+     * @returns An unsubscribe function removing the listener.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * The question the TUI should render now, or null when idle.
+     * @returns The cached snapshot; the reference is stable between mutations.
+     */
+    getSnapshot() {
+        return this.snapshotCache;
+    }
+    /**
+     * Take (and clear) every completed batch summary for the transcript.
+     * @returns The summaries collected since the last take.
+     */
+    takeSummaries() {
+        const summaries = this.summaries;
+        this.summaries = [];
+        return summaries;
+    }
+    emit() {
+        for (const listener of this.listeners)
+            listener();
+    }
+    /** Rebuild the cached snapshot after any mutation of active/index. */
+    rebuildSnapshot() {
+        const pending = this.active;
+        if (pending === undefined) {
+            this.snapshotCache = null;
+            return;
+        }
+        const question = pending.request.questions[pending.index];
+        const savedDraft = pending.drafts[pending.index];
+        const savedAnswer = pending.answers[pending.index];
+        this.snapshotCache = question === undefined ? null : {
+            key: `${pending.batchId}-${pending.index}`,
+            question,
+            position: pending.index + 1,
+            total: pending.request.questions.length,
+            answered: pending.index,
+            ...(savedDraft !== undefined
+                ? { draft: savedDraft }
+                : savedAnswer !== undefined
+                    ? { draft: selectionFromAnswer(savedAnswer) }
+                    : {}),
+            canGoBack: pending.index > 0,
+        };
+    }
+    /**
+     * Provider entry point — called by `ctx.userQuestions.ask()` when the
+     * 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, options) {
+        assertCapabilityShadowPolicy('host.presentation.ask', this.runtime.mode, this.runtime.slices);
+        return new Promise((resolve, reject) => {
+            const pending = {
+                request,
+                batchId: ++this.batchSeq,
+                index: 0,
+                answers: new Array(request.questions.length),
+                drafts: new Array(request.questions.length),
+                ...(options?.redact ? { redact: true } : {}),
+                resolve,
+                reject,
+                onAbort: () => {
+                    if (this.active === pending) {
+                        this.active = undefined;
+                        this.rebuildSnapshot();
+                        this.fail(pending);
+                        this.startNext();
+                        this.emit();
+                        return;
+                    }
+                    const at = this.queue.indexOf(pending);
+                    if (at >= 0)
+                        this.queue.splice(at, 1);
+                    this.fail(pending);
+                },
+            };
+            request.signal?.addEventListener('abort', pending.onAbort, { once: true });
+            this.queue.push(pending);
+            this.startNext();
+        });
+    }
+    /** Advance to the next queued ask, if any. */
+    startNext() {
+        if (this.active !== undefined || this.queue.length === 0)
+            return;
+        this.active = this.queue.shift();
+        this.rebuildSnapshot();
+        this.emit();
+    }
+    /**
+     * The user submitted an answer for the current question; replaces any
+     * previous answer at that position, advances the batch, and settles it once
+     * every question is answered.
+     * @param selection - Selected option labels plus optional custom text.
+     */
+    answerCurrent(selection) {
+        const pending = this.active;
+        const question = pending?.request.questions[pending.index];
+        if (pending === undefined || question === undefined)
+            return;
+        const answer = {
+            id: question.id,
+            selected: [...selection.selected],
+            ...(selection.custom !== undefined && selection.custom !== ''
+                ? { custom: selection.custom }
+                : {}),
+        };
+        pending.answers[pending.index] = answer;
+        pending.drafts[pending.index] = copyDraft(selection);
+        pending.index += 1;
+        if (pending.index >= pending.request.questions.length) {
+            // Batch complete: settle the harness promise, remember a transcript
+            // summary, and drain the next queued ask if any.
+            const answers = pending.answers.filter(isDefined);
+            this.active = undefined;
+            pending.resolve({ answers });
+            this.summaries.push(buildSummary(pending));
+            this.startNext();
+        }
+        this.rebuildSnapshot();
+        this.emit();
+    }
+    /**
+     * Navigate to the previous question without cancelling the batch. The
+     * caller supplies the panel's current draft so partially typed text can be
+     * restored when the user returns.
+     */
+    backCurrent(draft) {
+        const pending = this.active;
+        if (pending === undefined || pending.index <= 0)
+            return;
+        if (draft !== undefined) {
+            pending.drafts[pending.index] = copyDraft(draft);
+        }
+        pending.index -= 1;
+        this.rebuildSnapshot();
+        this.emit();
+    }
+    /** The user interrupted the questionnaire (Esc / Ctrl+C). */
+    cancelCurrent() {
+        const pending = this.active;
+        if (pending === undefined)
+            return;
+        this.active = undefined;
+        this.rebuildSnapshot();
+        this.cancel(pending);
+        this.startNext();
+        this.emit();
+    }
+    /** Reject the active and all queued asks (plugin teardown). */
+    rejectAll() {
+        const active = this.active;
+        this.active = undefined;
+        this.rebuildSnapshot();
+        if (active !== undefined)
+            this.fail(active);
+        for (const pending of this.queue.splice(0))
+            this.fail(pending);
+        this.emit();
+    }
+    /** User-initiated cancel — the asker learns the user wants to speak. */
+    cancel(pending) {
+        pending.reject(new UserQuestionError('the user cancelled ask_user_question', ASK_CANCELLED));
+    }
+    /** Harness-side interruption — abort signal fired or plugin teardown. */
+    fail(pending) {
+        pending.reject(new UserQuestionError('ask_user_question was interrupted before the user answered', ASK_ABORTED));
+    }
+}

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

@@ -0,0 +1,41 @@
+export type { RecapOutcome } from '../adapter/ports/channel-catalog.js';
+/**
+ * Session recap (`/recap`, pi-recap semantics): a single TOOL-LESS LLM
+ * call that summarizes the session's RECENT activity into one line and
+ * proposes a short title. Unlike `/btw` it does not replay the full
+ * derived history — the recent-activity excerpt below IS the payload, so
+ * the call stays cheap and the recap is about the tail of the session,
+ * which is exactly what a glance at a resumed/unknown session needs.
+ *
+ * The answer never enters the session log — it is pure UI state (the
+ * RecapPanel in the Chat screen); applying the proposed title goes
+ * through the normal `/rename` path (channel.renameSession).
+ *
+ * @module
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** Max chars of recent activity fed to the recap call. */
+export declare const RECAP_RECENT_CHARS = 6000;
+/**
+ * Collect the most recent user/assistant exchanges from a session event
+ * log as plain `role: text` lines, capped to the tail turns and a char
+ * budget. Rows derived from the log (tool cards, notices) are skipped —
+ * the recap wants the conversation, not the chrome.
+ */
+export declare function collectRecentActivity(events: readonly SessionEvent[], limitChars: number): string;
+/**
+ * Wrap the recent-activity excerpt with the single-response, JSON-only
+ * recap contract. The model answers with a title + one-line summary in
+ * the language of the activity (matching the user's own words).
+ */
+export declare function wrapRecapPrompt(activity: string): string;
+/**
+ * Parse the model's recap response: extract the JSON object (tolerating
+ * stray prose around it); on failure the whole text becomes the summary
+ * and no title is proposed.
+ */
+export declare function parseRecapResponse(raw: string): {
+    summary: string;
+    title?: string;
+};
+//# sourceMappingURL=recap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recap.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/recap.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AACvE;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAE5D,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB,OAAO,CAAA;AAkBtC;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAkCjG;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUxD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAyBnF"}