@askdkc/dsh-cli 0.11.7 → 0.12.0

package/node_modules/dsh-working-activity/lib/types/projection.d.ts

@@ -0,0 +1,168 @@
+/**
+ * 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 type { Lang } from './lang.js';
+import { type ActivityPhase, type TrackerConfig } from './status.js';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** Projection key a client reads: `useProjection('workingActivity')`. */
+export declare 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 declare const ACTIVITY_PROJECTION_STATE_VERSION = 6;
+/** 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. */
+declare const stateSchema: z.ZodObject<{
+    tracker: z.ZodUnknown;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+declare const viewSchema: z.ZodObject<{
+    phase: z.ZodEnum<{
+        idle: "idle";
+        tool: "tool";
+        waiting: "waiting";
+        thinking: "thinking";
+        done: "done";
+    }>;
+    line: z.ZodString;
+    live: z.ZodBoolean;
+    label: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodString>;
+    phrase: z.ZodOptional<z.ZodString>;
+    toolCount: z.ZodNumber;
+    phaseStartedAt: z.ZodNumber;
+    turnStartedAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+    lang: z.ZodEnum<{
+        zh: "zh";
+        en: "en";
+        ja: "ja";
+    }>;
+}, z.core.$strip>;
+/** 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 declare 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;
+};
+export {};

package/node_modules/dsh-working-activity/lib/types/projection.js

@@ -0,0 +1,162 @@
+/**
+ * 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 { ActivityTracker, TRACKER_SNAPSHOT_VERSION, } from './status.js';
+/** 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;
+/** 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']),
+});
+/**
+ * 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) {
+    const now = options.now ?? Date.now;
+    const trackerConfig = { ...options.trackerConfig, language: options.lang };
+    const fresh = () => 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) => {
+        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) => {
+        const state = raw;
+        // 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: () => ({ tracker: fresh().snapshot(), updatedAt: 0 }),
+        apply: (raw, event) => {
+            const state = raw;
+            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/lib/types/registration.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Register `activity/status` as a known session-event type in every
+ * reachable dsh-session copy. Idempotent; silently skips anchors whose
+ * resolution fails.
+ */
+export declare function registerActivityEventType(): void;

package/node_modules/dsh-working-activity/lib/types/registration.js

@@ -0,0 +1,94 @@
+/**
+ * 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';
+/**
+ * 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() {
+    const anchors = [import.meta.url, process.argv[1]].filter((anchor) => typeof anchor === 'string' && anchor.length > 0);
+    /** Realpaths already registered — split trees symlink heavily, and require caches by realpath. */
+    const registered = new Set();
+    for (const anchor of anchors) {
+        let req;
+        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, registered) {
+    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).KNOWN_SESSION_EVENT_TYPES?.add(ACTIVITY_EVENT_TYPE);
+    }
+    catch {
+        // No resolvable dsh-session copy from this anchor — nothing to register into.
+    }
+}