@askdkc/dsh-cli 0.11.7 → 0.12.0

package/node_modules/dsh-working-activity/src/projection.ts

@@ -0,0 +1,259 @@
+/**
+ * The `workingActivity` session projection — the Web transport for the line.
+ *
+ * The browser cannot see the host's in-process state, and the previous
+ * transport (appending `activity/status` events into the shared session log)
+ * made the log unreadable for other readers — the reason dsh-tui mounts this
+ * plugin with `publish: false`. A **session projection** is the supported
+ * replacement: the host folds committed events into a value and ships it to
+ * clients through the projection store, so nothing is written to the log.
+ *
+ * ## One definition, two host contract shapes
+ * The registry's definition contract changed between the corridors this package
+ * supports, and every spelling below is still live somewhere:
+ *
+ * | field | `0.1.0-rc.6` | `0.1.2-alpha.2` | `0.1.7-rc.2` |
+ * |---|---|---|---|
+ * | state schema | — (every unit ships) | `stateSchema` | `stateSchema` |
+ * | wire schema | `schema` | `viewSchema` | `wire.viewSchema` |
+ * | view | `view(state)` | `view(state)` | `wire.view(state)` |
+ * | `init` arguments | none | `header` | `header`, inherited count |
+ *
+ * Each `register` implementation reads only the fields it knows and ignores the
+ * rest, so the definition below carries **every spelling at once** and registers
+ * unchanged on any of them. That is cheaper and far more honest than probing a
+ * host version at runtime, and it keeps working for a corridor that mixed the
+ * spellings differently again.
+ *
+ * ## What a client gets, and what it must do itself
+ * The projection is event-driven: a value changes when a committed event folds,
+ * and never on its own. Elapsed seconds therefore CANNOT stream — the wire
+ * carries the timestamps (`phaseStartedAt`, `turnStartedAt`) and the client
+ * ticks locally. `line` is included as the host rendered it, which is exact for
+ * the settled phases and for any client that does not tick.
+ *
+ * ## Fold state is self-sufficient on purpose
+ * A checkpoint restores and then folds the log's tail without replaying the
+ * whole session, so the state must be resumable: it carries an opaque
+ * `ActivityTracker.snapshot()` plus the last folded event time. Checkpoints are
+ * persisted, which is what {@link ACTIVITY_PROJECTION_STATE_VERSION} gates —
+ * bump it whenever the tracker's snapshot shape changes.
+ * @module @deepseek-ai/dsh-working-activity/projection
+ */
+
+import { z } from 'zod'
+import { toActivityEvents } from './compat/session-events.js'
+import type { Lang } from './lang.js'
+import {
+  ActivityTracker,
+  TRACKER_SNAPSHOT_VERSION,
+  type ActivityPhase,
+  type TrackerConfig,
+} from './status.js'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+
+/** Projection key a client reads: `useProjection('workingActivity')`. */
+export const ACTIVITY_PROJECTION_KEY = 'workingActivity'
+
+/**
+ * Persisted-cache version of this unit's state. Derived from the tracker
+ * snapshot version, so a change to what the fold stores invalidates old
+ * checkpoints instead of forward-applying them into garbage.
+ */
+export const ACTIVITY_PROJECTION_STATE_VERSION = TRACKER_SNAPSHOT_VERSION
+
+/** The client-facing value of the `workingActivity` projection. */
+export interface WorkingActivityView {
+  /** Which phase the line is in; `idle` means "render nothing". */
+  readonly phase: ActivityPhase
+  /** The line as the host rendered it at `updatedAt`. */
+  readonly line: string
+  /** Whether `line` counts elapsed time and a client should tick it locally. */
+  readonly live: boolean
+  /** Tool action verb (the tool phase's short label), when there is one. */
+  readonly label?: string
+  /** Tool detail fragment (path / command / pattern), when there is one. */
+  readonly detail?: string
+  /** The playful phrase or `⏵` narration currently shown, when there is one. */
+  readonly phrase?: string
+  /** Tools completed in the current turn. */
+  readonly toolCount: number
+  /** Wall clock the current phase began (what a live `line` counts from). */
+  readonly phaseStartedAt: number
+  /** Wall clock the current turn began (0 when no turn has started). */
+  readonly turnStartedAt: number
+  /**
+   * Wall clock of the last folded event — the freshness signal a client needs
+   * to distrust a persisted `cached` row from a process that is gone. It is
+   * session time (event timestamps), not the moment the fold ran, so it stays
+   * meaningful across a restart.
+   */
+  readonly updatedAt: number
+  /** Language `line` was rendered in, so a ticking client matches its copy. */
+  readonly lang: Lang
+}
+
+/** Per-session fold state. Opaque outside this module (see the module doc). */
+interface ActivityProjectionState {
+  /** `ActivityTracker.snapshot()` of the session folded so far. */
+  readonly tracker: unknown
+  /** Timestamp of the last event that changed the fold. */
+  readonly updatedAt: number
+}
+
+/** Anything the tracker's snapshot refuses to parse is a stale checkpoint. */
+const stateSchema = z.object({
+  tracker: z.unknown(),
+  updatedAt: z.number(),
+})
+
+const viewSchema = z.object({
+  phase: z.enum(['idle', 'waiting', 'thinking', 'tool', 'done']),
+  line: z.string(),
+  live: z.boolean(),
+  label: z.string().optional(),
+  detail: z.string().optional(),
+  phrase: z.string().optional(),
+  toolCount: z.number(),
+  phaseStartedAt: z.number(),
+  turnStartedAt: z.number(),
+  updatedAt: z.number(),
+  lang: z.enum(['zh', 'en', 'ja']),
+})
+
+/** What a live host can overlay onto the folded value. */
+export interface LiveActivityOverlay {
+  /** The `⏵` narration most recently streamed for this session. */
+  readonly narration: string
+  /** When that narration arrived (its freshness clock). */
+  readonly lastChunkAt: number
+}
+
+/** Knobs a projection needs; all of them are also plugin configuration. */
+export interface ActivityProjectionOptions {
+  /** Behavioral knobs of the tracker to fold with. */
+  readonly trackerConfig: TrackerConfig
+  /** Custom action pools for tool copy. */
+  readonly customActions?: Readonly<Record<string, readonly string[]>>
+  /** Wall clock used to render the wire value (injectable for tests). */
+  readonly now?: () => number
+  /** Live UI language tag, so clients render in the same language. */
+  readonly lang: () => Lang
+  /**
+   * Live narration for one folded state, when the host has any.
+   *
+   * The narration is streamed, and a projection only folds committed events, so
+   * without this the projected line would never show the model's own words. The
+   * host keeps the frames and hands the freshest line over per read; the value
+   * still derives everything else from the log. Corridors whose registry has no
+   * `stateOf` (rc.6) simply never call this and fall back to the narration that
+   * settled messages carry.
+   */
+  readonly live?: (state: unknown) => LiveActivityOverlay | undefined
+}
+
+/**
+ * Build the `workingActivity` projection definition.
+ * @param options - tracker configuration, clock and language supplier.
+ * @returns a definition object registerable on every supported host corridor.
+ */
+export function createActivityProjection(options: ActivityProjectionOptions): {
+  key: string
+  stateVersion: number
+  stateSchema: typeof stateSchema
+  wire: { viewSchema: typeof viewSchema; view: (state: unknown) => WorkingActivityView }
+  schema: typeof viewSchema
+  viewSchema: typeof viewSchema
+  view: (state: unknown) => WorkingActivityView
+  init: () => ActivityProjectionState
+  apply: (state: unknown, event: SessionEvent) => ActivityProjectionState
+} {
+  const now = options.now ?? Date.now
+  const trackerConfig = { ...options.trackerConfig, language: options.lang }
+  const fresh = (): ActivityTracker =>
+    new ActivityTracker(trackerConfig, now, options.customActions)
+  // A checkpoint the tracker refuses is stale, not fatal: `view` runs inside
+  // the host's synchronous dispatch, and a same-version-but-unusable payload
+  // (torn write, hand-edited cache) must degrade to "fold from here" rather
+  // than throw through every listener. The host's own version gate still
+  // discards checkpoints from older builds before they get here.
+  const restoreOrFresh = (state: ActivityProjectionState): ActivityTracker => {
+    try {
+      return ActivityTracker.restore(
+        trackerConfig,
+        now,
+        options.customActions,
+        state.tracker,
+      )
+    } catch {
+      return fresh()
+    }
+  }
+
+  /**
+   * Render the current value. Called by the host when a fold changes and on
+   * every read, so the line it returns is as fresh as the read.
+   */
+  const view = (raw: unknown): WorkingActivityView => {
+    const state = raw as ActivityProjectionState
+    // One clock read for the whole value: rendering and deriving the turn's
+    // start instant from the rendered elapsed must agree exactly.
+    const at = now()
+    const tracker = restoreOrFresh(state)
+    // A projection folds durable events, but the `⏵` self-narration is born on
+    // live stream frames. The host that owns those frames overlays the freshest
+    // one here, so the value keeps the live narration without writing anything
+    // to the session log.
+    const live = options.live?.(state)
+    if (live !== undefined) tracker.applyLiveNarration(live.narration, live.lastChunkAt)
+    const rendered = tracker.render(at)
+    const running = rendered.phase !== 'idle' && rendered.phase !== 'done'
+    return {
+      phase: rendered.phase,
+      line: rendered.line,
+      live: running,
+      ...(rendered.label === undefined ? {} : { label: rendered.label }),
+      ...(rendered.detail === undefined ? {} : { detail: rendered.detail }),
+      ...(rendered.phrase === undefined ? {} : { phrase: rendered.phrase }),
+      toolCount: rendered.toolCount,
+      phaseStartedAt: rendered.phaseStartedAt,
+      // `ActivityState` reports elapsed rather than the turn's start instant.
+      // The difference is exact, and a client needs the instant to keep
+      // ticking; only the idle phase means "there is no turn" — an elapsed of
+      // zero is a turn that just started, not an absent one.
+      turnStartedAt: rendered.phase === 'idle' ? 0 : at - rendered.turnElapsedMs,
+      updatedAt: state.updatedAt,
+      lang: tracker.language(),
+    }
+  }
+
+  return {
+    key: ACTIVITY_PROJECTION_KEY,
+    stateVersion: ACTIVITY_PROJECTION_STATE_VERSION,
+    stateSchema,
+    wire: { viewSchema, view },
+    // The rc.6-era and alpha.2-era spellings of the same two fields (see the
+    // module doc): every register implementation reads only what it knows.
+    schema: viewSchema,
+    viewSchema,
+    view,
+    init: (): ActivityProjectionState => ({ tracker: fresh().snapshot(), updatedAt: 0 }),
+    apply: (raw: unknown, event: SessionEvent): ActivityProjectionState => {
+      const state = raw as ActivityProjectionState
+      const events = toActivityEvents(event)
+      // An event this unit does not model MUST return the same reference: the
+      // host treats it as "zero downstream work".
+      if (events.length === 0) return state
+      const tracker = restoreOrFresh(state)
+      for (const activityEvent of events) tracker.onEvent(activityEvent)
+      const next = tracker.snapshot()
+      const updatedAt = typeof event.time === 'number' ? event.time : state.updatedAt
+      // `next` is a fresh object by construction (`snapshot()` rebuilds), so
+      // content-comparing it against the previous state could only ever
+      // suppress the exotic same-millisecond no-op duplicate — while paying a
+      // double JSON serialization of the whole fold on EVERY modelled event.
+      // An occasional extra publish of an identical line is cheaper than that.
+      return { tracker: next, updatedAt }
+    },
+  }
+}

