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

package/lib/types/service.js

@@ -0,0 +1,493 @@
+import { InspectorStore, scopeAuthorized } from "./store.js";
+import { recordAssembly } from "./segmenter.js";
+import { fromRequestMessage, serializeMessage } from "./messages.js";
+import { messageOfRow, meterOf, replacementFact, replacementFactsOf } from "./changes.js";
+import { foldLogRows, IN_PROCESS_PROVIDERS, isSessionLogReader, openCursor, reconstructSession, } from "./log-lane.js";
+/** The capture store's query face (Remote delegates here). */
+export class InspectorService {
+    ctx;
+    config;
+    store;
+    disposers;
+    /** childId → open read handle (persistent: reads are offset-incremental). */
+    handles = new Map();
+    cursors = new Map();
+    /** In-flight refresh per childId — concurrent panel queries share one read. */
+    refreshing = new Map();
+    /** sessionId → the metering event (`compaction/summary` | `compaction/prune`) just seen; the host appends its replacement next. */
+    meters = new Map();
+    now;
+    logWarn;
+    persistenceOverride;
+    constructor(ctx, config = {}, deps = {}) {
+        this.ctx = ctx;
+        this.config = config;
+        this.now = deps.now ?? Date.now;
+        this.logWarn = deps.logger?.warn.bind(deps.logger) ?? ((message) => ctx.logger.warn(message));
+        this.persistenceOverride = deps.persistence;
+        const storeConfig = {
+            ...config.maxTurnsPerSession === undefined ? {} : { maxTurnsPerSession: config.maxTurnsPerSession },
+            ...config.maxBackfillRequestsPerSession === undefined ? {} : { maxBackfillRequestsPerSession: config.maxBackfillRequestsPerSession },
+            ...config.maxStoredCharsTotal === undefined ? {} : { maxStoredCharsTotal: config.maxStoredCharsTotal },
+        };
+        this.store = new InspectorStore(storeConfig, {
+            now: this.now,
+            onTurnEvicted: (_sessionId, turn) => this.dropEvictedChildState(turn),
+            ...deps.generation === undefined ? {} : { generation: deps.generation },
+        });
+        this.disposers = [
+            ctx.on('llm/stream', (options, next) => this.onStream(options, next)),
+            ctx.on('system-prompt/assemble', (_assembly, _context, next) => this.onAssemble(next)),
+            ctx.on('session/event', (session, event) => this.onSessionEvent(session, event)),
+        ];
+    }
+    // ---------- lane 1: llm/stream (in-process, full fidelity) ----------
+    /**
+     * 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.
+     */
+    onStream(options, next) {
+        let request;
+        try {
+            request = this.store.beginRequest(snapshotOptions(options), this.now());
+        }
+        catch (error) {
+            this.logWarn(`context-lens: capture setup failed, forwarding uncaptured (${String(error)})`);
+            return next();
+        }
+        if (request === undefined)
+            return next();
+        return this.tee(request, next);
+    }
+    tee(request, next) {
+        const { store, now } = this;
+        const warn = this.logWarn;
+        return (async function* () {
+            let thrown;
+            try {
+                for await (const chunk of next()) {
+                    try {
+                        store.observeChunk(request, chunk, now());
+                    }
+                    catch (error) {
+                        warn(`context-lens: chunk observation dropped (${String(error)})`);
+                    }
+                    yield chunk;
+                }
+            }
+            catch (error) {
+                thrown = error;
+                throw error;
+            }
+            finally {
+                try {
+                    store.settleRequest(request, now(), thrown);
+                }
+                catch (error) {
+                    warn(`context-lens: request settlement dropped (${String(error)})`);
+                }
+            }
+        })();
+    }
+    // ---------- lane 2: system-prompt/assemble (read-only attribution feed) ----------
+    /**
+     * Record the post-waterfall assembly for section attribution. The returned
+     * value passes through unchanged — this listener observes, it never rewrites
+     * a prompt.
+     */
+    async onAssemble(next) {
+        const result = await next();
+        try {
+            recordAssembly(this.store.assemblyRing, result, this.now());
+        }
+        catch (error) {
+            this.logWarn(`context-lens: assembly record dropped (${String(error)})`);
+        }
+        return result;
+    }
+    // ---------- lane 3: session/event (turn brackets + tool pairing + catalog) ----------
+    onSessionEvent(session, event) {
+        try {
+            this.dispatchSessionEvent(session, event);
+        }
+        catch (error) {
+            this.logWarn(`context-lens: session event "${String(event.type)}" dropped (${String(error)})`);
+        }
+    }
+    dispatchSessionEvent(session, event) {
+        const sessionId = session.id;
+        const at = event.time;
+        const eventType = event.type;
+        this.noteReplacement(session, event);
+        this.store.noteLogActivity(sessionId);
+        if (eventType.startsWith('compaction/'))
+            this.store.noteCompaction(sessionId, eventType, event.data);
+        if (eventType.startsWith('room/')) {
+            this.store.noteRoomEvent(sessionId, eventType, event.data, event.seq, at);
+            return;
+        }
+        if (event.type === 'tool/result' && event.surfaceOp !== 'append') {
+            const original = session.eventAt(event.surfaceOp.startSeq);
+            if (original?.type === 'tool/result') {
+                this.store.notePruning(sessionId, event.data.message.id, serializeMessage(fromRequestMessage(original.data.message)).length, serializeMessage(fromRequestMessage(event.data.message)).length);
+            }
+            // A replacement updates context, not the original execution's result.
+            return;
+        }
+        switch (event.type) {
+            case 'turn/start':
+                this.store.turnStart(sessionId, event.data.turn, at, event.seq);
+                return;
+            case 'turn/end':
+                this.store.turnEnd(sessionId, event.data.turn, event.data.reason, at);
+                return;
+            case 'user/message': {
+                const message = fromRequestMessage(event.data);
+                if (message.compactionId !== undefined && event.surfaceOp !== 'append')
+                    this.store.noteCompaction(sessionId, 'compaction/applied', { compactionId: message.compactionId });
+                if (message.id)
+                    this.store.noteMessageTurn(sessionId, message.id);
+                this.store.noteUserMessage(sessionId, message.sourceKind, serializeMessage(message));
+                return;
+            }
+            case 'assistant/message':
+                this.store.noteMessageTurn(sessionId, event.data.message.id, event.data.turn);
+                this.store.noteAssistantMessage(sessionId, event.data.message.id);
+                return;
+            case 'tool/call':
+                this.store.toolCall(sessionId, event.data.callId, event.data.name, event.data.arguments, at);
+                return;
+            case 'tool/result': {
+                this.store.noteMessageTurn(sessionId, event.data.message.id, event.data.turn);
+                const message = fromRequestMessage(event.data.message);
+                this.store.toolResult(sessionId, event.data.message.toolCallId, event.data.message.isError === true, serializeMessage(message), at);
+                return;
+            }
+            default:
+                break;
+        }
+        // `subagent/catalog` belongs to the subagent package's SessionEventMap
+        // merge — read structurally so this plugin neither depends on that package
+        // nor breaks when the composition lacks it.
+        const type = event.type;
+        if (type === 'subagent/descriptor') {
+            const provider = event.data['provider'];
+            if (typeof provider === 'string') {
+                this.store.noteChildProvider(sessionId, provider);
+                if (!IN_PROCESS_PROVIDERS.has(provider))
+                    this.store.markLogDriven(sessionId);
+            }
+            return;
+        }
+        if (type === 'subagent/catalog') {
+            const data = event.data;
+            const childId = data['childId'];
+            if (typeof childId === 'string' && childId.length > 0) {
+                const label = data['label'];
+                this.store.subagentCatalog(sessionId, childId, typeof label === 'string' && label.length > 0 ? label : undefined, at);
+            }
+        }
+    }
+    // ---------- lane 4: child logs (fresh-process subagent fallback) ----------
+    /** The probed `sessionPersistence` service, when the composition mounts one. */
+    reader() {
+        if (this.persistenceOverride !== undefined)
+            return this.persistenceOverride;
+        try {
+            const candidate = this.ctx.get('sessionPersistence');
+            return isSessionLogReader(candidate) ? candidate : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * 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.
+     */
+    async refreshChildren(rootSessionId, filter) {
+        const reader = this.reader();
+        if (reader === undefined)
+            return;
+        const scopes = this.store.childScopes(rootSessionId);
+        await Promise.all(scopes.map(scope => scopeAuthorized(scope.scopeId, filter)
+            ? this.refreshChild(rootSessionId, scope.scopeId, reader, scope.live)
+            : Promise.resolve()));
+    }
+    refreshChild(rootSessionId, childId, reader, live) {
+        if (live)
+            return Promise.resolve();
+        const pending = this.refreshing.get(childId);
+        if (pending !== undefined)
+            return pending;
+        const job = this.doRefreshChild(rootSessionId, childId, reader)
+            .finally(() => {
+            this.refreshing.delete(childId);
+        });
+        this.refreshing.set(childId, job);
+        return job;
+    }
+    async doRefreshChild(rootSessionId, childId, reader) {
+        let cursor = this.cursors.get(childId);
+        if (cursor?.broken !== undefined)
+            return;
+        if (cursor === undefined) {
+            cursor = openCursor();
+            this.cursors.set(childId, cursor);
+        }
+        try {
+            let handle = this.handles.get(childId);
+            if (handle === undefined) {
+                handle = await reader.open(childId, 'read');
+                this.handles.set(childId, handle);
+            }
+            const { events } = await handle.read(cursor.consumed);
+            const descriptor = events.find(row => row.type === 'subagent/descriptor');
+            const provider = descriptor?.data?.['provider'];
+            if (typeof provider === 'string')
+                this.store.noteChildProvider(childId, provider);
+            for (const request of foldLogRows(cursor, events)) {
+                this.store.appendLogRequest(rootSessionId, childId, request);
+            }
+            this.store.refreshExecutionResults(rootSessionId, childId);
+        }
+        catch (error) {
+            // A not-yet-materialized child log is transient (the child process flushes
+            // on its own schedule) — retry on the next refresh. Anything else is a
+            // durable unreadability (format drift, unknown event vocabulary): stop
+            // hammering it and keep the scope's honest empty state.
+            if (error instanceof Error && error.name === 'SessionPersistenceNotFoundError')
+                return;
+            cursor.broken = error instanceof Error ? error.message : String(error);
+            this.logWarn(`context-lens: child log "${childId}" unreadable (${cursor.broken})`);
+        }
+    }
+    /** Turn eviction drops the child cursors/handles whose scopes lived on it. */
+    dropEvictedChildState(turn) {
+        for (const scopeId of turn.scopes.keys()) {
+            if (scopeId === 'main')
+                continue;
+            this.cursors.delete(scopeId);
+            const handle = this.handles.get(scopeId);
+            if (handle !== undefined) {
+                this.handles.delete(scopeId);
+                void handle.close().catch(() => undefined);
+            }
+        }
+    }
+    // ---------- lane 5: main-session history backfill ----------
+    /**
+     * 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. */
+    noteReplacement(session, row) {
+        const meter = this.meters.get(session.id);
+        this.meters.delete(session.id);
+        const next = meterOf(row);
+        if (next !== undefined)
+            this.meters.set(session.id, next);
+        const fact = replacementFact(row, seq => {
+            const shadowed = session.eventAt(seq);
+            return shadowed === undefined ? undefined : messageOfRow(shadowed)?.id;
+        }, meter);
+        if (fact !== undefined)
+            this.store.noteReplacement(session.id, fact);
+    }
+    async backfillMainSession(sessionId) {
+        const reader = this.reader();
+        if (reader === undefined)
+            return;
+        // Retryable until complete: a partial fill re-reads on later queries
+        // (eviction may have freed room); the read is one zstd decode.
+        const state = this.store.backfillState(sessionId);
+        if (state === 'broken' || (state === 'complete' && !this.store.needsRequestNumbers(sessionId) && !this.store.needsLogRead(sessionId)))
+            return;
+        const jobKey = `main:${sessionId}`;
+        const pending = this.refreshing.get(jobKey);
+        if (pending !== undefined)
+            return pending;
+        const job = this.doBackfillMainSession(sessionId, reader)
+            .finally(() => {
+            this.refreshing.delete(jobKey);
+        });
+        this.refreshing.set(jobKey, job);
+        return job;
+    }
+    async doBackfillMainSession(sessionId, reader) {
+        try {
+            const handle = await reader.open(sessionId, 'read');
+            try {
+                const { events } = await handle.read(0);
+                // Materialize only the window's requests: every request carries its
+                // whole context, so a long log rebuilt at once grows quadratically.
+                const hosts = events.filter(row => row.type === 'turn/start')
+                    .map(row => row.data?.turn).filter((turn) => typeof turn === 'number');
+                // An external agent's own session: its requests reach only this log.
+                const provider = events.find(row => row.type === 'subagent/descriptor')?.data?.['provider'];
+                if (typeof provider === 'string' && !IN_PROCESS_PROVIDERS.has(provider))
+                    this.store.markLogDriven(sessionId);
+                const keep = this.store.windowHosts(sessionId, hosts);
+                this.store.insertLogTurns(sessionId, reconstructSession(events, host => host === undefined || keep.has(host)));
+                for (const fact of replacementFactsOf(events))
+                    this.store.noteReplacement(sessionId, fact);
+                for (const row of events) {
+                    if (row.type.startsWith('room/'))
+                        this.store.noteRoomEvent(sessionId, row.type, row.data, row.seq, row.time);
+                }
+                await this.resolveParent(sessionId, events, reader);
+            }
+            finally {
+                void handle.close().catch(() => undefined);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'SessionPersistenceNotFoundError')
+                return;
+            const reason = error instanceof Error ? error.message : String(error);
+            this.store.markBackfillBroken(sessionId, reason);
+            this.logWarn(`context-lens: session "${sessionId}" log unreadable, history backfill skipped (${reason})`);
+        }
+    }
+    /**
+     * 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.
+     */
+    async resolveParent(sessionId, events, reader) {
+        const header = events[0];
+        const parentId = header?.type === 'session' ? header.parentSession : undefined;
+        if (typeof parentId !== 'string' || parentId.length === 0 || this.store.hasParent(sessionId))
+            return;
+        const parent = { sessionId: parentId };
+        try {
+            const handle = await reader.open(parentId, 'read');
+            try {
+                const { events: rows } = await handle.read(0);
+                let turn;
+                for (const row of rows) {
+                    const data = (row.data ?? {});
+                    if (row.type === 'turn/start' && typeof data['turn'] === 'number')
+                        turn = data['turn'];
+                    if (row.type === 'session/title' && typeof data['title'] === 'string')
+                        parent.title = data['title'];
+                    if (row.type === 'subagent/catalog' && data['childId'] === sessionId) {
+                        if (turn !== undefined)
+                            parent.hostTurn = turn;
+                        if (typeof data['label'] === 'string')
+                            parent.label = data['label'];
+                    }
+                }
+            }
+            finally {
+                void handle.close().catch(() => undefined);
+            }
+        }
+        catch {
+            // The id alone still says whose child this is.
+        }
+        this.store.noteParent(sessionId, parent);
+    }
+    // ---------- queries (the Remote face delegates here) ----------
+    /**
+     * 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.
+     */
+    async listTurns(sessionId, filter) {
+        await this.backfillMainSession(sessionId);
+        await this.refreshChildren(sessionId, filter);
+        return this.store.listTurns(sessionId, filter);
+    }
+    /**
+     * 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.
+     */
+    async loadTurns(sessionId, end, filter) {
+        const pending = this.refreshing.get(`main:${sessionId}`);
+        if (pending !== undefined)
+            await pending;
+        this.store.setWindow(sessionId, end ?? undefined);
+        return this.listTurns(sessionId, filter);
+    }
+    /** One turn's scope/request overview, without segments. */
+    async getTurn(sessionId, turnSeq, filter) {
+        await this.backfillMainSession(sessionId);
+        await this.refreshChildren(sessionId, filter);
+        return this.store.getTurn(sessionId, turnSeq, filter);
+    }
+    /** One request's full four-segment breakdown (a {@link ScopedRefusal} when the filter excludes its scope). */
+    async getRequest(sessionId, seq, filter) {
+        await this.backfillMainSession(sessionId);
+        await this.refreshChildren(sessionId, filter);
+        const request = this.store.getRequest(sessionId, seq, filter);
+        const tools = request !== undefined && 'prefix' in request ? request.prefix?.toolChanges : undefined;
+        if (tools === undefined || tools.length === 0)
+            return request;
+        return { ...request, prefix: { ...request.prefix, toolChanges: tools.map(tool => {
+                    const owner = this.toolOwner(tool.name);
+                    return owner === undefined ? tool : { ...tool, owner };
+                }) } };
+    }
+    /** The declaring package from a registered tool's host-side origin tag (capability-catalog convention); absent when untagged. */
+    toolOwner(name) {
+        try {
+            const registry = this.ctx.get('tools');
+            const definition = registry?.get?.(name);
+            if (typeof definition !== 'object' || definition === null)
+                return undefined;
+            const origin = definition[Symbol.for('dsh.tool.origin')];
+            return typeof origin?.owner === 'string' ? origin.owner : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Read the session map through the same backfill and scope-filtered path. */
+    async getSessionTrend(sessionId, filter) {
+        await this.listTurns(sessionId, filter);
+        return this.store.getSessionTrend(sessionId, filter);
+    }
+    /** One turn's whole-turn timing aggregation. */
+    async getTurnTiming(sessionId, turnSeq, filter) {
+        await this.backfillMainSession(sessionId);
+        await this.refreshChildren(sessionId, filter);
+        return this.store.getTurnTiming(sessionId, turnSeq, filter);
+    }
+    /** Release every session buffer, listener, and open child-log handle (plugin dispose). */
+    dispose() {
+        for (const dispose of this.disposers.splice(0))
+            dispose();
+        this.store.dispose();
+        for (const handle of this.handles.values()) {
+            void handle.close().catch(() => undefined);
+        }
+        this.handles.clear();
+        this.cursors.clear();
+    }
+}
+/** The dispatch-time snapshot of one GenerateOptions (never mutates the frozen input). */
+function snapshotOptions(options) {
+    return {
+        ...options.sessionId === undefined ? {} : { sessionId: options.sessionId },
+        ...options.purpose === undefined ? {} : { purpose: options.purpose },
+        config: {
+            provider: options.provider,
+            model: options.model,
+            ...options.reasoningEffort === undefined ? {} : { reasoningEffort: options.reasoningEffort },
+            ...options.temperature === undefined ? {} : { temperature: options.temperature },
+            ...options.maxTokens === undefined ? {} : { maxTokens: options.maxTokens },
+        },
+        messages: options.messages.map(fromRequestMessage),
+        ...options.system === undefined ? {} : { systemSlot: options.system },
+        ...options.tools === undefined ? {} : { tools: options.tools },
+    };
+}