@north-light/api 0.3.579 → 0.3.587

package/dist/clients/conversation/projection.d.ts

@@ -0,0 +1,79 @@
+import type { AgentSessionEvent } from '@earendil-works/pi-coding-agent';
+import type { Message, ToolResultMessage } from '@earendil-works/pi-ai';
+import type { BrokerSnapshot } from '../../core/runtime/broker-protocol.js';
+import { type ToolGroupSummary } from '../../shared/tool-groups.js';
+/** A persisted pi message or a crouter custom message carried on the broker wire. */
+export type AnyMessage = Message | ({
+    role: string;
+} & Record<string, unknown>);
+export interface ConvState {
+    /** The full ordered transcript (snapshot history + streamed messages). */
+    messages: AnyMessage[];
+    /** Index of the assistant message currently streaming, or null. */
+    streamingIndex: number | null;
+    /** toolCallIds whose `tool_execution_*` is in flight (for an "executing…" badge). */
+    executingToolIds: ReadonlySet<string>;
+    /** Latest streaming/final result carried by tool_execution_* before the persisted toolResult message lands. */
+    partialToolResults: ReadonlyMap<string, ToolResultMessage>;
+    /** True between `agent_start` and `agent_end` (drives prompt-vs-steer + Stop). */
+    isStreaming: boolean;
+    /** A transient activity label (working / compacting / retrying), or null. */
+    activity: string | null;
+    /** Broker-selected normal label restored after temporary compaction/retry activity. */
+    workingActivity: string;
+    /** Texts still waiting to run — a writable view's steer/follow-up sent mid-turn
+     *  (pi's `_steeringMessages` + `_followUpMessages`), authoritative from the
+     *  engine's `queue_update` event. Drained (and removed here) the moment each
+     *  one starts as a real `message_start`, so a queued row and the eventual
+     *  transcript message never both show. */
+    queued: readonly string[];
+    /** Plain-text presentation recaps, keyed by the group's first tool-call id. */
+    toolGroupSummaries: Readonly<Record<string, string>>;
+    /** Canonical broker-owned completed tool-group summaries, keyed by the group's first tool-call id. */
+    toolGroupSummaryDetails: Readonly<Record<string, ToolGroupSummary>>;
+}
+export declare function initialConvState(): ConvState;
+/** Rebuild the ephemeral reconciliation fields from a persisted transcript cache. */
+export declare function restoreConvState(entry: {
+    messages: AnyMessage[];
+    isStreaming: boolean;
+    activity: string | null;
+    toolGroupSummaries: unknown;
+}): ConvState;
+/** Seed state from the broker's catch-up snapshot.
+ *
+ *  `welcome.snapshot` is the PERSISTED history (`snapshotMessages()` in the
+ *  broker), not the live in-memory array. During an active turn — after
+ *  `message_start`, before `message_end` — the in-flight assistant message may
+ *  not be persisted yet, so a mid-stream `welcome` can report
+ *  `state.isStreaming: true` with no trailing assistant in the snapshot.
+ *  Wholesale-replacing in that case (as we always did) drops the in-flight
+ *  turn: `streamingIndex` resets to null and the next `message_update`/
+ *  `message_end` has nothing to land on (see `reduce`).
+ *
+ *  So: idle snapshots replace wholesale exactly as before. Streaming snapshots
+ *  reconcile — if the persisted history already ends in an assistant, adopt
+ *  it as the streaming target; otherwise adopt the caller-supplied `previous`
+ *  state's in-flight assistant (a cache-first render or an earlier live
+ *  session) if one exists, or synthesize an empty placeholder. Either way the
+ *  first `message_update` REPLACES that message wholesale, so no duplicate or
+ *  dropped turn results. */
+export declare function applySnapshot(snapshot: BrokerSnapshot, previous?: ConvState): ConvState;
+/** Apply the broker's random choice for the newly received user message. */
+export declare function applyWorkingActivity(state: ConvState, activity: string): ConvState;
+/** Apply one broker-published structured summary without touching transcript ordering. */
+export declare function applyToolGroupSummary(state: ConvState, key: string, summary: ToolGroupSummary): ConvState;
+export declare function bashStart(state: ConvState, command: string, excludeFromContext?: boolean): ConvState;
+export declare function bashOutput(state: ConvState, chunk: string): ConvState;
+export declare function bashEnd(state: ConvState, result: {
+    exitCode: number | undefined;
+    cancelled: boolean;
+    truncated: boolean;
+    fullOutputPath?: string;
+}): ConvState;
+/** Apply one broker→client AGENT event (an `AgentSessionEvent`) to the transcript.
+ *  Broker control frames (welcome/model_changed/error/…) are handled by the hook,
+ *  NOT here — only pi agent events reach this function. Returns a NEW state object
+ *  (with fresh `messages`/`executingToolIds` only when they actually change) so
+ *  React re-renders correctly. */
+export declare function reduce(state: ConvState, event: AgentSessionEvent): ConvState;

