ftown-bridge 0.19.67 → 0.20.0

package/dist/ask-question-hook.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Claude Code PreToolUse hook for AskUserQuestion (`ftown-harness ask-hook`).
+ * Records the question with the bridge, blocks until the human answers in the
+ * dashboard, then returns the answer so Claude Code skips the terminal picker.
+ *
+ * Installed globally, so it runs for every Claude Code session on the machine:
+ * outside ftown sessions it must exit immediately and silently. It always exits
+ * 0 and writes to stdout only when it has an answer; any other outcome lets the
+ * normal terminal picker run.
+ */
+import { type AttentionAnswerEntry } from './attention-prompt-protocol.js';
+export interface AskUserQuestionHookOutput {
+    hookSpecificOutput: {
+        hookEventName: 'PreToolUse';
+        permissionDecision: 'allow';
+        updatedInput: Record<string, unknown> & {
+            answers: Record<string, string>;
+        };
+    };
+}
+/**
+ * Claude Code's documented updatedInput for AskUserQuestion: the full original
+ * tool input plus `answers` keyed by the exact question text. Returns undefined
+ * when the answers do not line up with the original questions.
+ */
+export declare function buildAskUserQuestionHookOutput(toolInput: Record<string, unknown>, answers: AttentionAnswerEntry[]): AskUserQuestionHookOutput | undefined;
+export interface AskHookResponse {
+    status: number;
+    body: unknown;
+}
+export interface AskHookDeps {
+    readStdin: () => Promise<string>;
+    env: Record<string, string | undefined>;
+    /** Local bridge API. Rejects when the bridge is unreachable. */
+    request: (method: 'GET' | 'POST', path: string, body?: unknown, signal?: AbortSignal) => Promise<AskHookResponse>;
+    now: () => number;
+    sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+    writeStdout: (text: string) => void;
+    writeStderr: (text: string) => void;
+    signal?: AbortSignal;
+    deadlineMs?: number;
+}
+/** Always resolves 0. Writes stdout only when there is an answer to hand back. */
+export declare function runAskHook(deps: AskHookDeps): Promise<0>;
+/** Wires real stdin/stdout, the bridge local API (same pointer + auth as the other harness commands) and signals. */
+export declare function runAskHookCli(): Promise<number>;

package/dist/ask-question-hook.js

