@khorsheed/dsh-context-lens 0.0.0-stage → 0.1.0

package/lib/types/room.js

@@ -0,0 +1,101 @@
+export function emptyRoom() {
+    return { members: new Map(), dispatches: [], runs: new Map(), handoffs: [], decisions: [], seen: new Set() };
+}
+const str = (value) => typeof value === 'string' && value.length > 0 ? value : undefined;
+const num = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+/**
+ * Apply one `room/*` event. Unknown types and malformed payloads are ignored.
+ * @returns whether the event was a room event this module reads.
+ */
+export function applyRoomEvent(room, type, data, seq, at) {
+    if (!type.startsWith('room/'))
+        return false;
+    if (seq !== undefined) {
+        if (room.seen.has(seq))
+            return true;
+        room.seen.add(seq);
+    }
+    const d = (typeof data === 'object' && data !== null ? data : {});
+    switch (type) {
+        case 'room/member-added':
+        case 'room/member-updated': {
+            const id = str(d['id']), name = str(d['name']);
+            if (id !== undefined && name !== undefined)
+                room.members.set(id, name);
+            return true;
+        }
+        case 'room/dispatch': {
+            if (d['origin'] !== 'human' || seq === undefined || at === undefined)
+                return true;
+            const targets = Array.isArray(d['targets']) ? d['targets'].filter((t) => typeof t === 'string') : [];
+            room.dispatches.push({ seq, at, text: str(d['text']) ?? '', targets });
+            return true;
+        }
+        case 'room/run-state': {
+            const runId = str(d['runId']);
+            if (runId === undefined)
+                return true;
+            const [head, ...rest] = runId.split(':');
+            const dispatchSeq = Number(head);
+            if (!Number.isSafeInteger(dispatchSeq))
+                return true;
+            const run = room.runs.get(runId) ?? { runId, dispatchSeq, memberId: rest.join(':') };
+            const member = str(d['member']), state = str(d['state']), child = str(d['childSessionId']);
+            const startedAt = num(d['startedAt']), elapsed = num(d['elapsedMs']), childTurn = num(d['childTurn']);
+            if (member !== undefined)
+                run.member = member;
+            if (state !== undefined)
+                run.state = state;
+            if (startedAt !== undefined)
+                run.startedAt = startedAt;
+            if (startedAt !== undefined && elapsed !== undefined)
+                run.endedAt = startedAt + elapsed;
+            else if ((state === 'done' || state === 'failed') && at !== undefined)
+                run.endedAt ??= at;
+            if (child !== undefined)
+                run.childSessionId = child;
+            if (childTurn !== undefined)
+                run.childTurn = childTurn;
+            room.runs.set(runId, run);
+            return true;
+        }
+        case 'room/decision': {
+            const call = (typeof d['call'] === 'object' && d['call'] !== null ? d['call'] : undefined);
+            const id = str(d['id']), scenario = str(d['scenario']), outcome = str(d['outcome']);
+            if (call === undefined || id === undefined || scenario === undefined || outcome === undefined || seq === undefined || at === undefined)
+                return true;
+            const request = (typeof call['request'] === 'object' && call['request'] !== null ? call['request'] : {});
+            const failure = call['failure'];
+            const about = (typeof d['about'] === 'object' && d['about'] !== null ? d['about'] : {});
+            room.decisions.push({
+                id, seq, at, scenario, outcome, model: str(call['model']) ?? 'typesafe', about,
+                request: { state: (request['state'] ?? null), questions: (request['questions'] ?? null) },
+                ...str(d['rule']) === undefined ? {} : { rule: str(d['rule']) },
+                ...num(d['probability']) === undefined ? {} : { probability: num(d['probability']) },
+                ...num(call['latencyMs']) === undefined ? {} : { latencyMs: num(call['latencyMs']) },
+                ...typeof call['cached'] === 'boolean' ? { cached: call['cached'] } : {},
+                ...num(call['inputTokens']) === undefined ? {} : { inputTokens: num(call['inputTokens']) },
+                ...num(call['outputTokens']) === undefined ? {} : { outputTokens: num(call['outputTokens']) },
+                ...call['response'] === undefined ? {} : { response: call['response'] },
+                ...typeof failure?.reason === 'string' ? { failure: { reason: failure.reason, ...typeof failure.detail === 'string' ? { detail: failure.detail } : {} } } : {},
+            });
+            return true;
+        }
+        case 'room/coordinator': {
+            const memberId = str(d['memberId']);
+            if (memberId !== undefined && seq !== undefined && at !== undefined)
+                room.handoffs.push({ seq, at, memberId });
+            return true;
+        }
+        default:
+            return true;
+    }
+}
+/** The runs a dispatch started, in start order. */
+export function runsOf(room, dispatchSeq) {
+    return [...room.runs.values()].filter(run => run.dispatchSeq === dispatchSeq)
+        .sort((a, b) => (a.startedAt ?? 0) - (b.startedAt ?? 0));
+}
+/** A synthetic, stable panel address for a room round (far below any purpose bucket). */
+export const ROOM_TURN_BASE = -1_000_000;
+export const roomTurnSeq = (dispatchSeq) => ROOM_TURN_BASE - dispatchSeq;