package/dist/clients/conversation/projection.js

@@ -0,0 +1,324 @@
+// projection.ts — the surface-neutral reducer that turns a broker snapshot and
+// its live frames into one ordered transcript model. Renderers retain their own
+// folding and presentation; this module owns only wire-state reconciliation.
+import { normalizeToolGroupSummary, normalizeToolGroupSummaryRecord } from '../../shared/tool-groups.js';
+import { DEFAULT_WORKING_ACTIVITY } from '../../shared/working-activity.js';
+export function initialConvState() {
+    return {
+        messages: [],
+        streamingIndex: null,
+        executingToolIds: new Set(),
+        partialToolResults: new Map(),
+        isStreaming: false,
+        activity: null,
+        workingActivity: DEFAULT_WORKING_ACTIVITY,
+        queued: [],
+        toolGroupSummaries: {},
+        toolGroupSummaryDetails: {},
+    };
+}
+/** Rebuild the ephemeral reconciliation fields from a persisted transcript cache. */
+export function restoreConvState(entry) {
+    const lastIndex = entry.messages.length - 1;
+    return {
+        ...initialConvState(),
+        messages: entry.messages,
+        streamingIndex: entry.isStreaming && lastIndex >= 0 ? lastIndex : null,
+        isStreaming: entry.isStreaming,
+        activity: entry.activity,
+        workingActivity: entry.isStreaming && entry.activity !== null ? entry.activity : DEFAULT_WORKING_ACTIVITY,
+        toolGroupSummaries: textToolGroupSummaries(entry.toolGroupSummaries),
+        toolGroupSummaryDetails: normalizeToolGroupSummaryRecord(entry.toolGroupSummaries),
+    };
+}
+/** An empty assistant message shaped so the next `message_update`/`message_end`
+ *  (which replace, not append — see `reduce`'s `message_update` case) has a
+ *  slot to land on. */
+function placeholderAssistant() {
+    return { role: 'assistant', content: [] };
+}
+/** Seed state from the broker's catch-up snapshot.
+ *
+ *  `welcome.snapshot` is the PERSISTED history (`snapshotMessages()` in the
+ *  broker), not the live in-memory array. During an active turn — after
+ *  `message_start`, before `message_end` — the in-flight assistant message may
+ *  not be persisted yet, so a mid-stream `welcome` can report
+ *  `state.isStreaming: true` with no trailing assistant in the snapshot.
+ *  Wholesale-replacing in that case (as we always did) drops the in-flight
+ *  turn: `streamingIndex` resets to null and the next `message_update`/
+ *  `message_end` has nothing to land on (see `reduce`).
+ *
+ *  So: idle snapshots replace wholesale exactly as before. Streaming snapshots
+ *  reconcile — if the persisted history already ends in an assistant, adopt
+ *  it as the streaming target; otherwise adopt the caller-supplied `previous`
+ *  state's in-flight assistant (a cache-first render or an earlier live
+ *  session) if one exists, or synthesize an empty placeholder. Either way the
+ *  first `message_update` REPLACES that message wholesale, so no duplicate or
+ *  dropped turn results. */
+export function applySnapshot(snapshot, previous) {
+    const messages = snapshot.messages;
+    const toolGroupSummaryDetails = snapshotToolGroupSummaries(snapshot);
+    const toolGroupSummaries = summaryTexts(toolGroupSummaryDetails);
+    const isStreaming = snapshot.state?.isStreaming === true;
+    const workingActivity = snapshotWorkingActivity(snapshot);
+    const queued = snapshotQueued(snapshot);
+    if (!isStreaming) {
+        return {
+            messages,
+            streamingIndex: null,
+            executingToolIds: new Set(),
+            partialToolResults: new Map(),
+            isStreaming: false,
+            activity: null,
+            workingActivity,
+            queued,
+            toolGroupSummaries,
+            toolGroupSummaryDetails,
+        };
+    }
+    const lastIdx = messages.length - 1;
+    if (lastIdx >= 0 && roleOf(messages[lastIdx]) === 'assistant') {
+        // The in-flight assistant is already in the persisted snapshot — adopt it.
+        return {
+            messages,
+            streamingIndex: lastIdx,
+            executingToolIds: new Set(),
+            partialToolResults: new Map(),
+            isStreaming: true,
+            activity: workingActivity,
+            workingActivity,
+            queued,
+            toolGroupSummaries,
+            toolGroupSummaryDetails,
+        };
+    }
+    // Not persisted yet — adopt the previous in-flight assistant if one was
+    // already rendered, else synthesize a placeholder.
+    const cachedAssistant = previous && previous.streamingIndex !== null ? previous.messages[previous.streamingIndex] : undefined;
+    const inFlightAssistant = cachedAssistant && roleOf(cachedAssistant) === 'assistant' ? cachedAssistant : placeholderAssistant();
+    const withInFlight = [...messages, inFlightAssistant];
+    return {
+        messages: withInFlight,
+        streamingIndex: withInFlight.length - 1,
+        executingToolIds: new Set(),
+        partialToolResults: new Map(),
+        isStreaming: true,
+        activity: workingActivity,
+        workingActivity,
+        queued,
+        toolGroupSummaries,
+        toolGroupSummaryDetails,
+    };
+}
+function snapshotWorkingActivity(snapshot) {
+    const activity = snapshot.workingActivity;
+    return typeof activity === 'string' && activity.trim() !== '' ? activity : DEFAULT_WORKING_ACTIVITY;
+}
+/** The queue a `welcome` reports, in the same order `queue_update` composes it.
+ *  Absent on a snapshot from a broker generation older than the field, and on
+ *  an offline node (which has no engine and so no queue) — both mean nothing is
+ *  waiting to run, which is exactly an empty queue. */
+function snapshotQueued(snapshot) {
+    const queued = snapshot.queued;
+    if (typeof queued !== 'object' || queued === null)
+        return [];
+    const { steering, followUp } = queued;
+    return [...texts(steering), ...texts(followUp)];
+}
+function texts(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
+}
+/** Apply the broker's random choice for the newly received user message. */
+export function applyWorkingActivity(state, activity) {
+    const next = activity.trim() === '' ? DEFAULT_WORKING_ACTIVITY : activity;
+    return state.workingActivity === next ? state : { ...state, workingActivity: next };
+}
+/** Snapshot additions are optional across broker generations. Invalid entries
+ * are absent rather than adapted, so every surface receives the canonical
+ * structured summary or no summary at all. */
+function snapshotToolGroupSummaries(snapshot) {
+    return normalizeToolGroupSummaryRecord(snapshot.toolGroupSummaries);
+}
+/** The web's compact recap is a presentation derived from canonical broker data. */
+function summaryTexts(summaries) {
+    return Object.fromEntries(Object.entries(summaries).map(([key, summary]) => [key, summary.bullets.join(' · ')]));
+}
+/** Legacy browser-cache entries retain their prior presentation strings; live
+ * snapshots and frames always rebuild these from the structured source. */
+function textToolGroupSummaries(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === 'string'));
+}
+/** Apply one broker-published structured summary without touching transcript ordering. */
+export function applyToolGroupSummary(state, key, summary) {
+    const normalized = key.trim() === '' ? null : normalizeToolGroupSummary(summary);
+    if (normalized === null)
+        return state;
+    return {
+        ...state,
+        toolGroupSummaries: { ...state.toolGroupSummaries, [key]: normalized.bullets.join(' · ') },
+        toolGroupSummaryDetails: { ...state.toolGroupSummaryDetails, [key]: normalized },
+    };
+}
+function roleOf(m) {
+    return m.role ?? '';
+}
+// `!` bash execution (broker bash_start/bash_output/bash_end frames). These are
+// broker control frames, NOT AgentSessionEvents, so the hook routes them here
+// explicitly. They build a synthetic `bashExecution` message in the transcript
+// that mirrors the one pi persists to context — rendered by MessageView.
+/** Index of the most recent bashExecution message (the active `!` run), or null. */
+function lastBashIndex(state) {
+    for (let i = state.messages.length - 1; i >= 0; i--) {
+        if (roleOf(state.messages[i]) === 'bashExecution')
+            return i;
+    }
+    return null;
+}
+export function bashStart(state, command, excludeFromContext) {
+    const msg = {
+        role: 'bashExecution',
+        command,
+        output: '',
+        exitCode: undefined,
+        cancelled: false,
+        truncated: false,
+        excludeFromContext,
+        timestamp: Date.now(),
+    };
+    return { ...state, messages: [...state.messages, msg] };
+}
+export function bashOutput(state, chunk) {
+    const idx = lastBashIndex(state);
+    if (idx === null)
+        return state;
+    const messages = [...state.messages];
+    const m = messages[idx];
+    messages[idx] = { ...m, output: `${m.output ?? ''}${chunk}` };
+    return { ...state, messages };
+}
+export function bashEnd(state, result) {
+    const idx = lastBashIndex(state);
+    if (idx === null)
+        return state;
+    const messages = [...state.messages];
+    const m = messages[idx];
+    messages[idx] = {
+        ...m,
+        exitCode: result.exitCode,
+        cancelled: result.cancelled,
+        truncated: result.truncated,
+        fullOutputPath: result.fullOutputPath,
+    };
+    return { ...state, messages };
+}
+/** Apply one broker→client AGENT event (an `AgentSessionEvent`) to the transcript.
+ *  Broker control frames (welcome/model_changed/error/…) are handled by the hook,
+ *  NOT here — only pi agent events reach this function. Returns a NEW state object
+ *  (with fresh `messages`/`executingToolIds` only when they actually change) so
+ *  React re-renders correctly. */
+export function reduce(state, event) {
+    switch (event.type) {
+        case 'agent_start':
+            return { ...state, isStreaming: true, activity: state.workingActivity };
+        case 'agent_end':
+        case 'agent_settled':
+            return {
+                ...state,
+                isStreaming: false,
+                activity: null,
+                streamingIndex: null,
+                executingToolIds: state.executingToolIds.size ? new Set() : state.executingToolIds,
+            };
+        case 'message_start': {
+            // User messages arrive complete on message_start (no streaming deltas).
+            const message = event.message;
+            const messages = [...state.messages, message];
+            const isAssistant = roleOf(message) === 'assistant';
+            let partialToolResults = state.partialToolResults;
+            if (roleOf(message) === 'toolResult') {
+                const id = message.toolCallId;
+                if (typeof id === 'string' && partialToolResults.has(id)) {
+                    const next = new Map(partialToolResults);
+                    next.delete(id);
+                    partialToolResults = next;
+                }
+            }
+            return {
+                ...state,
+                messages,
+                partialToolResults,
+                streamingIndex: isAssistant ? messages.length - 1 : state.streamingIndex,
+            };
+        }
+        case 'message_update': {
+            // Only assistant messages stream. Replace the in-progress message with the
+            // event's full `message`. If we attached mid-stream (no message_start seen),
+            // adopt the last message when it is the assistant being streamed.
+            let idx = state.streamingIndex;
+            if (idx === null) {
+                const last = state.messages.length - 1;
+                if (last >= 0 && roleOf(state.messages[last]) === 'assistant')
+                    idx = last;
+            }
+            if (idx === null)
+                return state;
+            const messages = [...state.messages];
+            messages[idx] = event.message;
+            return { ...state, messages, streamingIndex: idx };
+        }
+        case 'message_end': {
+            if (state.streamingIndex === null)
+                return state;
+            const messages = [...state.messages];
+            messages[state.streamingIndex] = event.message;
+            return { ...state, messages, streamingIndex: null };
+        }
+        case 'tool_execution_start': {
+            const next = new Set(state.executingToolIds);
+            next.add(event.toolCallId);
+            return { ...state, executingToolIds: next };
+        }
+        case 'tool_execution_update': {
+            const next = new Map(state.partialToolResults);
+            next.set(event.toolCallId, toolResultFromExecution(event.toolCallId, event.toolName, event.partialResult, false));
+            return { ...state, partialToolResults: next };
+        }
+        case 'tool_execution_end': {
+            const nextExecuting = new Set(state.executingToolIds);
+            nextExecuting.delete(event.toolCallId);
+            const nextResults = new Map(state.partialToolResults);
+            nextResults.set(event.toolCallId, toolResultFromExecution(event.toolCallId, event.toolName, event.result, event.isError));
+            return { ...state, executingToolIds: nextExecuting, partialToolResults: nextResults };
+        }
+        case 'compaction_start':
+            return { ...state, activity: 'Compacting context…' };
+        case 'compaction_end':
+            return { ...state, activity: state.isStreaming ? state.workingActivity : null };
+        case 'auto_retry_start':
+            return {
+                ...state,
+                activity: `Retrying (${event.attempt}/${event.maxAttempts}) in ${Math.ceil(event.delayMs / 1000)}s…`,
+            };
+        case 'auto_retry_end':
+            return { ...state, activity: state.isStreaming ? state.workingActivity : null };
+        case 'queue_update':
+            return { ...state, queued: [...event.steering, ...event.followUp] };
+        // turn_* / session_info_changed / thinking_level_changed — no transcript
+        // mutation in v1 (footer-only or covered by adjacent message events).
+        default:
+            return state;
+    }
+}
+function toolResultFromExecution(toolCallId, toolName, result, isError) {
+    const fields = typeof result === 'object' && result !== null ? result : {};
+    return {
+        role: 'toolResult',
+        toolCallId,
+        toolName,
+        ...fields,
+        content: Array.isArray(fields.content) ? fields.content : [],
+        isError,
+    };
+}

