ftown-bridge 0.19.67 → 0.20.0

package/dist/attention-prompt.js

@@ -0,0 +1,333 @@
+import { ATTENTION_PROMPT_LIMITS, } from './attention-prompt-protocol.js';
+// DCS/SOS/PM/APC payloads run to ST (ESC \ or U+009C) or the end of the string.
+const STRING_ESCAPE_PATTERN = /\u001b[PX^_][\s\S]*?(?:\u001b\\|\u009c|$)/g;
+// OSC (7-bit or U+009D) ends at BEL, ST or the end of the string.
+const OSC_PATTERN = /(?:\u001b\]|\u009d)[\s\S]*?(?:\u0007|\u009c|\u001b\\|$)/g;
+// CSI (7-bit or U+009B).
+const CSI_PATTERN = /(?:\u001b\[|\u009b)[0-?]*[ -/]*[@-~]?/g;
+// Any other ESC consumes at most one printable ASCII char; otherwise only the ESC goes.
+const LONE_ESC_PATTERN = /\u001b[ -~]?/g;
+// C0 and C1 control characters except \t (\u0009) and \n (\u000a), plus bidi/format controls.
+const CONTROL_PATTERN = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+function stripControl(value) {
+    return value
+        .replace(/[\u2028\u2029]/g, '\n')
+        .replace(STRING_ESCAPE_PATTERN, '')
+        .replace(OSC_PATTERN, '')
+        .replace(CSI_PATTERN, '')
+        .replace(LONE_ESC_PATTERN, '')
+        .replace(CONTROL_PATTERN, '');
+}
+/** Multi-line text (question text, answer text): keeps \n and \t. */
+function cleanBlock(value) {
+    return stripControl(value).trim();
+}
+/** Single-line text (header, label, description): \n and \t become spaces. */
+function cleanLine(value) {
+    return stripControl(value).replace(/[\n\t]/g, ' ').trim();
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function ok(value) {
+    return { ok: true, value };
+}
+function fail(error) {
+    return { ok: false, error };
+}
+function unknownKey(value, allowed) {
+    return Object.keys(value).find((key) => !allowed.includes(key));
+}
+const QUESTION_KEYS = ['question', 'header', 'options', 'multiSelect', 'allowText'];
+const OPTION_KEYS = ['label', 'description'];
+function parseOption(raw, path) {
+    const limits = ATTENTION_PROMPT_LIMITS;
+    let labelRaw;
+    let descriptionRaw;
+    if (typeof raw === 'string') {
+        labelRaw = raw;
+    }
+    else if (isPlainObject(raw)) {
+        const extra = unknownKey(raw, OPTION_KEYS);
+        if (extra !== undefined)
+            return fail(`${path}.${extra} is not a supported field`);
+        labelRaw = raw.label;
+        descriptionRaw = raw.description;
+    }
+    else {
+        return fail(`${path} must be a string or an object with a label`);
+    }
+    if (typeof labelRaw !== 'string')
+        return fail(`${path}.label must be 1-${limits.optionLabelChars} characters`);
+    const label = cleanLine(labelRaw);
+    if (label.length < 1 || label.length > limits.optionLabelChars) {
+        return fail(`${path}.label must be 1-${limits.optionLabelChars} characters`);
+    }
+    const option = { label };
+    if (descriptionRaw !== undefined) {
+        if (typeof descriptionRaw !== 'string')
+            return fail(`${path}.description must be a string`);
+        const description = cleanLine(descriptionRaw);
+        if (description.length > limits.optionDescriptionChars) {
+            return fail(`${path}.description must be at most ${limits.optionDescriptionChars} characters`);
+        }
+        if (description)
+            option.description = description;
+    }
+    return ok(option);
+}
+function parseQuestion(raw, path) {
+    const limits = ATTENTION_PROMPT_LIMITS;
+    if (!isPlainObject(raw))
+        return fail(`${path} must be an object`);
+    const extra = unknownKey(raw, QUESTION_KEYS);
+    if (extra !== undefined)
+        return fail(`${path}.${extra} is not a supported field`);
+    if (typeof raw.question !== 'string')
+        return fail(`${path}.question must be 1-${limits.questionChars} characters`);
+    const question = cleanBlock(raw.question);
+    if (question.length < 1 || question.length > limits.questionChars) {
+        return fail(`${path}.question must be 1-${limits.questionChars} characters`);
+    }
+    let header;
+    if (raw.header !== undefined) {
+        if (typeof raw.header !== 'string')
+            return fail(`${path}.header must be a string`);
+        const cleaned = cleanLine(raw.header);
+        if (cleaned.length > limits.headerChars)
+            return fail(`${path}.header must be at most ${limits.headerChars} characters`);
+        if (cleaned)
+            header = cleaned;
+    }
+    const options = [];
+    if (raw.options !== undefined) {
+        if (!Array.isArray(raw.options))
+            return fail(`${path}.options must be an array`);
+        if (raw.options.length > limits.options)
+            return fail(`${path}.options must have at most ${limits.options} entries`);
+        const seen = new Set();
+        for (let i = 0; i < raw.options.length; i += 1) {
+            const parsed = parseOption(raw.options[i], `${path}.options[${i}]`);
+            if (!parsed.ok)
+                return parsed;
+            const key = parsed.value.label.toLowerCase();
+            if (seen.has(key))
+                return fail(`${path}.options[${i}].label duplicates another option label`);
+            seen.add(key);
+            options.push(parsed.value);
+        }
+    }
+    let multiSelect = false;
+    if (raw.multiSelect !== undefined) {
+        if (typeof raw.multiSelect !== 'boolean')
+            return fail(`${path}.multiSelect must be a boolean`);
+        multiSelect = raw.multiSelect;
+    }
+    let allowText = true;
+    if (raw.allowText !== undefined) {
+        if (typeof raw.allowText !== 'boolean')
+            return fail(`${path}.allowText must be a boolean`);
+        allowText = raw.allowText;
+    }
+    if (options.length === 0) {
+        if (!allowText)
+            return fail(`${path} has no options, so allowText must be true`);
+        if (multiSelect)
+            return fail(`${path} has no options, so multiSelect must be false`);
+    }
+    const result = { question, options, multiSelect, allowText };
+    if (header !== undefined)
+        result.header = header;
+    return ok(result);
+}
+export function parseAttentionPrompt(questions, channel) {
+    const max = ATTENTION_PROMPT_LIMITS.questions;
+    if (!Array.isArray(questions))
+        return fail('questions must be an array');
+    if (questions.length < 1 || questions.length > max)
+        return fail(`questions must have 1-${max} entries`);
+    const parsed = [];
+    for (let i = 0; i < questions.length; i += 1) {
+        const q = parseQuestion(questions[i], `questions[${i}]`);
+        if (!q.ok)
+            return q;
+        parsed.push(q.value);
+    }
+    return ok({ channel, questions: parsed });
+}
+/** Lenient parse of one Claude Code AskUserQuestion question; undefined when unusable. */
+function questionFromAskInput(raw) {
+    const limits = ATTENTION_PROMPT_LIMITS;
+    if (!isPlainObject(raw))
+        return undefined;
+    if (typeof raw.question !== 'string')
+        return undefined;
+    const question = cleanBlock(raw.question);
+    if (question.length < 1 || question.length > limits.questionChars)
+        return undefined;
+    let header;
+    if (raw.header !== undefined) {
+        if (typeof raw.header !== 'string')
+            return undefined;
+        const cleaned = cleanLine(raw.header);
+        if (cleaned.length > limits.headerChars)
+            return undefined;
+        if (cleaned)
+            header = cleaned;
+    }
+    if (!Array.isArray(raw.options))
+        return undefined;
+    if (raw.options.length < 1 || raw.options.length > limits.options)
+        return undefined;
+    const options = [];
+    const seen = new Set();
+    for (const rawOption of raw.options) {
+        if (!isPlainObject(rawOption))
+            return undefined;
+        if (typeof rawOption.label !== 'string')
+            return undefined;
+        const label = cleanLine(rawOption.label);
+        if (label.length < 1 || label.length > limits.optionLabelChars)
+            return undefined;
+        const key = label.toLowerCase();
+        if (seen.has(key))
+            return undefined;
+        seen.add(key);
+        const option = { label };
+        if (rawOption.description !== undefined) {
+            if (typeof rawOption.description !== 'string')
+                return undefined;
+            const description = cleanLine(rawOption.description);
+            if (description.length > limits.optionDescriptionChars)
+                return undefined;
+            if (description)
+                option.description = description;
+        }
+        options.push(option);
+    }
+    let multiSelect = false;
+    if (raw.multiSelect !== undefined) {
+        if (typeof raw.multiSelect !== 'boolean')
+            return undefined;
+        multiSelect = raw.multiSelect;
+    }
+    const result = { question, options, multiSelect, allowText: true };
+    if (header !== undefined)
+        result.header = header;
+    return result;
+}
+export function promptFromAskUserQuestionInput(toolInput) {
+    if (!isPlainObject(toolInput))
+        return undefined;
+    const raw = toolInput.questions;
+    if (!Array.isArray(raw))
+        return undefined;
+    if (raw.length < 1 || raw.length > ATTENTION_PROMPT_LIMITS.questions)
+        return undefined;
+    const questions = [];
+    for (const entry of raw) {
+        const question = questionFromAskInput(entry);
+        if (!question)
+            return undefined;
+        questions.push(question);
+    }
+    return { channel: 'hook', questions };
+}
+const ANSWER_KEYS = ['selected', 'text'];
+export function validateAttentionAnswer(prompt, answers) {
+    if (!Array.isArray(answers))
+        return fail('answers must be an array');
+    if (answers.length !== prompt.questions.length) {
+        return fail(`answers must have exactly ${prompt.questions.length} entries, one per question`);
+    }
+    const normalized = [];
+    for (let i = 0; i < answers.length; i += 1) {
+        const path = `answers[${i}]`;
+        const question = prompt.questions[i];
+        const raw = answers[i];
+        if (!isPlainObject(raw))
+            return fail(`${path} must be an object`);
+        const extra = unknownKey(raw, ANSWER_KEYS);
+        if (extra !== undefined)
+            return fail(`${path}.${extra} is not a supported field`);
+        const rawSelected = raw.selected === undefined ? [] : raw.selected;
+        if (!Array.isArray(rawSelected))
+            return fail(`${path}.selected must be an array of option indexes`);
+        const selected = [];
+        for (const index of rawSelected) {
+            if (typeof index !== 'number' || !Number.isInteger(index)) {
+                return fail(`${path}.selected must contain only integers`);
+            }
+            if (index < 0 || index >= question.options.length) {
+                return fail(`${path}.selected has an out-of-range index ${index}`);
+            }
+            if (selected.includes(index))
+                return fail(`${path}.selected has a duplicate index ${index}`);
+            selected.push(index);
+        }
+        selected.sort((a, b) => a - b);
+        if (!question.multiSelect && selected.length > 1) {
+            return fail(`${path}.selected must have at most 1 entry for a single-select question`);
+        }
+        let text;
+        if (raw.text !== undefined) {
+            if (typeof raw.text !== 'string')
+                return fail(`${path}.text must be a string`);
+            const cleaned = cleanBlock(raw.text);
+            if (cleaned.length > ATTENTION_PROMPT_LIMITS.answerTextChars) {
+                return fail(`${path}.text must be at most ${ATTENTION_PROMPT_LIMITS.answerTextChars} characters`);
+            }
+            if (cleaned) {
+                if (!question.allowText)
+                    return fail(`${path}.text is not allowed for this question`);
+                text = cleaned;
+            }
+        }
+        if (selected.length === 0 && text === undefined) {
+            return fail(`${path} needs at least one selected option or some text`);
+        }
+        const entry = { selected };
+        if (text !== undefined)
+            entry.text = text;
+        normalized.push(entry);
+    }
+    return ok(normalized);
+}
+export function answerLabels(question, entry) {
+    const labels = [];
+    for (const index of [...entry.selected].sort((a, b) => a - b)) {
+        const option = question.options[index];
+        if (option)
+            labels.push(option.label);
+    }
+    return labels;
+}
+export function formatAttentionAnswerText(prompt, answers) {
+    const blocks = [];
+    prompt.questions.forEach((question, i) => {
+        const entry = answers[i] ?? { selected: [] };
+        const lines = [`Q: ${question.question}`];
+        const labels = answerLabels(question, entry);
+        if (labels.length > 0) {
+            lines.push(`A: ${labels.join(', ')}`);
+            if (entry.text)
+                lines.push(`Note: ${entry.text}`);
+        }
+        else if (entry.text) {
+            lines.push(`A: ${entry.text}`);
+        }
+        blocks.push(lines.join('\n'));
+    });
+    return blocks.join('\n\n');
+}
+export function formatAttentionAnswerMail(input) {
+    const lines = [`[ftown attention answer id=${input.attentionId}]`];
+    const title = input.title?.trim();
+    if (title)
+        lines.push(`Re: ${title}`);
+    return `${lines.join('\n')}\n\n${formatAttentionAnswerText(input.prompt, input.answers)}`;
+}
+//# sourceMappingURL=attention-prompt.js.map

package/dist/attention-prompt.js.map

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

package/dist/attention-store.d.ts

@@ -1,5 +1,6 @@
 import type { PushNotice } from './push-notifier.js';
 import { type Activity, type AttentionItem } from './attention-events.js';
+import { type AttentionPrompt } from './attention-prompt-protocol.js';
 export interface AttentionPage {
     events: AttentionItem[];
     cursor: string;
@@ -19,6 +20,14 @@ export interface ExplicitAttentionSnapshot {
     attention: AttentionItem | null;
     sequence: number;
 }
+export interface AttentionAnswerResult {
+    item: AttentionItem;
+    snapshot: ExplicitAttentionSnapshot;
+    waiterLive: boolean;
+}
+export interface AttentionRecordOptions {
+    prompt?: AttentionPrompt;
+}
 export declare class AttentionError extends Error {
     readonly code: string;
     readonly status: number;
@@ -47,10 +56,18 @@ export declare class AttentionStore {
     private onNotification?;
     private locks;
     private listeners;
+    /** Per session: wake callbacks of item waiters, fired whenever any item is resolved. */
+    private itemWaiters;
+    /** Per attention event id: active item long-polls and when the latest one started. */
+    private pollers;
     private idleTimers;
     private notificationsStopped;
     private notificationOptions;
     constructor(resolveDir: (sessionId: string) => string, resolvedRetention?: number, onNotification?: ((sessionId: string, notice: PushNotice) => void) | undefined, options?: AttentionNotificationOptions);
+    private wakeItemWaiters;
+    private isExplicit;
+    hasLiveWaiter(eventId: string, now?: number): boolean;
+    private activeWaits;
     private clearIdleTimer;
     private idleCanceled;
     private scheduleIdle;
@@ -63,13 +80,24 @@ export declare class AttentionStore {
     private save;
     private cursor;
     private parseCursor;
+    /** `protect`: items resolved by the current operation; a waiter must still be able to read them. */
     private prune;
-    record(id: string, eventName: string, data: Record<string, unknown>): Promise<AttentionItem | undefined>;
+    record(id: string, eventName: string, data: Record<string, unknown>, options?: AttentionRecordOptions): Promise<AttentionItem | undefined>;
+    /** Like record, but also reports whether the returned item was newly created (true) or deduped onto an existing one (false). */
+    recordDetailed(id: string, eventName: string, data: Record<string, unknown>, options?: AttentionRecordOptions): Promise<{
+        item: AttentionItem | undefined;
+        created: boolean;
+    }>;
     list(id: string, options?: AttentionReadOptions): Promise<AttentionPage>;
     private latestExplicit;
     explicitSnapshot(id: string): Promise<ExplicitAttentionSnapshot>;
     /** Dismiss the displayed incident and its superseded explicit predecessors. */
     resolveExplicitThrough(id: string, eventId: string): Promise<ExplicitAttentionSnapshot>;
+    /** Record the human's answer and resolve the item. The caller delivers it (waiter or mail). */
+    answer(id: string, eventId: string, answers: unknown, now?: Date): Promise<AttentionAnswerResult>;
     mutate(id: string, ids: string[], operation: 'ack' | 'resolve', reason?: string): Promise<AttentionItem[]>;
     wait(id: string, options: AttentionReadOptions, waitSeconds: number, signal?: AbortSignal): Promise<AttentionPage>;
+    private readItem;
+    /** Long-poll one item: returns when it is resolved, at the deadline (current item), or rejects on abort. */
+    waitForItem(id: string, eventId: string, waitMs: number, signal?: AbortSignal): Promise<AttentionItem>;
 }