package/lib/types/segmenter.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The four-segment split of one captured request: system / tools / history /
+ * added. History vs added compares message identity AND content against the previous
+ * request IN THE SAME SCOPE (durable message ids and content hashes
+ * otherwise); "added" therefore includes the previous response and its tool
+ * results, and a compaction that rewrote the surface shows up as new content —
+ * exactly what the model saw change.
+ *
+ * System rows are attributed to `system-prompt/assemble` sections by content:
+ * the capture renders each observed assembly (same interpolate-filter-join
+ * rules as the host's `renderPrompt`) and a system message whose text equals a
+ * rendered assembly splits into that assembly's named sections. Anything that
+ * fails to match stays one unattributed row — attribution is presentation,
+ * never worth faking.
+ *
+ * @module @khorsheed/dsh-context-lens/segmenter
+ */
+import type { CapturedRequest, SegmentItem, ToolDefItem } from './types.ts';
+import { type CapturedMessage } from './messages.ts';
+/** One tool definition as the waterfall carries it (host `ToolSchema`, structurally). */
+export interface CapturedToolSchema {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    deferLoading?: true;
+}
+/**
+ * One rendered `system-prompt/assemble` output, kept for content-matching
+ * against later requests' system messages.
+ */
+export interface AssemblyRecord {
+    /** The whole rendered prompt (sections interpolated, empties dropped, `\n\n`-joined). */
+    rendered: string;
+    /** Per-section rendered text, in assembly order. */
+    sections: {
+        name: string;
+        text: string;
+    }[];
+    at: number;
+}
+/** The previous request's diff baseline within one scope. */
+export interface ScopeFingerprint {
+    messageKeys: string[];
+    toolNames: string[];
+    /** The one-shot system slot text, for its freshness on the next request. */
+    systemSlot?: string;
+}
+/** Everything the split needs beyond the request's own payload. */
+export interface SegmentContext {
+    /** Previous request's fingerprint in this scope; absent for the scope's first request. */
+    previous?: ScopeFingerprint;
+    /** Recently observed assemblies, oldest first. */
+    assemblies: readonly AssemblyRecord[];
+    /** Resolve a tool-call id to its tool name (tool rows label themselves with it). */
+    resolveToolName?: (callId: string) => string | undefined;
+    /** Resolve a durable assistant message id to its producing request's generation time. */
+    turnFor?: (messageId: string) => number | undefined;
+    durationFor?: (messageId: string) => number | undefined;
+}
+/** The split result plus the fingerprint the scope's NEXT request diffs against. */
+export interface SegmentResult {
+    system: SegmentItem[];
+    tools: ToolDefItem[];
+    history: SegmentItem[];
+    added: SegmentItem[];
+    fingerprint: ScopeFingerprint;
+    /** 请求体总字符数（明细头右上）— system + tools + history + added 之和。 */
+    totalChars: number;
+}
+/** A `system-prompt/assemble` waterfall value, structurally (host `PromptAssembly`). */
+export interface CapturedAssembly {
+    sections: {
+        name: string;
+        text: string;
+        interpolate?: boolean;
+    }[];
+    variables: Record<string, string | undefined>;
+}
+/** Cap on retained assemblies; assemblies older than the last 32 never match again in practice. */
+export declare const ASSEMBLY_RING_CAP = 32;
+/**
+ * Record one post-waterfall assembly into the ring. Adjacent duplicates (a
+ * listener-free re-assembly between steps) collapse to one entry.
+ */
+export declare function recordAssembly(ring: AssemblyRecord[], assembly: CapturedAssembly, at: number): void;
+/** Split one request's payload into the four segments. Pure: no I/O, no clock. */
+export declare function splitRequest(input: {
+    /** All `options.messages`, normalized, in wire order. */
+    messages: CapturedMessage[];
+    /** `options.system` (one-shot callers), when present. */
+    systemSlot?: string;
+    /** `options.tools`, normalized. */
+    tools?: CapturedToolSchema[];
+    context: SegmentContext;
+}): SegmentResult;
+/** A late log backfill can supply the baseline that was missing at capture. */
+export declare function rebaseSegments(segments: CapturedRequest['segments'], current: ScopeFingerprint, previous: ScopeFingerprint): CapturedRequest['segments'];
+/** FNV-1a 32-bit — enough to keep id-less messages diffable, no crypto import needed. */
+export declare function contentHash(text: string): string;
+//# sourceMappingURL=segmenter.d.ts.map

package/lib/types/segmenter.js

@@ -0,0 +1,184 @@
+import { classifyMessage, messageKey, messageSourceLabel, previewLine, previewMessage, serializeMessage, toolCallNames, } from "./messages.js";
+/** Cap on retained assemblies; assemblies older than the last 32 never match again in practice. */
+export const ASSEMBLY_RING_CAP = 32;
+const VARIABLE_REFERENCE = /\{\{([a-z][a-z0-9_]*)\}\}/g;
+/**
+ * Interpolate one section the way the host's renderer does, minus its error
+ * paths: a reference whose variable is missing keeps its literal form so the
+ * rendered text still lines up with whatever the host produced (or simply
+ * fails to match, degrading attribution to a single row).
+ */
+function interpolateSection(text, variables) {
+    return text.replace(VARIABLE_REFERENCE, (raw, name) => variables[name] ?? raw);
+}
+/**
+ * Record one post-waterfall assembly into the ring. Adjacent duplicates (a
+ * listener-free re-assembly between steps) collapse to one entry.
+ */
+export function recordAssembly(ring, assembly, at) {
+    const sections = assembly.sections
+        .map(section => ({
+        name: section.name,
+        text: section.interpolate === false ? section.text : interpolateSection(section.text, assembly.variables),
+    }))
+        .filter(section => section.text.length > 0);
+    const rendered = sections.map(section => section.text).join('\n\n');
+    const last = ring[ring.length - 1];
+    if (last !== undefined && last.rendered === rendered) {
+        last.at = at;
+        return;
+    }
+    ring.push({ rendered, sections, at });
+    if (ring.length > ASSEMBLY_RING_CAP)
+        ring.splice(0, ring.length - ASSEMBLY_RING_CAP);
+}
+/** Split one request's payload into the four segments. Pure: no I/O, no clock. */
+export function splitRequest(input) {
+    const { messages, context } = input;
+    const keys = messages.map(message => messageKey(message, contentHash));
+    const freshnessByIndex = messageFreshness(keys, context.previous);
+    const previousToolNames = new Set(context.previous?.toolNames ?? []);
+    const system = [];
+    if (input.systemSlot !== undefined && input.systemSlot.length > 0) {
+        system.push({
+            // The system slot sits ahead of the message array on the wire; -1 marks
+            // "not a message-slot position".
+            index: -1,
+            category: 'system',
+            source: 'system',
+            preview: previewLine(input.systemSlot),
+            full: input.systemSlot,
+            chars: input.systemSlot.length,
+            freshness: context.previous?.systemSlot === input.systemSlot ? 'history' : 'new',
+        });
+    }
+    const history = [];
+    const added = [];
+    messages.forEach((message, index) => {
+        const freshness = freshnessByIndex[index];
+        if (message.role === 'system') {
+            system.push(...attributeSystem(message, index, freshness, context.assemblies));
+            return;
+        }
+        const full = serializeMessage(message);
+        const toolCalls = message.role === 'assistant' ? toolCallNames(message) : [];
+        const durationMs = message.role === 'assistant' && message.id !== undefined
+            ? context.durationFor?.(message.id)
+            : undefined;
+        const sourceTurn = message.sourceTurn ?? (message.id === undefined ? undefined : context.turnFor?.(message.id));
+        const item = {
+            index,
+            ...message.id === undefined ? {} : { messageId: message.id },
+            ...message.compactionId === undefined ? {} : { compactionId: message.compactionId },
+            ...message.pruning === undefined ? {} : { pruning: message.pruning },
+            category: classifyMessage(message),
+            source: messageSourceLabel(message, message.toolCallId === undefined ? undefined : context.resolveToolName?.(message.toolCallId)),
+            ...toolCalls.length > 0 ? { toolCalls } : {},
+            preview: previewMessage(message),
+            full,
+            chars: full.length,
+            ...durationMs === undefined ? {} : { durationMs },
+            ...message.isError === undefined ? {} : { isError: message.isError },
+            ...message.toolCallId === undefined ? {} : { toolCallId: message.toolCallId },
+            ...sourceTurn === undefined ? {} : { sourceTurn },
+            freshness,
+        };
+        (freshness === 'history' ? history : added).push(item);
+    });
+    const tools = (input.tools ?? []).map(tool => {
+        const parameters = JSON.stringify(tool.parameters, null, 1);
+        return {
+            name: tool.name,
+            description: tool.description,
+            parameters,
+            chars: tool.name.length + tool.description.length + parameters.length,
+            added: context.previous !== undefined && !previousToolNames.has(tool.name),
+        };
+    });
+    const totalChars = system.reduce((n, item) => n + item.chars, 0)
+        + tools.reduce((n, item) => n + item.chars, 0)
+        + history.reduce((n, item) => n + item.chars, 0)
+        + added.reduce((n, item) => n + item.chars, 0);
+    return {
+        system,
+        tools,
+        history,
+        added,
+        fingerprint: {
+            messageKeys: keys,
+            toolNames: (input.tools ?? []).map(tool => tool.name),
+            ...input.systemSlot === undefined ? {} : { systemSlot: input.systemSlot },
+        },
+        totalChars,
+    };
+}
+/** Match occurrences, preserving unchanged tails across surface replacements. */
+function messageFreshness(keys, previous) {
+    const remaining = new Map();
+    for (const key of previous?.messageKeys ?? [])
+        remaining.set(key, (remaining.get(key) ?? 0) + 1);
+    return keys.map(key => {
+        const count = remaining.get(key) ?? 0;
+        if (count > 0)
+            remaining.set(key, count - 1);
+        return count > 0 ? 'history' : 'new';
+    });
+}
+/** A late log backfill can supply the baseline that was missing at capture. */
+export function rebaseSegments(segments, current, previous) {
+    const freshness = messageFreshness(current.messageKeys, previous);
+    const refresh = (item) => ({ ...item, freshness: item.index === -1
+            ? current.systemSlot === previous.systemSlot ? 'history' : 'new'
+            : freshness[item.index] ?? item.freshness });
+    const messages = [...segments.history, ...segments.added].sort((a, b) => a.index - b.index).map(refresh);
+    const tools = new Set(previous.toolNames);
+    return {
+        system: segments.system.map(refresh),
+        tools: segments.tools.map(tool => ({ ...tool, added: !tools.has(tool.name) })),
+        history: messages.filter(item => item.freshness === 'history'),
+        added: messages.filter(item => item.freshness === 'new'),
+    };
+}
+/** Attribute one system message to assembly sections when its text matches a rendered assembly exactly. */
+function attributeSystem(message, index, freshness, assemblies) {
+    const full = serializeMessage(message);
+    for (let i = assemblies.length - 1; i >= 0; i -= 1) {
+        const assembly = assemblies[i];
+        if (assembly === undefined || assembly.rendered !== full || assembly.sections.length === 0)
+            continue;
+        return assembly.sections.map(section => ({
+            index,
+            ...message.id === undefined ? {} : { messageId: message.id },
+            ...message.compactionId === undefined ? {} : { compactionId: message.compactionId },
+            ...message.pruning === undefined ? {} : { pruning: message.pruning },
+            category: 'system',
+            source: section.name,
+            preview: previewLine(section.text),
+            full: section.text,
+            chars: section.text.length,
+            ...message.isError === undefined ? {} : { isError: message.isError },
+            ...message.toolCallId === undefined ? {} : { toolCallId: message.toolCallId },
+            ...message.sourceTurn === undefined ? {} : { sourceTurn: message.sourceTurn },
+            freshness,
+        }));
+    }
+    return [{
+            index,
+            ...message.id === undefined ? {} : { messageId: message.id },
+            category: 'system',
+            source: message.sourceKind,
+            preview: previewLine(full),
+            full,
+            chars: full.length,
+            freshness,
+        }];
+}
+/** FNV-1a 32-bit — enough to keep id-less messages diffable, no crypto import needed. */
+export function contentHash(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i += 1) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(36);
+}

