@maudecode/talaria-web 1.17.2 → 1.19.0

package/dist/sessions/goals.d.ts

@@ -0,0 +1,31 @@
+import type { SessionGoal, SidecarResult } from '@maudecode/talaria-web-contracts';
+type GoalStatus = SidecarResult<'goals.get'>;
+/**
+ * TAL-808: the session `goal` view of the Agent's `goals.get`. A timed park whose deadline passed is active again (the
+ * Agent lifts it at its next judgement); a done, cleared or absent goal is null.
+ */
+export declare function sessionGoalView(status: GoalStatus, now: number): SessionGoal | null;
+/**
+ * TAL-808: the last `goals.get` per session, refreshed after `/goal` and each goal judgement.
+ * ponytail: in memory; a session's first load after a restart reads it once, and a goal changed from another surface shows
+ * after this server's next refresh.
+ */
+export declare class SessionGoals {
+    private readonly now;
+    private readonly bySession;
+    private readonly parkTimers;
+    /** The view each session last reported, so a park that lapsed since counts as a change. */
+    private readonly reported;
+    constructor(now: () => number);
+    has(sessionId: string): boolean;
+    view(sessionId: string): SessionGoal | null;
+    /** Stores the session's status; true when its view differs from the one it last reported. */
+    set(sessionId: string, status: GoalStatus): boolean;
+    /**
+     * Runs `reread` just after the session's timed park ends, replacing any earlier one. A timer that fires early finds the
+     * park still running, and the re-read schedules the next one.
+     */
+    rereadAfterPark(sessionId: string, reread: () => void): void;
+    sweep(exists: (sessionId: string) => boolean | Promise<boolean>): Promise<void>;
+}
+export {};

package/dist/sessions/goals.js

@@ -0,0 +1,75 @@
+/** Past the deadline, so the Agent's own clock agrees the park ended. */
+const PARK_END_MARGIN_MS = 500;
+/**
+ * TAL-808: the session `goal` view of the Agent's `goals.get`. A timed park whose deadline passed is active again (the
+ * Agent lifts it at its next judgement); a done, cleared or absent goal is null.
+ */
+export function sessionGoalView(status, now) {
+    const goal = status.goal;
+    if (!goal || (goal.status !== 'active' && goal.status !== 'paused'))
+        return null;
+    const base = { text: goal.goal, turns_used: goal.turns_used, max_turns: goal.max_turns };
+    if (goal.status === 'paused')
+        return { ...base, status: 'paused', reason: goal.paused_reason || null, parked_until: null };
+    const parked = status.parked;
+    if (parked && (parked.until === null || parked.until > now))
+        return { ...base, status: 'parked', reason: parked.reason, parked_until: parked.until };
+    return { ...base, status: 'active', reason: null, parked_until: null };
+}
+/**
+ * TAL-808: the last `goals.get` per session, refreshed after `/goal` and each goal judgement.
+ * ponytail: in memory; a session's first load after a restart reads it once, and a goal changed from another surface shows
+ * after this server's next refresh.
+ */
+export class SessionGoals {
+    now;
+    bySession = new Map();
+    parkTimers = new Map();
+    /** The view each session last reported, so a park that lapsed since counts as a change. */
+    reported = new Map();
+    constructor(now) {
+        this.now = now;
+    }
+    has(sessionId) {
+        return this.bySession.has(sessionId);
+    }
+    view(sessionId) {
+        const status = this.bySession.get(sessionId);
+        return status ? sessionGoalView(status, this.now()) : null;
+    }
+    /** Stores the session's status; true when its view differs from the one it last reported. */
+    set(sessionId, status) {
+        this.bySession.set(sessionId, status);
+        const view = JSON.stringify(this.view(sessionId));
+        // A session that never had one starts with none.
+        if ((this.reported.get(sessionId) ?? 'null') === view)
+            return false;
+        this.reported.set(sessionId, view);
+        return true;
+    }
+    /**
+     * Runs `reread` just after the session's timed park ends, replacing any earlier one. A timer that fires early finds the
+     * park still running, and the re-read schedules the next one.
+     */
+    rereadAfterPark(sessionId, reread) {
+        clearTimeout(this.parkTimers.get(sessionId));
+        this.parkTimers.delete(sessionId);
+        const until = this.view(sessionId)?.parked_until;
+        if (until === null || until === undefined)
+            return;
+        const timer = setTimeout(() => { this.parkTimers.delete(sessionId); reread(); }, Math.max(0, until - this.now()) * 1000 + PARK_END_MARGIN_MS);
+        timer.unref();
+        this.parkTimers.set(sessionId, timer);
+    }
+    async sweep(exists) {
+        for (const sid of this.bySession.keys()) {
+            if (await exists(sid))
+                continue;
+            this.bySession.delete(sid);
+            this.reported.delete(sid);
+            clearTimeout(this.parkTimers.get(sid));
+            this.parkTimers.delete(sid);
+        }
+    }
+}
+//# sourceMappingURL=goals.js.map