package/dist/clients/conversation/submit.d.ts

@@ -0,0 +1,38 @@
+export type SubmitClassification = {
+    kind: 'empty';
+} | {
+    kind: 'slash';
+    trimmed: string;
+} | {
+    kind: 'dormant';
+    text: string;
+    trimmed: string;
+} | {
+    kind: 'bash';
+    command: string;
+    excludeFromContext: boolean;
+    trimmed: string;
+} | {
+    kind: 'steer';
+    text: string;
+    trimmed: string;
+} | {
+    kind: 'prompt';
+    text: string;
+    trimmed: string;
+};
+/**
+ * Classify a text submission to determine the appropriate message kind.
+ *
+ * The branch order is load-bearing and must match the original handleSubmit order exactly:
+ * 1. Empty trim → nothing
+ * 2. Slash command → handled by the viewer caller
+ * 3. Dormant + can wake → dormant wake (if `canWakeDormant`)
+ * 4. Bash (! or !!) → bash
+ * 5. Streaming ? steer : prompt → prompt or steer
+ */
+export declare function classifySubmit(text: string, ctx: {
+    isDormant: boolean;
+    canWakeDormant: boolean;
+    isStreaming: boolean;
+}): SubmitClassification;

package/dist/clients/conversation/submit.js

@@ -0,0 +1,51 @@
+// conversation/submit.ts — classification of text submission intent.
+//
+// Extracted from InputController.handleSubmit (T-A4): classify user input before
+// deciding whether to dispatch a slash command, wake a dormant node, run bash,
+// or send a prompt/steer frame. The load-bearing branch order is preserved exactly:
+// empty-trim → slash → dormant (isDormant && canWakeDormant) → bash (! / !!) →
+// streaming ? steer : prompt.
+//
+// Caller applies slash dispatch, readOnlySlashRefusal, expandImagePlaceholders,
+// addToHistory, setText(''), and clearPastedImages() — this extraction is pure
+// classification, not control flow.
+/**
+ * Classify a text submission to determine the appropriate message kind.
+ *
+ * The branch order is load-bearing and must match the original handleSubmit order exactly:
+ * 1. Empty trim → nothing
+ * 2. Slash command → handled by the viewer caller
+ * 3. Dormant + can wake → dormant wake (if `canWakeDormant`)
+ * 4. Bash (! or !!) → bash
+ * 5. Streaming ? steer : prompt → prompt or steer
+ */
+export function classifySubmit(text, ctx) {
+    const trimmed = text.trim();
+    // Branch 1: empty-trim
+    if (!trimmed) {
+        return { kind: 'empty' };
+    }
+    // Branch 2: slash. Dispatch and read-only refusal remain caller-owned.
+    if (trimmed.startsWith('/')) {
+        return { kind: 'slash', trimmed };
+    }
+    // Branch 3: dormant
+    if (ctx.isDormant && ctx.canWakeDormant) {
+        return { kind: 'dormant', text, trimmed };
+    }
+    // Branch 4: bash
+    if (trimmed.startsWith('!')) {
+        const excludeFromContext = trimmed.startsWith('!!');
+        const command = trimmed.slice(excludeFromContext ? 2 : 1).trim();
+        if (command === '') {
+            // bare `!`/`!!` with no command → empty
+            return { kind: 'empty' };
+        }
+        return { kind: 'bash', command, excludeFromContext, trimmed };
+    }
+    // Branch 5: steer or prompt
+    if (ctx.isStreaming) {
+        return { kind: 'steer', text, trimmed };
+    }
+    return { kind: 'prompt', text, trimmed };
+}

package/dist/clients/dashboard/app.d.ts

@@ -0,0 +1,7 @@
+export interface DashboardOptions {
+    /** Profile to show; undefined means every profile (no profile toggle). */
+    profileId: string | undefined;
+    /** The dashboard's own directory — the default for a new conversation. */
+    cwd: string;
+}
+export declare function runDashboard(opts: DashboardOptions): Promise<void>;