package/lib/types/service.d.ts

@@ -0,0 +1,145 @@
+import type { SessionTrend } from './types.ts';
+/**
+ * The context-lens service core: wires the three read-only capture lanes
+ * into the host and answers the Remote face's queries from the store.
+ *
+ * Lanes:
+ * 1. **`llm/stream`** (primary, full fidelity) — a waterfall tee that snapshots
+ *    the frozen `GenerateOptions` at dispatch and forwards every chunk
+ *    unchanged while recording block timing, usage, and tool-call identity.
+ * 2. **`system-prompt/assemble`** — records each post-waterfall assembly into
+ *    the section-attribution ring (read-only: always returns `next()`'s value).
+ * 3. **`session/event`** — turn brackets, the user query preview, closing
+ *    assistant message ids, tool exec pairing, and `subagent/catalog` scope
+ *    correlation.
+ *
+ * The fourth input is the **log lane** (`sessionPersistence`, lazy): child
+ * scopes of fresh-process `subagent_dsh` runs fill from the child's on-disk
+ * log (the parent's waterfall never sees those requests), and a session's
+ * pre-mount turns reconstruct from its own log — once per session at first
+ * query, budgeted behind the live turns (the history backfill).
+ *
+ * Capture is observation, never interception: any capture-internal failure is
+ * logged and the model path forwards untouched (the tee degrades to a bare
+ * `next()`; listener bodies are individually contained).
+ *
+ * @module @khorsheed/dsh-context-lens/service
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { CapturedRequest, ListTurnsResult, ScopeFilter, ScopedRefusal, TurnOverview, TurnTiming } from './types.ts';
+import { type SessionLogReader } from './log-lane.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** The context-lens service core. */
+        requestInspector: InspectorService;
+    }
+}
+/** Plugin config: capture retention knobs. */
+export interface InspectorConfig {
+    /** Turns retained per session (oldest evicted first, backfilled before live). Default 30. */
+    maxTurnsPerSession?: number;
+    /** Log-reconstructed requests retained per session. Default 500. */
+    maxBackfillRequestsPerSession?: number;
+    /** Global budget of stored segment text characters. Default 150M (~150MB). */
+    maxStoredCharsTotal?: number;
+}
+/** Test seams: the clock, the persistence probe, and the warning sink. */
+export interface InspectorDeps {
+    now?: () => number;
+    /** Overrides the `sessionPersistence` probe (tests inject the fixture here). */
+    persistence?: SessionLogReader;
+    logger?: {
+        warn(message: string): void;
+    };
+    /** Overrides the instance epoch stamped on query results (restart invalidation tests). */
+    generation?: string;
+}
+/** The capture store's query face (Remote delegates here). */
+export declare class InspectorService {
+    readonly ctx: Context;
+    readonly config: InspectorConfig;
+    private readonly store;
+    private readonly disposers;
+    /** childId → open read handle (persistent: reads are offset-incremental). */
+    private readonly handles;
+    private readonly cursors;
+    /** In-flight refresh per childId — concurrent panel queries share one read. */
+    private readonly refreshing;
+    /** sessionId → the metering event (`compaction/summary` | `compaction/prune`) just seen; the host appends its replacement next. */
+    private readonly meters;
+    private readonly now;
+    private readonly logWarn;
+    private readonly persistenceOverride?;
+    constructor(ctx: Context, config?: InspectorConfig, deps?: InspectorDeps);
+    /**
+     * The waterfall tee: snapshot the (possibly deep-frozen) request at dispatch,
+     * then forward every chunk unchanged while observing. A capture-side failure
+     * at setup degrades to the bare downstream stream; mid-stream failures only
+     * lose the remaining observations.
+     */
+    private onStream;
+    private tee;
+    /**
+     * Record the post-waterfall assembly for section attribution. The returned
+     * value passes through unchanged — this listener observes, it never rewrites
+     * a prompt.
+     */
+    private onAssemble;
+    private onSessionEvent;
+    private dispatchSessionEvent;
+    /** The probed `sessionPersistence` service, when the composition mounts one. */
+    private reader;
+    /**
+     * Refresh the log-sourced child scopes of one session (query-time,
+     * incremental). A scope the query's {@link ScopeFilter} excludes is skipped
+     * outright — its log is not opened on an unauthorized query's behalf.
+     */
+    private refreshChildren;
+    private refreshChild;
+    private doRefreshChild;
+    /** Turn eviction drops the child cursors/handles whose scopes lived on it. */
+    private dropEvictedChildState;
+    /**
+     * Reconstruct the session's pre-mount history from its own log, once per
+     * session (the store's watermark holds). The read is one full pass at first
+     * query; the store keeps the newest turns that fit the budget behind the
+     * live ones. A not-yet-materialized log is transient (retry next query); any
+     * other read failure marks the session broken and stops hammering it.
+     */
+    /** Pair a surface replacement with what it shadowed, typed by the metering event right before it. */
+    private noteReplacement;
+    private backfillMainSession;
+    private doBackfillMainSession;
+    /**
+     * A session opened on its own whose log header names a `parentSession`:
+     * read the parent's log once for its title, the turn whose catalog row
+     * started this child, and that row's label. Best effort — an unreadable
+     * parent leaves just its id.
+     */
+    private resolveParent;
+    /**
+     * Light turn list of one session plus its backfill watermark. The optional
+     * {@link ScopeFilter} restricts rows and aggregates to the authorized
+     * scopes; absent is the unfiltered local semantics.
+     */
+    listTurns(sessionId: string, filter?: ScopeFilter): Promise<ListTurnsResult>;
+    /**
+     * Move the session's backfill window to the turns ending at `end` (the
+     * latest turns when null) and answer the refreshed turn list. Live turns
+     * stay; the window refills from the log in the same call.
+     */
+    loadTurns(sessionId: string, end: number | null, filter?: ScopeFilter): Promise<ListTurnsResult>;
+    /** One turn's scope/request overview, without segments. */
+    getTurn(sessionId: string, turnSeq: number, filter?: ScopeFilter): Promise<TurnOverview | undefined>;
+    /** One request's full four-segment breakdown (a {@link ScopedRefusal} when the filter excludes its scope). */
+    getRequest(sessionId: string, seq: number, filter?: ScopeFilter): Promise<CapturedRequest | ScopedRefusal | undefined>;
+    /** The declaring package from a registered tool's host-side origin tag (capability-catalog convention); absent when untagged. */
+    private toolOwner;
+    /** Read the session map through the same backfill and scope-filtered path. */
+    getSessionTrend(sessionId: string, filter?: ScopeFilter): Promise<SessionTrend>;
+    /** One turn's whole-turn timing aggregation. */
+    getTurnTiming(sessionId: string, turnSeq: number, filter?: ScopeFilter): Promise<TurnTiming | undefined>;
+    /** Release every session buffer, listener, and open child-log handle (plugin dispose). */
+    dispose(): void;
+}
+//# sourceMappingURL=service.d.ts.map