package/dist/sessions/goals.js.map

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

package/dist/sessions/handoff.d.ts

@@ -0,0 +1,32 @@
+type Message = Record<string, unknown>;
+/** The summary prompt the session's main model answers. */
+export declare const HANDOFF_SYSTEM_PROMPT: string;
+/** Python `_extract_handoff_text`: a content-part list joins its text parts. */
+export declare function handoffText(content: unknown): string;
+/** The transcript the model reads: each user/assistant message's text, capped at 1000 characters. */
+export declare function handoffTranscript(messages: Message[]): string;
+/** Python `_fallback_handoff_summary`: the last user and assistant point, in the conversation's language. */
+export declare function fallbackHandoffSummary(messages: Message[]): string;
+/** Python `_summary_output_incomplete`: empty, ellipsized, or a last line that stops mid-sentence. */
+export declare function summaryOutputIncomplete(raw: string): boolean;
+/** Python `_agent_summary_incomplete`: the provider stopped on its token limit, or the text looks cut off. */
+export declare function completionIncomplete(result: {
+    text: string;
+    finish_reason?: string | null;
+}): boolean;
+interface HandoffPayload {
+    session_id: string;
+    summary: string;
+    channel: unknown;
+    rounds: unknown;
+    fallback: boolean;
+}
+/** Python `_build_handoff_summary_tool_message`: an empty `tool_call_id` keeps the marker out of the model's history. */
+export declare function handoffMarker(sid: string, summary: string, channel: string | null, rounds: number, fallback: boolean, now: number): Message;
+/** A marker's card payload (Python `_extract_handoff_summary_payload` / `_is_matching_handoff_summary_content`). */
+export declare function handoffPayload(content: unknown): HandoffPayload | null;
+/** The tail dedupe: the same card regardless of when it was generated. */
+export declare function sameHandoff(a: HandoffPayload | null, b: HandoffPayload | null): boolean;
+/** A WebUI transcript row's card payload: only a `handoff_summary` tool row carries one. */
+export declare function messageHandoffPayload(m: unknown): HandoffPayload | null;
+export {};

package/dist/sessions/handoff.js