package/node_modules/dsh-working-activity/src/registration.ts

@@ -0,0 +1,99 @@
+/**
+ * Runtime registration of the `activity/status` session-event type.
+ *
+ * dsh-session's read paths (resume seed validation, persistence load)
+ * refuse any log containing a type outside KNOWN_SESSION_EVENT_TYPES unless
+ * every such event carries the envelope's `ignorable` marker — and
+ * `session.append()` exposes no ignorable flag, so this plugin's published
+ * snapshots used to make the whole session unresumable (and broke tolerant
+ * title reads). Upstream's catalog header defers a registration surface
+ * "until such a consumer exists" — this plugin is that consumer, so it
+ * registers its own type at load.
+ *
+ * Why "every reachable copy": a runtime can load dsh-session more than
+ * once. The dsh CLI tree and a plugin profile tree resolve different
+ * physical copies (e.g. rc.5 vs rc.6 during upgrade windows), and the
+ * strict validators consult only THEIR copy's Set. Registering through the
+ * plugin's own import alone would leave the validator's copy untouched.
+ * Anchors: this module (plugin/profile tree) and the process entry point
+ * (the CLI tree the persistence backend resolves from). Each anchor covers
+ * its own tree's top-level copy, then walks one edge further — through
+ * `@deepseek-ai/dsh-session-persistence`'s own resolution — because the
+ * strict validators (persistence load / resume seed checks) consult the
+ * copy THEY resolve, a third physical copy under nested or split-tree
+ * layouts that neither anchor's top-level resolution can reach. Copies are
+ * deduped by realpath; a copy that cannot be resolved from an anchor simply
+ * is not there; registration never throws.
+ *
+ * Self-adjusting per the compat house rules: when upstream's generated
+ * catalog adopts `activity/status` (or a real registration API ships), the
+ * add() calls are no-ops and this module can be deleted.
+ * @module dsh-working-activity/registration
+ */
+import { realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+
+/** The session-event type this plugin publishes. */
+const ACTIVITY_EVENT_TYPE = 'activity/status'
+
+/** The package whose own resolution chain leads to the validators' dsh-session copy. */
+const PERSISTENCE_PACKAGE = '@deepseek-ai/dsh-session-persistence'
+const SESSION_PACKAGE = '@deepseek-ai/dsh-session'
+
+interface KnownTypesModule {
+  KNOWN_SESSION_EVENT_TYPES?: Set<string>
+}
+
+/**
+ * Register `activity/status` as a known session-event type in every
+ * reachable dsh-session copy. Idempotent; silently skips anchors whose
+ * resolution fails.
+ */
+export function registerActivityEventType(): void {
+  const anchors = [import.meta.url, process.argv[1]].filter(
+    (anchor): anchor is string => typeof anchor === 'string' && anchor.length > 0,
+  )
+  /** Realpaths already registered — split trees symlink heavily, and require caches by realpath. */
+  const registered = new Set<string>()
+  for (const anchor of anchors) {
+    let req: NodeRequire
+    try {
+      req = createRequire(anchor)
+    } catch {
+      continue // Anchor not on disk (e.g. no argv[1] under some runners) — skip.
+    }
+    registerSessionCopy(req, registered)
+    // The validator edge: persistence's load()/resume seed checks consult
+    // THEIR OWN resolved dsh-session copy — a third physical copy under
+    // nested/split-tree layouts (CLI/profile split, rc.5↔rc.6 upgrade
+    // windows, pnpm nesting) that the anchor's top-level resolution misses.
+    try {
+      const persistenceReq = createRequire(req.resolve(PERSISTENCE_PACKAGE))
+      registerSessionCopy(persistenceReq, registered)
+    } catch {
+      // No persistence package reachable from this anchor — nothing more to cover.
+    }
+  }
+}
+
+/**
+ * Register into the dsh-session copy resolved by `req`, once per realpath.
+ * @param req - require anchored at the tree (or nested package) to probe.
+ * @param registered - realpaths already handled in this registration pass.
+ */
+function registerSessionCopy(req: NodeRequire, registered: Set<string>): void {
+  try {
+    const resolved = req.resolve(SESSION_PACKAGE)
+    let key = resolved
+    try {
+      key = realpathSync(resolved)
+    } catch {
+      // Vanished between resolve and realpath — dedupe by the resolved path.
+    }
+    if (registered.has(key)) return
+    registered.add(key)
+    ;(req(resolved) as KnownTypesModule).KNOWN_SESSION_EVENT_TYPES?.add(ACTIVITY_EVENT_TYPE)
+  } catch {
+    // No resolvable dsh-session copy from this anchor — nothing to register into.
+  }
+}