@@ -0,0 +1,192 @@
+/**
+ * Claude Code PreToolUse hook for AskUserQuestion (`ftown-harness ask-hook`).
+ * Records the question with the bridge, blocks until the human answers in the
+ * dashboard, then returns the answer so Claude Code skips the terminal picker.
+ *
+ * Installed globally, so it runs for every Claude Code session on the machine:
+ * outside ftown sessions it must exit immediately and silently. It always exits
+ * 0 and writes to stdout only when it has an answer; any other outcome lets the
+ * normal terminal picker run.
+ */
+import { ASK_HOOK_DEADLINE_MS, ATTENTION_ITEM_WAIT_MAX_SECONDS, } from './attention-prompt-protocol.js';
+import { apiResponse, loadPointer } from './cli-client.js';
+const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+const RETRY_DELAY_MS = 2_000;
+const OUTAGE_LIMIT_MS = 60_000;
+const STDIN_TIMEOUT_MS = 10_000;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Claude Code's documented updatedInput for AskUserQuestion: the full original
+ * tool input plus `answers` keyed by the exact question text. Returns undefined
+ * when the answers do not line up with the original questions.
+ */
+export function buildAskUserQuestionHookOutput(toolInput, answers) {
+    const questions = toolInput.questions;
+    if (!Array.isArray(questions) || questions.length !== answers.length)
+        return undefined;
+    // Claude Code keys answers by question text, so duplicate question texts collide (last one wins).
+    const byQuestion = {};
+    for (let i = 0; i < questions.length; i += 1) {
+        const question = questions[i];
+        const entry = answers[i];
+        if (!isRecord(question) || typeof question.question !== 'string' || !entry || !Array.isArray(entry.selected))
+            return undefined;
+        const options = Array.isArray(question.options) ? question.options : [];
+        const parts = [];
+        for (const index of entry.selected) {
+            const option = Number.isInteger(index) ? options[index] : undefined;
+            if (!isRecord(option) || typeof option.label !== 'string')
+                return undefined;
+            parts.push(option.label);
+        }
+        if (typeof entry.text === 'string' && entry.text.length > 0)
+            parts.push(entry.text);
+        byQuestion[question.question] = parts.join(', ');
+    }
+    return {
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'allow',
+            updatedInput: { ...toolInput, answers: byQuestion },
+        },
+    };
+}
+function ok(response) {
+    return response.status >= 200 && response.status < 300;
+}
+/** Always resolves 0. Writes stdout only when there is an answer to hand back. */
+export async function runAskHook(deps) {
+    const { signal } = deps;
+    const aborted = () => signal?.aborted === true;
+    try {
+        const sessionId = deps.env.FTOWN_SESSION_ID;
+        if (!sessionId || !SESSION_ID_PATTERN.test(sessionId))
+            return 0;
+        const input = JSON.parse(await deps.readStdin());
+        if (!isRecord(input) || input.tool_name !== 'AskUserQuestion' || !isRecord(input.tool_input) || typeof input.tool_use_id !== 'string')
+            return 0;
+        const toolInput = input.tool_input;
+        if (aborted())
+            return 0;
+        const base = `/api/sessions/${sessionId}`;
+        const session = await deps.request('GET', base, undefined, signal);
+        if (!ok(session) || !isRecord(session.body))
+            return 0;
+        const capabilities = session.body.capabilities;
+        const attention = isRecord(capabilities) ? capabilities.attention : undefined;
+        if (!isRecord(attention) || attention.prompt !== true)
+            return 0;
+        const askBody = { toolName: 'AskUserQuestion', toolUseId: input.tool_use_id, toolInput };
+        let asked;
+        try {
+            asked = await deps.request('POST', `${base}/attention/ask`, askBody, signal);
+        }
+        catch {
+            if (aborted())
+                return 0;
+            // Transport failure: retry once. Safe because the store dedups unresolved items by tool_use_id.
+            await deps.sleep(RETRY_DELAY_MS, signal);
+            if (aborted())
+                return 0;
+            asked = await deps.request('POST', `${base}/attention/ask`, askBody, signal);
+        }
+        if (!ok(asked) || !isRecord(asked.body) || !isRecord(asked.body.event) || typeof asked.body.event.id !== 'string')
+            return 0;
+        const itemPath = `${base}/attention/${encodeURIComponent(asked.body.event.id)}`;
+        const deadlineAt = deps.now() + (deps.deadlineMs ?? ASK_HOOK_DEADLINE_MS);
+        let lastSuccess = deps.now();
+        while (!aborted()) {
+            const remaining = deadlineAt - deps.now();
+            if (remaining <= 0)
+                return 0;
+            const waitSeconds = Math.max(1, Math.min(ATTENTION_ITEM_WAIT_MAX_SECONDS, Math.ceil(remaining / 1000)));
+            let response;
+            try {
+                response = await deps.request('GET', `${itemPath}?waitSeconds=${waitSeconds}`, undefined, signal);
+            }
+            catch {
+                if (aborted())
+                    return 0;
+            }
+            if (response && response.status === 404)
+                return 0;
+            if (response && ok(response) && isRecord(response.body) && isRecord(response.body.event)) {
+                lastSuccess = deps.now();
+                const item = response.body.event;
+                if (item.resolution === 'answered' && isRecord(item.answer) && Array.isArray(item.answer.answers)) {
+                    const output = buildAskUserQuestionHookOutput(toolInput, item.answer.answers);
+                    if (output && !aborted())
+                        deps.writeStdout(JSON.stringify(output));
+                    return 0;
+                }
+                if (item.resolution !== undefined || item.resolvedAt !== undefined)
+                    return 0;
+                continue;
+            }
+            if (deps.now() - lastSuccess > OUTAGE_LIMIT_MS)
+                return 0;
+            await deps.sleep(RETRY_DELAY_MS, signal);
+        }
+        return 0;
+    }
+    catch (error) {
+        if (!aborted())
+            deps.writeStderr(`ftown ask-hook: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 0;
+    }
+}
+async function readStdinText() {
+    if (process.stdin.isTTY)
+        return '';
+    const chunks = [];
+    const killer = setTimeout(() => { process.stdin.destroy(); }, STDIN_TIMEOUT_MS);
+    killer.unref();
+    try {
+        for await (const chunk of process.stdin)
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    finally {
+        clearTimeout(killer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function abortableSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const done = () => { clearTimeout(timer); signal?.removeEventListener('abort', done); resolve(); };
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener('abort', done, { once: true });
+    });
+}
+/** Wires real stdin/stdout, the bridge local API (same pointer + auth as the other harness commands) and signals. */
+export async function runAskHookCli() {
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    try {
+        return await runAskHook({
+            readStdin: readStdinText,
+            env: process.env,
+            request: async (method, path, body, requestSignal) => {
+                const result = await apiResponse(loadPointer(), method, path, body, undefined, requestSignal);
+                return { status: result.status, body: result.body };
+            },
+            now: () => Date.now(),
+            sleep: abortableSleep,
+            writeStdout: (text) => { process.stdout.write(text); },
+            writeStderr: (text) => { process.stderr.write(text); },
+            signal: controller.signal,
+        });
+    }
+    finally {
+        process.off('SIGINT', stop);
+        process.off('SIGTERM', stop);
+    }
+}
+//# sourceMappingURL=ask-question-hook.js.map

package/dist/ask-question-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-question-hook.js","sourceRoot":"","sources":["../src/ask-question-hook.ts"],"names":[],"mappings":"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"}

package/dist/attention-events.d.ts

@@ -1,5 +1,7 @@
+import { z } from 'zod';
+import { type AttentionAnswer, type AttentionPrompt } from './attention-prompt-protocol.js';
 export type AttentionType = 'permission_prompt' | 'elicitation_dialog' | 'agent_needs_input' | 'ask_user';
-export type Resolution = 'manual' | 'user_prompt' | 'elicitation_complete' | 'session_end';
+export type Resolution = 'manual' | 'user_prompt' | 'elicitation_complete' | 'session_end' | 'answered' | 'tool_complete';
 export interface Activity {
     state: 'thinking' | 'tool_use' | 'idle' | 'unknown';
     lastActivityAt?: string;
@@ -16,6 +18,8 @@ export interface AttentionItem {
     acknowledgedAt?: string;
     resolvedAt?: string;
     resolution?: Resolution;
+    prompt?: AttentionPrompt;
+    answer?: AttentionAnswer;
 }
 export interface AttentionObservation {
     activity?: Activity['state'];
@@ -24,9 +28,41 @@ export interface AttentionObservation {
         title: string;
         message: string;
         sourceId?: string;
+        prompt?: AttentionPrompt;
     };
-    resolve?: Exclude<Resolution, 'manual'>;
+    resolve?: Exclude<Resolution, 'manual' | 'answered' | 'tool_complete'>;
+    /** Raw tool_use_id of an ask tool that finished; resolves the matching ask_user item. */
+    toolComplete?: string;
 }
+export declare const promptSchema: z.ZodObject<{
+    channel: z.ZodEnum<{
+        mail: "mail";
+        hook: "hook";
+    }>;
+    questions: z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        header: z.ZodOptional<z.ZodString>;
+        options: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        multiSelect: z.ZodBoolean;
+        allowText: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Secret redaction only (no cleaning, truncation or excerpting). */
+export declare function redactAttentionSecrets(value: string): string;
+/**
+ * Redacts every prompt string, then re-checks limits, unique labels and the free-text rule.
+ * Never throws; the error names what to fix.
+ */
+export declare function normalizeAttentionPrompt(input: unknown): {
+    ok: true;
+    value: AttentionPrompt;
+} | {
+    ok: false;
+    error: string;
+};
 /** Only the selected human-facing excerpt crosses the API; never the hook payload. */
 export declare function sanitizeAttentionText(value: string, maxLength: number): string;
 export declare function classifyAttentionHook(eventName: string, data: Record<string, unknown>): AttentionObservation;

package/dist/attention-events.js

@@ -1,3 +1,64 @@
+import { z } from 'zod';
+import { ATTENTION_PROMPT_LIMITS as L } from './attention-prompt-protocol.js';
+import { promptFromAskUserQuestionInput } from './attention-prompt.js';
+export const promptSchema = z.object({
+    channel: z.enum(['mail', 'hook']),
+    questions: z.array(z.object({
+        question: z.string().min(1).max(L.questionChars),
+        header: z.string().max(L.headerChars).optional(),
+        options: z.array(z.object({
+            label: z.string().min(1).max(L.optionLabelChars),
+            description: z.string().max(L.optionDescriptionChars).optional(),
+        }).strict()).max(L.options),
+        multiSelect: z.boolean(),
+        allowText: z.boolean(),
+    }).strict()).min(1).max(L.questions),
+}).strict();
+/** Secret redaction only (no cleaning, truncation or excerpting). */
+export function redactAttentionSecrets(value) {
+    return value
+        .replace(/\b(Bearer\s+)[A-Za-z0-9._~+\/-]+=*/gi, '$1[redacted]')
+        .replace(/\b((?:[A-Z_]*(?:API_KEY|AUTH_TOKEN|ACCESS_TOKEN|SECRET|PASSWORD)[A-Z_]*|authorization)\s*[:=]\s*)[^\s,;]+/gi, '$1[redacted]')
+        .replace(/\b(?:sk-(?:ant-)?[A-Za-z0-9_-]{12,}|gh[pousr]_[A-Za-z0-9]{20,})\b/g, '[redacted]');
+}
+/**
+ * Redacts every prompt string, then re-checks limits, unique labels and the free-text rule.
+ * Never throws; the error names what to fix.
+ */
+export function normalizeAttentionPrompt(input) {
+    const shape = promptSchema.safeParse(input);
+    if (!shape.success) {
+        const issue = shape.error.issues[0];
+        return { ok: false, error: `Invalid prompt${issue ? ` at ${issue.path.join('.') || 'prompt'}: ${issue.message}` : ''}` };
+    }
+    const prompt = shape.data;
+    const redacted = {
+        channel: prompt.channel,
+        questions: prompt.questions.map((q) => ({
+            question: redactAttentionSecrets(q.question),
+            ...(q.header !== undefined ? { header: redactAttentionSecrets(q.header) } : {}),
+            options: q.options.map((o) => ({
+                label: redactAttentionSecrets(o.label),
+                ...(o.description !== undefined ? { description: redactAttentionSecrets(o.description) } : {}),
+            })),
+            multiSelect: q.multiSelect,
+            allowText: q.allowText,
+        })),
+    };
+    const parsed = promptSchema.safeParse(redacted);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        return { ok: false, error: `Invalid prompt${issue ? ` at ${issue.path.join('.') || 'prompt'}: ${issue.message}` : ''}` };
+    }
+    for (const [i, q] of parsed.data.questions.entries()) {
+        const labels = new Set(q.options.map((o) => o.label.toLowerCase()));
+        if (labels.size !== q.options.length)
+            return { ok: false, error: `Invalid prompt at questions.${i}.options: labels must be unique` };
+        if (!q.options.length && (!q.allowText || q.multiSelect))
+            return { ok: false, error: `Invalid prompt at questions.${i}: a question without options must allow text and not be multi-select` };
+    }
+    return { ok: true, value: parsed.data };
+}
 /** Only the selected human-facing excerpt crosses the API; never the hook payload. */
 export function sanitizeAttentionText(value, maxLength) {
     return value
@@ -61,6 +122,15 @@ export function classifyAttentionHook(eventName, data) {
             message: sanitizeAttentionText(question(data) ?? 'Open the session to respond.', 2000),
             ...(sourceId ? { sourceId: sourceId.slice(0, 200) } : {}),
         };
+        if (tool === 'askuserquestion') {
+            const raw = promptFromAskUserQuestionInput(data.tool_input ?? data.toolInput ?? data.input);
+            const checked = raw ? normalizeAttentionPrompt(raw) : undefined;
+            if (checked?.ok)
+                observation.attention.prompt = checked.value;
+        }
+    }
+    if (['PostToolUse', 'postToolUse'].includes(eventName) && tool && askTools.has(tool) && sourceId) {
+        observation.toolComplete = sourceId.slice(0, 200);
     }
     return observation;
 }

package/dist/attention-events.js.map

@@ -1 +1 @@
-{"version":3,"file":"attention-events.js","sourceRoot":"","sources":["../src/attention-events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"attention-events.js","sourceRoot":"","sources":["../src/attention-events.ts"],"names":[],"mappings":"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"}

package/dist/attention-prompt-protocol.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Structured questions an attention request can carry, and the human's answer.
+ * Shared by the bridge, the ftown CLI, MCP, the harness hook and the UI, so it
+ * must stay free of Node built-ins and runtime dependencies.
+ */
+export declare const ATTENTION_PROMPT_LIMITS: {
+    readonly questions: 4;
+    readonly questionChars: 500;
+    readonly headerChars: 40;
+    readonly options: 8;
+    readonly optionLabelChars: 80;
+    readonly optionDescriptionChars: 200;
+    readonly answerTextChars: 4000;
+};
+/**
+ * A waiter counts as live while a long-poll is active and this long after its
+ * latest long-poll ended normally (an aborted poll ends liveness at once). Kept
+ * short: a waiter that died between polls must not swallow an answer that
+ * should have fallen back to mail.
+ */
+export declare const ATTENTION_WAITER_TTL_MS = 10000;
+/** Longest single long-poll on one attention item, in seconds. */
+export declare const ATTENTION_ITEM_WAIT_MAX_SECONDS = 25;
+/** Claude Code `timeout` for the AskUserQuestion hook, in seconds. */
+export declare const ASK_HOOK_TIMEOUT_SECONDS = 3600;
+/** The hook gives up before Claude Code kills it, so the terminal picker can take over. */
+export declare const ASK_HOOK_DEADLINE_MS = 3540000;
+export interface AttentionPromptOption {
+    label: string;
+    description?: string;
+}
+export interface AttentionPromptQuestion {
+    question: string;
+    header?: string;
+    /** May be empty only when `allowText` is true (a free-text question). */
+    options: AttentionPromptOption[];
+    multiSelect: boolean;
+    /** The human may type their own answer or note ("manual input"). */
+    allowText: boolean;
+}
+/**
+ * `mail`: an agent asked through ftown; a live waiter receives the answer,
+ * otherwise it is mailed to the session.
+ * `hook`: a blocking harness hook (Claude Code AskUserQuestion) receives it;
+ * there is no mail fallback.
+ */
+export type AttentionAnswerChannel = 'mail' | 'hook';
+export interface AttentionPrompt {
+    channel: AttentionAnswerChannel;
+    questions: AttentionPromptQuestion[];
+}
+/** Answer to `prompt.questions[i]` is `answers[i]`. */
+export interface AttentionAnswerEntry {
+    /** Indexes into the question's `options`, unique, ascending. */
+    selected: number[];
+    text?: string;
+}
+export interface AttentionAnswer {
+    answers: AttentionAnswerEntry[];
+    answeredAt: string;
+}
+/** What callers send as `questions` (local API, MCP, CLI --questions-json). */
+export interface AttentionPromptQuestionInput {
+    question: string;
+    header?: string;
+    options?: Array<string | AttentionPromptOption>;
+    multiSelect?: boolean;
+    allowText?: boolean;
+}
+/** Body of POST /api/sessions/:id/attention/ask (harness hook only). */
+export interface AttentionAskRequest {
+    toolName: string;
+    toolUseId: string;
+    toolInput: unknown;
+}
+/** Browser -> bridge E2EE command `answer_session_attention` (control permission). */
+export interface AnswerSessionAttentionPayload {
+    bridgeId: string;
+    sessionId: string;
+    eventId: string;
+    answers: AttentionAnswerEntry[];
+}
+/** `waiter`: a live long-poll took the answer. `mail`: mailed to the session. */
+export type AttentionAnswerDelivery = 'waiter' | 'mail' | 'mail_failed';
+export type AttentionAnswerErrorCode = 'attention_not_found' | 'attention_not_answerable' | 'attention_already_resolved' | 'invalid_answer' | 'answer_waiter_gone';
+export type AttentionParseResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};

package/dist/attention-prompt-protocol.js

@@ -0,0 +1,28 @@
+/**
+ * Structured questions an attention request can carry, and the human's answer.
+ * Shared by the bridge, the ftown CLI, MCP, the harness hook and the UI, so it
+ * must stay free of Node built-ins and runtime dependencies.
+ */
+export const ATTENTION_PROMPT_LIMITS = {
+    questions: 4,
+    questionChars: 500,
+    headerChars: 40,
+    options: 8,
+    optionLabelChars: 80,
+    optionDescriptionChars: 200,
+    answerTextChars: 4000,
+};
+/**
+ * A waiter counts as live while a long-poll is active and this long after its
+ * latest long-poll ended normally (an aborted poll ends liveness at once). Kept
+ * short: a waiter that died between polls must not swallow an answer that
+ * should have fallen back to mail.
+ */
+export const ATTENTION_WAITER_TTL_MS = 10_000;
+/** Longest single long-poll on one attention item, in seconds. */
+export const ATTENTION_ITEM_WAIT_MAX_SECONDS = 25;
+/** Claude Code `timeout` for the AskUserQuestion hook, in seconds. */
+export const ASK_HOOK_TIMEOUT_SECONDS = 3600;
+/** The hook gives up before Claude Code kills it, so the terminal picker can take over. */
+export const ASK_HOOK_DEADLINE_MS = 3_540_000;
+//# sourceMappingURL=attention-prompt-protocol.js.map

package/dist/attention-prompt-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attention-prompt-protocol.js","sourceRoot":"","sources":["../src/attention-prompt-protocol.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,SAAS,EAAE,CAAC;IACZ,aAAa,EAAE,GAAG;IAClB,WAAW,EAAE,EAAE;IACf,OAAO,EAAE,CAAC;IACV,gBAAgB,EAAE,EAAE;IACpB,sBAAsB,EAAE,GAAG;IAC3B,eAAe,EAAE,IAAI;CACb,CAAC;AAEX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAC9C,kEAAkE;AAClE,MAAM,CAAC,MAAM,+BAA+B,GAAG,EAAE,CAAC;AAClD,sEAAsE;AACtE,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAC7C,2FAA2F;AAC3F,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC"}

package/dist/attention-prompt.d.ts

@@ -0,0 +1,12 @@
+import { type AttentionAnswerChannel, type AttentionAnswerEntry, type AttentionParseResult, type AttentionPrompt, type AttentionPromptQuestion } from './attention-prompt-protocol.js';
+export declare function parseAttentionPrompt(questions: unknown, channel: AttentionAnswerChannel): AttentionParseResult<AttentionPrompt>;
+export declare function promptFromAskUserQuestionInput(toolInput: unknown): AttentionPrompt | undefined;
+export declare function validateAttentionAnswer(prompt: AttentionPrompt, answers: unknown): AttentionParseResult<AttentionAnswerEntry[]>;
+export declare function answerLabels(question: AttentionPromptQuestion, entry: AttentionAnswerEntry): string[];
+export declare function formatAttentionAnswerText(prompt: AttentionPrompt, answers: AttentionAnswerEntry[]): string;
+export declare function formatAttentionAnswerMail(input: {
+    attentionId: string;
+    title?: string;
+    prompt: AttentionPrompt;
+    answers: AttentionAnswerEntry[];
+}): string;