@@ -0,0 +1,114 @@
+/**
+ * TAL-258: the handoff dock's summary (Python `_handle_handoff_summary` and its persistence helpers). The prompt, the
+ * deterministic English/Chinese fallback, the truncation guard, and the display-only `handoff_summary` tool marker.
+ */
+import { str } from '../util.js';
+import { isDict } from './merge.js';
+/** The summary prompt the session's main model answers. */
+export const HANDOFF_SYSTEM_PROMPT = [
+    'You are summarizing an external-channel conversation so a Web UI reader can quickly catch up after switching contexts.',
+    '',
+    'Only use the latest messages, and never copy raw transcript lines.',
+    'Do not output role labels (no “你:” / “assistant:” / “user:” / “assistant”).',
+    'Use direct 2–5 bullet points in the conversation language.',
+    'English: speak using “you”.',
+    '中文: 使用“你”。',
+    '',
+    'Focus on:',
+    '- Unfinished tasks or action items',
+    '- Pending questions that need replies',
+    '- Key decisions made',
+    '- Open disagreements or TBD items',
+    '',
+    'If the conversation is purely casual with no actionable items, say so in one sentence.',
+].join('\n');
+/** Python `_extract_handoff_text`: a content-part list joins its text parts. */
+export function handoffText(content) {
+    if (Array.isArray(content))
+        return content.filter(isDict).map((part) => str(part.text || part.content || '')).join(' ').trim();
+    return str(content ?? '').trim();
+}
+// Code points, as Python counts and slices them.
+const chars = (text) => Array.from(text);
+const isConversation = (m) => m.role === 'user' || m.role === 'assistant';
+const isChinese = (messages) => messages.some((m) => /[一-鿿]/.test(handoffText(m.content)));
+/** The transcript the model reads: each user/assistant message's text, capped at 1000 characters. */
+export function handoffTranscript(messages) {
+    return messages.flatMap((m) => {
+        const text = chars(handoffText(m.content)).slice(0, 1000).join('').trim();
+        return isConversation(m) && text ? [text] : [];
+    }).join('\n');
+}
+function snippet(raw, max = 82) {
+    const text = raw.split(/\s+/).filter(Boolean).join(' ');
+    const cps = chars(text);
+    return cps.length <= max ? text : `${cps.slice(0, max - 1).join('').trimEnd()}…`;
+}
+/** Python `_fallback_handoff_summary`: the last user and assistant point, in the conversation's language. */
+export function fallbackHandoffSummary(messages) {
+    const chinese = isChinese(messages);
+    const user = [];
+    const assistant = [];
+    for (const m of messages) {
+        const text = snippet(handoffText(m.content));
+        if (!isConversation(m) || !text)
+            continue;
+        (m.role === 'user' ? user : assistant).push(text);
+    }
+    if (!user.length && !assistant.length) {
+        return chinese ? '近期可读文本不足，无法生成更完整的交接摘要，请补充一条消息后重试。' : 'Not enough readable text to create a useful handoff summary; please send one more message and retry.';
+    }
+    const enough = user.length + assistant.length >= 2;
+    const bullets = chinese
+        ? [...(user.length ? [`- 你刚讨论了：${user.at(-1)}。`] : []), ...(assistant.length ? [`- 助手已回复：${assistant.at(-1)}。`] : []), enough ? '- 当前对话存在尚未确认的后续动作。' : '- 当前信息偏少，建议补充关键点后再切换。']
+        : [...(user.length ? [`- You asked: ${user.at(-1)}.`] : []), ...(assistant.length ? [`- The assistant responded: ${assistant.at(-1)}.`] : []), enough ? '- There is pending context to continue next.' : '- The conversation is still short; add one more turn before summarizing.'];
+    return bullets.join('\n');
+}
+/** Python `_summary_output_incomplete`: empty, ellipsized, or a last line that stops mid-sentence. */
+export function summaryOutputIncomplete(raw) {
+    const text = raw.trim();
+    if (!text || text.endsWith('...') || text.endsWith('…'))
+        return true;
+    const last = text.split('\n').map((line) => line.trim()).filter(Boolean).at(-1);
+    if (!last)
+        return true;
+    if (/[。！？；!?.；]$/.test(last))
+        return false;
+    if (chars(last).length >= 56 && !/\b(and|or|so|then|because|if|when|but|as)\b$/i.test(last))
+        return true;
+    return /\b(and|or|but|so|because|if|when)$/i.test(last);
+}
+/** Python `_agent_summary_incomplete`: the provider stopped on its token limit, or the text looks cut off. */
+export function completionIncomplete(result) {
+    const reason = str(result.finish_reason).trim().toLowerCase();
+    return reason === 'length' || reason === 'max_tokens' || summaryOutputIncomplete(result.text);
+}
+/** Python `_build_handoff_summary_tool_message`: an empty `tool_call_id` keeps the marker out of the model's history. */
+export function handoffMarker(sid, summary, channel, rounds, fallback, now) {
+    const content = JSON.stringify({ _handoff_summary_card: true, session_id: sid, summary: summary.trim(), channel: channel?.trim() || null, rounds, fallback, generated_at: now });
+    return { role: 'tool', tool_call_id: '', name: 'handoff_summary', timestamp: now, _ts: now, content };
+}
+/** A marker's card payload (Python `_extract_handoff_summary_payload` / `_is_matching_handoff_summary_content`). */
+export function handoffPayload(content) {
+    let payload = content;
+    if (typeof content === 'string') {
+        try {
+            payload = JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!isDict(payload) || payload._handoff_summary_card !== true || payload.session_id === null || payload.session_id === undefined)
+        return null;
+    return { session_id: str(payload.session_id), summary: str(payload.summary ?? ''), channel: payload.channel ?? null, rounds: payload.rounds ?? null, fallback: Boolean(payload.fallback) };
+}
+/** The tail dedupe: the same card regardless of when it was generated. */
+export function sameHandoff(a, b) {
+    return a !== null && b !== null && a.session_id === b.session_id && a.summary === b.summary && a.channel === b.channel && a.rounds === b.rounds && a.fallback === b.fallback;
+}
+/** A WebUI transcript row's card payload: only a `handoff_summary` tool row carries one. */
+export function messageHandoffPayload(m) {
+    return isDict(m) && m.role === 'tool' && m.name === 'handoff_summary' ? handoffPayload(m.content) : null;
+}
+//# sourceMappingURL=handoff.js.map

package/dist/sessions/handoff.js.map

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

package/dist/sessions/journal.d.ts

@@ -1,3 +1,6 @@
+import type { JournalBackend, JournalWriter } from './storage/backend.js';
+export type RunJournal = JournalBackend;
+export type RunJournalWriter = JournalWriter;
 export declare const RUN_JOURNAL_DIR_NAME = "_run_journal";
 export declare const TERMINAL_SSE_EVENTS: Set<string>;
 export declare const SSE_RELAY_CLOSE_EVENTS: Set<string>;
@@ -50,82 +53,5 @@ export declare function validateId(value: string, field: string): string;
 export declare function parseRunJournalEventId(raw: string | null | undefined): [string | null, number | null];
 /** The journal's run-status vocabulary, from the turn outcome (`terminal_state`) every terminal frame carries. */
 export declare function terminalStateForEvent(eventName: string, payload: unknown): string | null;
-export declare class RunJournal {
-    readonly sessionDir: string;
-    private readonly env;
-    constructor(sessionDir: string, env?: Record<string, string | undefined>);
-    root(): string;
-    pathFor(sessionId: string, runId: string): string;
-    /** Python `delete_run_journal`: remove one session's journal directory; false for a missing or unsafe id. */
-    deleteSession(sessionId: string): boolean;
-    private fsyncMode;
-    writer(sessionId: string, runId: string): RunJournalWriter;
-    private static parseLines;
-    readRunEvents(sessionId: string, runId: string, opts?: {
-        afterSeq?: number | null;
-        maxSeq?: number | null;
-    }): JournalEvent[];
-    /**
-     * `readRunEvents` one page at a time, so a replay that waits on a slow reader holds one page of the journal rather
-     * than all of it (run-state contract: recovery never parses an unbounded journal in one request).
-     */
-    iterRunEvents(sessionId: string, runId: string, opts?: {
-        afterSeq?: number | null;
-        maxSeq?: number | null;
-    }): Generator<JournalEvent>;
-    readRunEventTail(sessionId: string, runId: string, maxBytes?: number, maxRows?: number): {
-        events: JournalEvent[];
-        truncated: boolean;
-    };
-    /** The bounded tail of `raw`, read from byte `start`: drop the partial first line, keep the last `maxRows` rows. */
-    private static parseTail;
-    /** `readRunEventTail` off the event loop, plus the identity of the file it read. */
-    private static readTailAsync;
-    static selectAuthoritativeTerminalEvent(events: JournalEvent[]): JournalEvent | null;
-    static summaryFromEvents(sessionId: string, runId: string, events: JournalEvent[]): RunSummary;
-    private loadPrunedSummary;
-    latestRunSummary(sessionId: string, runId: string): RunSummary;
-    /**
-     * Python `prune_settled_run_journals`: compact terminal journals older than
-     * `HERMES_WEBUI_RUN_JOURNAL_RETENTION_DAYS` (14) into `.summary.json`, keeping
-     * the `HERMES_WEBUI_RUN_JOURNAL_KEEP_RECENT` (3) newest per session and any
-     * path with a live writer.
-     *
-     * The sweep is incremental so requests keep running on the event loop: I/O is
-     * async and it yields after every session and every parsed journal. Sessions
-     * whose metadata already rules out pruning (no more journals than the keep
-     * count, or none past the cutoff) are not parsed, so `terminal` counts only
-     * the journals inspected. `signal` stops the sweep at its next yield;
-     * `pause` replaces the default yield (`setImmediate`).
-     */
-    pruneSettled(opts?: PruneOptions): Promise<PruneResult>;
-    /** Locate a run across sessions (Python `find_run_summary`). */
-    findRunSummary(runId: string): RunSummary | null;
-    sessionJournalFingerprint(sessionId: string): string;
-    /** Python `read_session_run_events`: replay rows after an opaque cursor across a session's runs. */
-    readSessionRunEvents(sessionId: string, afterEventId: string | null | undefined): {
-        status: string;
-        events: JournalEvent[];
-        cursor_run_id: string | null;
-        cursor_seq: number | null;
-    };
-    /** Python `stale_interrupted_event`: a synthetic terminal row for a journal whose worker died. */
-    staleInterruptedEvent(sessionId: string, runId: string, afterSeq?: number | null, now?: number): JournalEvent | null;
-}
-export declare class RunJournalWriter {
-    private readonly journal;
-    readonly sessionId: string;
-    readonly runId: string;
-    private readonly fsyncMode;
-    private readonly now;
-    private fd;
-    private seq;
-    private closed;
-    readonly path: string;
-    constructor(journal: RunJournal, sessionId: string, runId: string, fsyncMode: 'eager' | 'terminal-only', now?: () => number);
-    appendSseEvent(eventName: string, payload: unknown, meta?: {
-        redacted?: boolean;
-    }): JournalEvent;
-    private closeHandle;
-    close(): void;
-}
+export declare function selectAuthoritativeTerminalEvent(events: JournalEvent[]): JournalEvent | null;
+export declare function summaryFromEvents(sessionId: string, runId: string, events: JournalEvent[]): RunSummary;