dsh-brief-sidebar 0.3.0

package/src/client/use-projection.ts

@@ -0,0 +1,117 @@
+/**
+ * Reading a live session projection from the client Session Controller.
+ *
+ * better-sidebar tab bodies are NOT rendered inside a DSH slot, so the
+ * framework's `useProjection` standard prop is not available to them. The
+ * equivalent face is reachable directly: the client Session Controller is a
+ * cordis service on the root context, and each session binding exposes its
+ * projections store (`SessionFace.projections.faceOf(key)`), which is the very
+ * observable `useProjection` resolves. Since it is a bare
+ * `{ getSnapshot, subscribe }` source, `useSyncExternalStore` binds it as-is —
+ * no local mirror, no folding, and the value reference only changes when the
+ * Host pushes a frame.
+ *
+ * Everything here is resolved defensively: a host without the Session
+ * Controller, or a session that is not open any more, degrades to "capability
+ * absent" (undefined) rather than throwing inside a render.
+ *
+ * This module is key-agnostic; the per-projection knowledge (which key, how to
+ * narrow the raw value) lives with the feature modules that call it.
+ */
+import { useCallback, useMemo, useSyncExternalStore } from 'react'
+import type { Context } from '@deepseek-ai/cordis'
+
+/** Structural view of a projection face (`ObservableSnapshot<unknown>`). */
+export interface ProjectionFace {
+  getSnapshot(): unknown
+  subscribe(listener: () => void): () => void
+}
+
+/** Structural view of one session binding's projection store. */
+export interface ProjectionsLike {
+  faceOf(key: string): ProjectionFace
+}
+
+/** Structural view of the client Session Controller face this plugin uses. */
+export interface SessionsLike {
+  binding(id: string): { readonly session: { readonly projections: ProjectionsLike } } | undefined
+}
+
+/** A no-op unsubscribe, kept as one identity so effects never thrash. */
+const NO_SUBSCRIBE = (): void => {}
+
+/** A source that never has a value — the absent-capability face. */
+const ABSENT: ProjectionFace = { getSnapshot: () => undefined, subscribe: () => NO_SUBSCRIBE }
+
+/**
+ * Whether a value really is a projection face.
+ *
+ * The store contract promises an identity-stable face for every key, so this
+ * never fires against a healthy host. It exists because the fallback is worse
+ * than the check: `useSyncExternalStore` would throw on a face-less key, and a
+ * thrown render is a blank sidebar rather than a diagnosable "unavailable".
+ */
+function isFace(value: unknown): value is ProjectionFace {
+  if (value === null || typeof value !== 'object') return false
+  const face = value as Partial<ProjectionFace>
+  return typeof face.getSnapshot === 'function' && typeof face.subscribe === 'function'
+}
+
+/**
+ * Resolve one projection face for one session.
+ *
+ * `ctx.get('sessions')` is the safe accessor (a direct `ctx.sessions` read can
+ * throw on a context that does not carry the service yet).
+ *
+ * @param ctx - the client root context handed to the tab body.
+ * @param sessionId - the tab's session scope; undefined means "no session".
+ * @param key - the projection key to resolve.
+ * @returns the projection face, or {@link ABSENT} when unreachable.
+ */
+export function resolveFace(ctx: Context | undefined, sessionId: string | undefined, key: string): ProjectionFace {
+  if (ctx === undefined || sessionId === undefined) return ABSENT
+  const sessions = ctx.get('sessions') as SessionsLike | undefined
+  if (sessions === undefined || typeof sessions.binding !== 'function') return ABSENT
+
+  const binding = sessions.binding(sessionId)
+  const projections = binding?.session?.projections
+  if (projections === undefined || typeof projections.faceOf !== 'function') return ABSENT
+
+  const face: unknown = projections.faceOf(key)
+  return isFace(face) ? face : ABSENT
+}
+
+/**
+ * Read one frame of a projection without subscribing.
+ *
+ * The one-shot sibling of {@link useProjectionValue}, for consumers that are
+ * not React components — the tab badge is a plain function called on every
+ * tab-bar render, so it must neither hold a subscription nor allocate one.
+ *
+ * @param ctx - the client root context.
+ * @param sessionId - the session whose projection is read.
+ * @param key - the projection key to read.
+ * @returns the raw snapshot: `undefined` while the capability is absent; the
+ *   semantics of any other value belong to the projection's own contract.
+ */
+export function projectionSnapshot(ctx: Context | undefined, sessionId: string | undefined, key: string): unknown {
+  return resolveFace(ctx, sessionId, key).getSnapshot()
+}
+
+/**
+ * Subscribe to one session projection by key.
+ *
+ * @param ctx - the client root context.
+ * @param sessionId - the session whose projection is shown.
+ * @param key - the projection key to subscribe to.
+ * @returns the raw snapshot value, identity-stable across frames the host did
+ *   not change. Narrowing is the caller's job.
+ */
+export function useProjectionValue(ctx: Context | undefined, sessionId: string | undefined, key: string): unknown {
+  const face = useMemo(() => resolveFace(ctx, sessionId, key), [ctx, sessionId, key])
+
+  const subscribe = useCallback((listener: () => void) => face.subscribe(listener), [face])
+  const getSnapshot = useCallback(() => face.getSnapshot(), [face])
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Node half of the brief sidebar plugin.
+ *
+ * The Cordis loader needs an entry point for the profile row; the browser half
+ * (`./client`, served by `dsh-client-modules`) renders the summary tab.
+ *
+ * Since the summary upgrade, this half owns ONE behaviour: contributing the
+ * `dshSummaryDeliverables` projection unit (see `./projection/register`), which
+ * folds successful mutation calls into a live produced-file feed. The
+ * contribution is optional — `registerDeliverablesProjection` waits for the
+ * `sessionProjections` service via `ctx.inject`, so a composition without the
+ * registry still loads this profile row and simply hides the deliverables
+ * section client-side.
+ *
+ * In particular this half still never touches the filesystem at load time: a
+ * profile row is instantiated on the boot path, and a synchronous read there
+ * would delay the host's startup. The fold is event-driven and stores paths
+ * only.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { registerDeliverablesProjection } from './projection/register'
+
+/** Profile row identity. */
+export const name = 'dsh-brief-sidebar'
+
+/**
+ * Node-face apply.
+ * @param ctx - the host context the loader hands this profile row.
+ */
+export function apply(ctx: Context): void {
+  registerDeliverablesProjection(ctx)
+}

package/src/projection/deliverables-fold.ts

@@ -0,0 +1,206 @@
+/**
+ * Host-side fold of produced-file facts — the projection unit state for
+ * `dshSummaryDeliverables`.
+ *
+ * The vocabulary is the one the harness's own deliverables experience uses
+ * (`ui-deliverables/turn-deliverables.ts`): the arguments of successful
+ * first-party mutation calls (`write`, `edit`, and the mutating
+ * `str_replace_editor` commands), never presentation data or prose. Reads,
+ * deletes, unsupported tools, malformed calls, and failed results contribute
+ * nothing; a file written and then edited in the same turn is one entry, in
+ * first-seen order.
+ *
+ * This module is deliberately PURE — no cordis, no zod, no IO — so the fold
+ * can be tested directly against hand-written event fixtures. The projection
+ * registry drives it once per committed `session/event`, which is what makes
+ * the produced list update mid-turn, the gap the official turn-tail row has.
+ */
+
+/** One bucket: the paths produced so far in one turn, first-seen order. */
+export interface DeliverablesTurnBucket {
+  readonly turn: number
+  readonly paths: readonly string[]
+}
+
+/** Fold state. Plain JSON, so the projection cache can persist it. */
+export interface DeliverablesState {
+  /** Turn number of the open (or latest seen) turn; 0 before the first turn. */
+  readonly turn: number
+  /** Open turn's `callId → mutation path` map (`null` = not a mutation call). */
+  readonly calls: Readonly<Record<string, { readonly turn: number; readonly path: string | null }>>
+  /** Paths accumulated in the latest turn so far (`null` before the first turn). */
+  readonly latest: DeliverablesTurnBucket | null
+  /** Every distinct produced path, most-recent-first, capped (see CAPS). */
+  readonly sessionPaths: readonly string[]
+  /** Distinct produced paths over the whole session, uncapped. */
+  readonly sessionTotal: number
+}
+
+/**
+ * Wire-view capacity bounds. The projection rides every event frame, so the
+ * lists are capped; the uncapped `sessionTotal` keeps the summary truthful
+ * beyond the cap.
+ */
+export const CAPS = {
+  /** Latest-turn paths kept in the wire view. */
+  latest: 50,
+  /** Session-wide paths kept in the wire view (most recent win). */
+  session: 100,
+} as const
+
+/** The fold's initial state: nothing has happened yet. */
+export function initDeliverablesState(): DeliverablesState {
+  return { turn: 0, calls: {}, latest: null, sessionPaths: [], sessionTotal: 0 }
+}
+
+/**
+ * Structural view of one committed session event. The registry hands the
+ * host's discriminated union; the fold only needs `type` and `data`, and the
+ * tool-event shapes mirror `dsh-session` types: `tool/call` carries
+ * `{ turn, step, callId, name, arguments }`, `tool/result` carries
+ * `{ turn, step, message: { content: [{ isError? }], source: { callId } } }`,
+ * `turn/start` carries `{ turn }`.
+ */
+export interface FoldEvent {
+  readonly type: string
+  readonly data: unknown
+}
+
+/**
+ * The next state after one committed event. Events the fold does not own
+ * return the SAME reference — an unchanged reference produces zero downstream
+ * work in the registry's `Object.is` drive.
+ *
+ * @param state - the state covering all prior events.
+ * @param event - the next committed session event.
+ * @returns the next state (same reference when nothing the fold tracks moved).
+ */
+export function applyDeliverablesEvent(state: DeliverablesState, event: FoldEvent): DeliverablesState {
+  if (event.type === 'turn/start') {
+    const turn = event.data as { turn?: unknown }
+    if (typeof turn?.turn !== 'number') return state
+    // Keep the previous turn's call records until its results settled; only
+    // older turns' unsettled entries are pruned (bounded-state hygiene).
+    const calls: Record<string, { readonly turn: number; readonly path: string | null }> = {}
+    for (const [id, entry] of Object.entries(state.calls)) {
+      if (entry.turn >= turn.turn - 1) calls[id] = entry
+    }
+    return { ...state, turn: turn.turn, calls, latest: { turn: turn.turn, paths: [] } }
+  }
+
+  if (event.type === 'tool/call') {
+    const call = event.data as { callId?: unknown; name?: unknown; arguments?: unknown }
+    if (typeof call?.callId !== 'string') return state
+    const path = typeof call.name === 'string' && typeof call.arguments === 'string'
+      ? mutationPath(call.name, call.arguments)
+      : null
+    return { ...state, calls: { ...state.calls, [call.callId]: { turn: state.turn, path } } }
+  }
+
+  if (event.type !== 'tool/result') return state
+
+  const result = event.data as {
+    message?: { content?: readonly { isError?: unknown }[]; source?: { callId?: unknown } }
+  }
+  const callId = result?.message?.source?.callId
+  if (typeof callId !== 'string') return state
+  if (result?.message?.content?.[0]?.isError === true) return state
+
+  const recorded = state.calls[callId]
+  const path = recorded?.path
+  if (path === undefined || path === null) return state
+
+  // A path written and edited again in the same turn is one bucket entry. A
+  // stray result that settles after a LATER turn opened never rewrites the
+  // newer bucket — its path still counts session-wide below.
+  const latest = state.latest
+  const sameTurn = latest !== null && latest.turn === recorded.turn
+  const nextLatest: DeliverablesTurnBucket | null = sameTurn && !latest.paths.includes(path)
+    ? { turn: latest.turn, paths: [...latest.paths, path].slice(-CAPS.latest) }
+    : latest
+
+  // Session-wide: distinct paths, most-recent-first, capped. The filter is
+  // non-empty-preserving, so a length change means the path was NEW here.
+  const withoutDuplicate = state.sessionPaths.filter(existing => existing !== path)
+  const sessionPaths = [path, ...withoutDuplicate].slice(0, CAPS.session)
+  const sessionTotal = withoutDuplicate.length === state.sessionPaths.length
+    ? state.sessionTotal + 1
+    : state.sessionTotal
+
+  return { ...state, latest: nextLatest, sessionPaths, sessionTotal }
+}
+
+/**
+ * Extract the path from a supported first-party mutation call.
+ *
+ * Ported from the harness deliverables fold so both carriers agree on what a
+ * "produced file" is. Session `tool/call` events are root calls; PTC dispatch
+ * children do not enter this fold independently.
+ *
+ * @param name - wire tool name.
+ * @param argsRaw - model-produced JSON arguments.
+ * @returns the mutation path, or null when the call is not a supported mutation.
+ */
+export function mutationPath(name: string, argsRaw: string): string | null {
+  let args: unknown
+  try {
+    args = JSON.parse(argsRaw) as unknown
+  } catch {
+    return null
+  }
+  if (!isRecord(args)) return null
+  switch (name) {
+    case 'write':
+      return typeof args.content === 'string' ? pathValue(args.file_path) : null
+    case 'edit':
+      return validEditArgs(args) ? pathValue(args.file_path) : null
+    case 'str_replace_editor':
+      return editorMutationPath(args)
+    default:
+      return null
+  }
+}
+
+/** Validate the fields that an `edit` execution requires. */
+function validEditArgs(args: Readonly<Record<string, unknown>>): boolean {
+  return typeof args.old_string === 'string'
+    && args.old_string.length > 0
+    && typeof args.new_string === 'string'
+    && args.old_string !== args.new_string
+    && (args.replace_all === undefined || typeof args.replace_all === 'boolean')
+}
+
+/** Extract a path only from a complete mutating editor command. */
+function editorMutationPath(args: Readonly<Record<string, unknown>>): string | null {
+  const path = pathValue(args.path)
+  if (path === null) return null
+  switch (args.command) {
+    case 'create':
+      return typeof args.file_text === 'string' ? path : null
+    case 'str_replace':
+      return typeof args.old_str === 'string'
+        && args.old_str.length > 0
+        && (args.new_str === undefined || typeof args.new_str === 'string')
+        ? path
+        : null
+    case 'insert':
+      return typeof args.insert_line === 'number'
+        && Number.isInteger(args.insert_line)
+        && args.insert_line >= 0
+        && typeof args.new_str === 'string'
+        ? path
+        : null
+    default:
+      return null
+  }
+}
+
+/** A non-blank path preserves the exact spelling supplied to the tool. */
+function pathValue(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value : null
+}
+
+/** Narrow parsed JSON to an argument object. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/projection/keys.ts

@@ -0,0 +1,27 @@
+/**
+ * The projection key this plugin contributes to the session-projection
+ * registry, and its wire view.
+ *
+ * The key is namespaced with the plugin name on purpose: the registry refuses
+ * to share a key across differing `stateVersion`s, so a collision with a
+ * future host-side deliverables unit would be a hard load error, not a silent
+ * shadow. The view type is declared structurally (the plugin has no compile
+ * dependency on `@deepseek-ai/dsh-session-projection`); the registry accepts
+ * any string key at runtime.
+ */
+
+/** The projection key registered by this plugin's host half. */
+export const DELIVERABLES_KEY = 'dshSummaryDeliverables'
+
+/** Client view of the produced-file fold (JSON-safe). */
+export interface DeliverablesView {
+  /** Paths produced in the latest turn, first-seen order (capped). */
+  readonly latest: {
+    readonly turn: number
+    readonly paths: readonly string[]
+  } | null
+  /** Distinct produced paths session-wide, most-recent-first (capped). */
+  readonly sessionPaths: readonly string[]
+  /** Distinct produced paths session-wide, uncapped — the truthful total. */
+  readonly sessionTotal: number
+}

package/src/projection/register.ts

@@ -0,0 +1,99 @@
+/**
+ * Registration of the `dshSummaryDeliverables` projection unit.
+ *
+ * The unit is an OPTIONAL contribution: a composition without the
+ * session-projection registry (or an older host) simply never registers it,
+ * and the client reads the key as capability absence — the deliverables
+ * section stays hidden. That is why this module routes through
+ * `ctx.inject(['sessionProjections'], …)` (wait for the service, register only
+ * when it appears) instead of declaring the service in the plugin's own
+ * `inject` list, which would make the whole profile row fail to load.
+ *
+ * The registry drives every registered unit once per committed session event
+ * and lazily replays the in-memory log for late units, so a session's history
+ * is folded even when this plugin mounts after work started.
+ */
+import { z } from 'zod'
+import type { Context } from '@deepseek-ai/cordis'
+import { applyDeliverablesEvent, CAPS, initDeliverablesState } from './deliverables-fold'
+import type { DeliverablesState } from './deliverables-fold'
+import { DELIVERABLES_KEY } from './keys'
+import type { DeliverablesView } from './keys'
+
+/**
+ * Structural view of the registry this plugin needs. Declared locally on
+ * purpose: the plugin has no compile dependency on the session-projection
+ * package, and `register` accepts any string key at runtime.
+ */
+interface ProjectionRegistryLike {
+  register(definition: {
+    key: string
+    stateSchema: { parse(value: unknown): unknown }
+    init(): DeliverablesState
+    apply(state: DeliverablesState, event: { type: string; data: unknown }): DeliverablesState
+    wire: { viewSchema: { parse(value: unknown): unknown }; view(state: DeliverablesState): DeliverablesView }
+    stateVersion: number
+  }): () => void
+}
+
+/** Zod schema of the fold state — validates persisted states before replay. */
+const stateSchema = z.object({
+  turn: z.number(),
+  calls: z.record(z.string(), z.object({ turn: z.number(), path: z.string().nullable() })),
+  latest: z.object({ turn: z.number(), paths: z.array(z.string()) }).nullable(),
+  sessionPaths: z.array(z.string()),
+  sessionTotal: z.number(),
+})
+
+/** Zod schema of the wire view — validates the payload before it leaves the host. */
+const viewSchema = z.object({
+  latest: z.object({ turn: z.number(), paths: z.array(z.string()) }).nullable(),
+  sessionPaths: z.array(z.string()),
+  sessionTotal: z.number(),
+})
+
+/**
+ * The view memo. The registry compares consecutive `view` results by
+ * `Object.is`, so a fresh object per event would republish the key on every
+ * unrelated frame. States are immutable references, so a WeakMap keyed by
+ * state reuses the view reference until the state really changes.
+ */
+const viewMemo = new WeakMap<DeliverablesState, DeliverablesView>()
+
+/** State → wire view, reference-stable across unchanged states. */
+function view(state: DeliverablesState): DeliverablesView {
+  const memoized = viewMemo.get(state)
+  if (memoized !== undefined) return memoized
+  const next: DeliverablesView = {
+    latest: state.latest === null
+      ? null
+      : { turn: state.latest.turn, paths: state.latest.paths.slice(-CAPS.latest) },
+    sessionPaths: state.sessionPaths.slice(0, CAPS.session),
+    sessionTotal: state.sessionTotal,
+  }
+  viewMemo.set(state, next)
+  return next
+}
+
+/**
+ * Register the deliverables projection as an optional contribution.
+ *
+ * @param ctx - the host context the plugin's `apply` receives.
+ * @returns nothing; the registration's disposer rides the injected fiber, so
+ *   unloading the plugin removes the key (clients then read capability absence).
+ */
+export function registerDeliverablesProjection(ctx: Context): void {
+  ctx.inject(['sessionProjections'], (injected) => {
+    const registry = (injected as unknown as { sessionProjections?: ProjectionRegistryLike })
+      .sessionProjections
+    if (registry === undefined || typeof registry.register !== 'function') return
+    registry.register({
+      key: DELIVERABLES_KEY,
+      stateSchema,
+      init: () => initDeliverablesState(),
+      apply: applyDeliverablesEvent,
+      wire: { viewSchema, view },
+      stateVersion: 0,
+    })
+  })
+}