@askdkc/dsh-cli 0.11.7 → 0.12.0

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

@@ -0,0 +1,350 @@
+/**
+ * working-activity — a live "working line" for DeepSeek Harness agents.
+ *
+ * Folds the durable session stream (turn/step/tool/stream events) plus
+ * `agent/status` into a playful real-time status line, then publishes it two
+ * ways, both optional:
+ *
+ * - TUI: registers the `${activity}` prompt slot on `ctx.tuiPrompt` when the
+ *   TUI is composed; add `${activity}` to `theme.leftPrompt` to see it.
+ * - Session log: appends log-only `activity/status` events (never surface
+ *   events) for Web and other UI consumers; replay ignores them.
+ *
+ * The state machine itself lives in `./status.ts` (pure, clock-injected); this
+ * module only wires events, the render tick, and the two sinks.
+ * @module @deepseek-ai/dsh-working-activity
+ */
+import { appendFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { ActivityTracker } from './status.js';
+import { feedStreamFrame } from './compat/assistant-stream.js';
+import { createActivityProjection, ACTIVITY_PROJECTION_KEY } from './projection.js';
+import { registerActivityEventType } from './registration.js';
+import { langNow, setLangOverride, t } from './lang.js';
+import { DEFAULT_PRESET } from './frames.js';
+import { featureOn } from './config.js';
+export const name = 'working-activity';
+// Explicit annotation: the inferred z.dict output references cosmokit's
+// Dict through a pnpm-virtual path, which is not portable in declaration
+// emit (TS2883) when the dependency graph shifts. The global `Schemastery`
+// interface comes from schemastery's own d.ts (declare global).
+export const Config = z.object({
+    phrases: z.boolean().default(true),
+    publish: z.boolean().default(false),
+    tickMs: z.number().step(50).min(100).max(5000).default(500),
+    publishIntervalMs: z.number().step(500).min(500).max(30_000).default(2000),
+    detailLimit: z.number().step(1).min(8).max(120).default(40),
+    customActions: z.dict(z.array(z.string())).default({}),
+    narrate: z.boolean().default(true),
+    lang: z.union(['auto', 'zh', 'en', 'ja', 'input']).default('auto'),
+    frames: z.string().default(DEFAULT_PRESET),
+    mode: z.union(['lively', 'minimal']).default('lively'),
+    features: z.dict(z.boolean()).default({}),
+    customPhrases: z.array(z.string()).default([]),
+    showTokPerSec: z.boolean().default(false),
+    workRemindAt: z.number().min(0).max(24).default(0),
+    debugLog: z.boolean().default(false),
+});
+/**
+ * Wire the working-activity plugin.
+ * @param ctx - Cordis context (agent loop + session services composed).
+ * @param config - Validated plugin config (schema defaults applied).
+ */
+export function apply(ctx, config = {}) {
+    // Register the event type BEFORE anything can publish or validate: the
+    // strict read paths (resume seed validation, persistence load) refuse
+    // logs with unknown non-ignorable types. Registration is unconditional —
+    // it also protects READING logs written by an earlier publish:true era
+    // in processes where publishing itself is off. See registration.ts.
+    registerActivityEventType();
+    const resolved = {
+        // `mode: minimal` renders functional labels only (pi extension parity).
+        phrases: config.phrases ?? config.mode !== 'minimal',
+        publish: config.publish ?? false,
+        tickMs: config.tickMs ?? 500,
+        publishIntervalMs: config.publishIntervalMs ?? 2000,
+        detailLimit: config.detailLimit ?? 40,
+        narrate: config.narrate ?? true,
+        lang: config.lang ?? 'auto',
+        customActions: config.customActions ?? {},
+        frames: config.frames ?? DEFAULT_PRESET,
+        mode: config.mode ?? 'lively',
+        features: config.features ?? {},
+        customPhrases: config.customPhrases ?? [],
+        showTokPerSec: config.showTokPerSec ?? false,
+        workRemindAt: config.workRemindAt ?? 0,
+        debugLog: config.debugLog ?? false,
+    };
+    // Trace target for {@link traceLine}: `~/.dsh-tui` mirrors where the UI keeps
+    // this plugin's config file; the env var redirects it (tests, bug reports).
+    const debugLogPath = resolved.debugLog
+        ? process.env.DSH_WORKING_ACTIVITY_DEBUG_LOG
+            ?? join(homedir(), '.dsh-tui', 'working-activity-debug.log')
+        : undefined;
+    // A pinned plugin-level language beats the env/file chain; releasing it on
+    // dispose restores `auto` for any other composition in the process.
+    setLangOverride(resolved.lang === 'input' ? 'auto' : resolved.lang);
+    ctx.effect(() => () => setLangOverride('auto'), 'working-activity lang override');
+    const runtimes = new Map();
+    /**
+     * The session whose line currently owns the single TUI prompt slot. The slot
+     * is one global seat with no notion of a foreground session, so the
+     * most-recently-active session keeps it; the per-session event log above is
+     * unaffected by this choice.
+     */
+    let slotSession;
+    // Optional TUI seam: no TUI composed -> no slot, no error. The register()
+    // call is itself effect-owned, so fiber disposal unregisters the slot.
+    const prompt = ctx.get('tuiPrompt', false);
+    const promptHandle = prompt?.register('activity', undefined);
+    // The `⏵` self-narration contract rides the stable system-prompt sections:
+    // injected when the systemPrompt service is composed (agent assemblies
+    // always mount it), removed with this fiber. The text is resolved at every
+    // assembly in the live language, so a `/lang` switch applies to the next
+    // turn without rebuilding the agent.
+    if (resolved.narrate) {
+        ctx.inject(['systemPrompt'], (promptCtx) => {
+            promptCtx.systemPrompt.section({
+                name: 'working-activity:narrate',
+                order: 60,
+                text: () => t('narrate-instruction'),
+            });
+        });
+    }
+    /** Tracker knobs shared by the live runtimes and the Web projection. */
+    // Feature flags resolve ONCE here (an explicit `features` entry beats the
+    // mode default) so every consumer applies the same gates. `features.phrases`
+    // folds into the master switch — the schema's `phrases` default must not
+    // mask a user's explicit `features: { phrases: false }`.
+    const fileLike = { features: resolved.features, mode: resolved.mode };
+    const on = (name) => featureOn(fileLike, name);
+    const trackerConfig = {
+        inputLanguage: resolved.lang === 'input',
+        phrases: resolved.phrases && on('phrases'),
+        detailLimit: resolved.detailLimit,
+        showIdle: false,
+        features: {
+            rareEggs: on('rareEggs'),
+            weekend: on('weekend'),
+            holidays: on('holidays'),
+            nightPhrases: on('nightPhrases'),
+            combo: on('combo'),
+            failPhrases: on('failPhrases'),
+            modelQuips: on('modelQuips'),
+            continuePhrases: on('continuePhrases'),
+        },
+        customPhrases: resolved.customPhrases,
+        showTokPerSec: resolved.showTokPerSec,
+        workRemindAt: resolved.workRemindAt,
+    };
+    // Web transport: a client-visible session projection. Registered only when the
+    // host provides the registry (the TUI-only composition does not), and only
+    // after it is mounted, hence `inject`. One definition serves both host
+    // contract shapes — see src/projection.ts for why that is a dual-spelling
+    // object rather than a version probe.
+    //
+    // The live narration overlay is keyed by the projection's own state object:
+    // `stateOf` is the only way back from a session to the state a read will see,
+    // and it exists on the current line but not on the rc.6-era registry — there
+    // the overlay stays empty and settled-message narration carries the line.
+    const liveNarration = new WeakMap();
+    /** The registry, once injected: `stateOf` is how the overlay finds its state. */
+    let projectionService;
+    /** Publish the tracker's current narration for the projected value to overlay. */
+    const noteLiveNarration = (session, tracker) => {
+        const state = projectionService?.stateOf?.(session, ACTIVITY_PROJECTION_KEY);
+        if (state === null || typeof state !== 'object')
+            return;
+        const narration = tracker.liveNarration();
+        if (narration === undefined)
+            return;
+        liveNarration.set(state, narration);
+    };
+    ctx.inject(['sessionProjections'], ((projectionCtx) => {
+        const registry = projectionCtx.sessionProjections;
+        if (registry === undefined)
+            return;
+        projectionService = registry;
+        registry.register(createActivityProjection({
+            trackerConfig,
+            customActions: resolved.customActions,
+            lang: langNow,
+            live: state => (state !== null && typeof state === 'object' ? liveNarration.get(state) : undefined),
+        }));
+    }));
+    const runtimeFor = (session) => {
+        let runtime = runtimes.get(session);
+        if (runtime === undefined) {
+            runtime = {
+                session,
+                tracker: new ActivityTracker(trackerConfig, Date.now, resolved.customActions),
+                lastPublishAt: 0,
+            };
+            runtimes.set(session, runtime);
+        }
+        return runtime;
+    };
+    /** Stop one runtime's pending wake-up. */
+    const stopTimer = (runtime) => {
+        if (runtime.timer === undefined)
+            return;
+        clearTimeout(runtime.timer);
+        runtime.timer = undefined;
+    };
+    /**
+     * Arm the next redraw, if this line has one coming.
+     *
+     * The tracker knows when its own line can next change (`nextWakeAt`), so an
+     * idle or settled line arms nothing at all — the idle CPU of a permanent
+     * 500 ms interval is what issue #14 reported. Live phases are additionally
+     * capped at the configured tick so a wrong estimate can only make the line
+     * fresher, never staler.
+     */
+    const armTimer = (runtime) => {
+        stopTimer(runtime);
+        const nowMs = Date.now();
+        const wakeAt = runtime.tracker.nextWakeAt(nowMs);
+        if (wakeAt === undefined)
+            return;
+        const phase = runtime.tracker.render(nowMs).phase;
+        const live = phase !== 'idle' && phase !== 'done';
+        const delayMs = Math.max(0, live ? Math.min(wakeAt - nowMs, resolved.tickMs) : wakeAt - nowMs);
+        runtime.timer = setTimeout(() => {
+            runtime.timer = undefined;
+            publish(runtime, runtime.tracker.render());
+            armTimer(runtime);
+        }, delayMs);
+        // A status line must never be the reason a process stays alive.
+        runtime.timer.unref();
+    };
+    /**
+     * Feed one runtime and republish. Callers snapshot the tracker state at event
+     * time and hand it here, so a burst of fast events (e.g. a synchronous tool
+     * call+result) cannot lose an intermediate phase; the append itself runs
+     * inside a microtask because the session's appending guard is still set while
+     * session/event callbacks run.
+     */
+    const feed = (runtime, state) => {
+        slotSession = runtime.session;
+        publish(runtime, state);
+        // A pending wake-up will refresh the line soon enough; re-arming on every
+        // streamed token would churn timers at the token rate.
+        if (runtime.timer === undefined)
+            armTimer(runtime);
+    };
+    /**
+     * Append one JSON line per distinct rendered line to the debug log (opt-in:
+     * {@link Config.debugLog}). The trace carries the derivation inputs — phase,
+     * copy pool, slot — because the line itself is derived, so this file is the
+     * only place "why did it say THAT" can be answered from.
+     */
+    const traceLine = (logPath, runtime, state) => {
+        if (state.line === runtime.lastLoggedLine)
+            return;
+        runtime.lastLoggedLine = state.line;
+        const at = Date.now();
+        const entry = {
+            at,
+            session: String(runtime.session.id ?? ''),
+            line: state.line,
+            ...runtime.tracker.describe(at),
+        };
+        void appendFile(logPath, `${JSON.stringify(entry)}\n`, 'utf8').catch(() => {
+            // A debug log that cannot be written (permissions, disk full) must
+            // never break the line itself.
+        });
+    };
+    /** Publish one rendered snapshot: TUI slot update + throttled session event. */
+    const publish = (runtime, state) => {
+        queueMicrotask(() => {
+            const line = state.phase === 'idle' ? undefined : state.line;
+            if (runtime.session === slotSession)
+                promptHandle?.set(line);
+            if (debugLogPath !== undefined)
+                traceLine(debugLogPath, runtime, state);
+            if (!resolved.publish)
+                return;
+            const nowMs = Date.now();
+            const lineChanged = state.line !== runtime.lastPublishedLine;
+            const phaseChanged = state.phase !== runtime.lastPublishedPhase;
+            // Live phases republish on a throttle so elapsed times stay current;
+            // settled phases (idle/done) publish only when the line itself changes.
+            const liveThrottle = state.phase !== 'idle' && state.phase !== 'done'
+                && nowMs - runtime.lastPublishAt >= resolved.publishIntervalMs;
+            if (!lineChanged && !phaseChanged && !liveThrottle)
+                return;
+            // Optional fields must be omitted (not undefined): session append rejects
+            // data JSON would discard, and `activity/status` is a lossless-JSON event.
+            const payload = {
+                phase: state.phase,
+                line: state.line,
+                toolCount: state.toolCount,
+                turnElapsedMs: state.turnElapsedMs,
+                phaseStartedAt: state.phaseStartedAt,
+                ...(state.label === undefined ? {} : { label: state.label }),
+                ...(state.detail === undefined ? {} : { detail: state.detail }),
+                ...(state.phrase === undefined ? {} : { phrase: state.phrase }),
+            };
+            try {
+                runtime.session.append('activity/status', payload);
+                runtime.lastPublishedLine = state.line;
+                runtime.lastPublishedPhase = state.phase;
+                runtime.lastPublishAt = nowMs;
+            }
+            catch {
+                // Session closed or the append guard still held: drop this snapshot;
+                // the next wake retries the same line.
+            }
+        });
+    };
+    ctx.on('session/event', (session, event) => {
+        const runtime = runtimeFor(session);
+        runtime.tracker.onSessionEvent(event);
+        // Re-key the live narration onto the fold's new state object: `apply`
+        // returns a fresh cell per fold, so without this the overlay would stay on
+        // the previous cell and a read right after a durable event (a tool
+        // starting, say) would lose the freshest `⏵` line until the next frame.
+        noteLiveNarration(session, runtime.tracker);
+        feed(runtime, runtime.tracker.render());
+    });
+    // Live model output. On the current host line the durable `assistant/chunk`
+    // event this plugin used to fold is gone — streamed deltas arrive as
+    // transient `agent/assistant-stream` frames instead — so the realtime half of
+    // the line (first-token promotion, `⏵` narration, tok/s) rides on these
+    // frames. Subscribed through a cast because the declared dev baseline
+    // (`@deepseek-ai/dsh-agent@0.1.0-rc.6`) predates the event; on that corridor
+    // the subscription simply never fires and the durable path above still runs.
+    // The cursor that orders frames lives with the emitting agent, so a replaced
+    // agent (whose revision restarts at 1) is never mistaken for a stale one.
+    ctx.on('agent/assistant-stream', (({ agent, frame }) => {
+        const runtime = runtimeFor(agent.session);
+        feedStreamFrame(runtime.tracker, agent, frame);
+        // Hand the freshest narration to the projected value as well: a projection
+        // folds committed events only, so without this overlay the line a client
+        // reads would never carry the model's own `⏵` words (see src/projection.ts).
+        noteLiveNarration(agent.session, runtime.tracker);
+        feed(runtime, runtime.tracker.render());
+    }));
+    ctx.on('session/disposed', (session) => {
+        const runtime = runtimes.get(session);
+        if (runtime !== undefined)
+            stopTimer(runtime);
+        runtimes.delete(session);
+        if (slotSession === session)
+            slotSession = undefined;
+    });
+    ctx.on('agent/status', ({ agent, status }) => {
+        const runtime = runtimeFor(agent.session);
+        runtime.tracker.onAgentStatus(status);
+        feed(runtime, runtime.tracker.render());
+    });
+    // No interval: each session's next redraw is armed from its own tracker
+    // (`nextWakeAt`), so idle and settled lines hold no timer at all. The effect
+    // disposer stops every pending wake-up when this fiber unloads.
+    ctx.effect(() => () => {
+        for (const runtime of runtimes.values())
+            stopTimer(runtime);
+    }, 'working-activity session timers');
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Package-owned `activity/status` snapshot invariants.
+ * @module dsh-working-activity/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "working-activity-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the working-activity invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;

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

@@ -0,0 +1,72 @@
+/**
+ * Package-owned `activity/status` snapshot invariants.
+ * @module dsh-working-activity/invariant
+ */
+/** Cordis companion plugin name. */
+export const name = 'working-activity-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+const PACKAGE_NAME = 'dsh-working-activity';
+const PHASES = new Set(['idle', 'waiting', 'thinking', 'tool', 'done']);
+/** Validate one published activity snapshot before it reaches the durable log. */
+function validateStatus(data, fail) {
+    const record = data;
+    if (record === null || typeof record !== 'object' || Array.isArray(record)) {
+        fail('activity/status data must be an object');
+        return;
+    }
+    if (typeof record.phase !== 'string' || !PHASES.has(record.phase)) {
+        fail(`activity/status carries unknown phase ${JSON.stringify(record.phase)}`);
+    }
+    if (typeof record.line !== 'string' || record.line.length === 0) {
+        fail('activity/status line must be a non-empty string');
+    }
+    for (const key of ['toolCount', 'turnElapsedMs', 'phaseStartedAt']) {
+        const value = record[key];
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+            fail(`activity/status ${key} must be a non-negative finite number`);
+        }
+    }
+    for (const key of ['label', 'detail', 'phrase']) {
+        if (record[key] !== undefined && typeof record[key] !== 'string') {
+            fail(`activity/status ${key} must be a string when present`);
+        }
+    }
+}
+/* jscpd:ignore-start -- package companions share replay and dispatch plumbing */
+/** Validate the package-owned event shape and ignore unrelated events. */
+function validateEvent(event, fail) {
+    if (event.type === 'activity/status')
+        validateStatus(event.data, fail);
+}
+/**
+ * The events of one already-loaded session across those two read shapes. A host
+ * exposing neither yields an empty log instead of aborting the companion: the
+ * bootstrap scan is best-effort, while the live `internal/dispatch` half must
+ * keep validating appended snapshots.
+ */
+function loadedEvents(session) {
+    if (typeof session.snapshotEvents === 'function')
+        return session.snapshotEvents();
+    return session.events ?? [];
+}
+/** Install validation for loaded and newly appended activity snapshots. */
+const install = Object.assign((ctx, fail) => {
+    for (const session of ctx.sessions.list()) {
+        for (const event of loadedEvents(session))
+            validateEvent(event, fail);
+    }
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName !== 'session/event')
+            return;
+        const event = args[1];
+        validateEvent(event, fail);
+    }, { global: true });
+}, { inject: ['sessions'] });
+/* jscpd:ignore-end */
+/**
+ * Register the working-activity invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));

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

@@ -0,0 +1,28 @@
+/** Japanese progress copy. Tool names and user-supplied details stay verbatim. */
+export declare const THINKING: readonly string[];
+export declare const THINKING_TIERS: readonly {
+    atMs: number;
+    pool: readonly string[];
+}[];
+export declare const WAITING: readonly string[];
+export declare const NIGHT: readonly string[];
+export declare const RARE: readonly string[];
+export declare const WEEKEND: readonly string[];
+export declare const RETRY: readonly string[];
+export declare const APPROVAL: readonly string[];
+export declare const COMPACTION_START: readonly string[];
+export declare const CONTINUE: readonly string[];
+export declare const COMPACT: readonly string[];
+export declare const OVERFLOW: readonly string[];
+export declare const COMPACT_RETRY: readonly string[];
+export declare const TOOL_OPENING: readonly string[];
+export declare const FAIL: readonly string[];
+export declare const DONE: readonly string[];
+export declare const NEW_YEAR: readonly string[];
+export declare const HOLIDAYS: Readonly<Record<string, readonly string[]>>;
+export declare const MODEL_QUIPS: Readonly<Record<string, readonly string[]>>;
+export declare const ACTION_MAP: readonly {
+    test: RegExp;
+    actions: readonly string[];
+}[];
+export declare const FALLBACK_ACTIONS: readonly string[];

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

@@ -0,0 +1,47 @@
+/** Japanese progress copy. Tool names and user-supplied details stay verbatim. */
+export const THINKING = ['考えています', '確認しています', '手順を整理しています'];
+export const THINKING_TIERS = [
+    { atMs: 300_000, pool: ['時間をかけて確認しています'] },
+    { atMs: 60_000, pool: ['引き続き調べています'] },
+    { atMs: 30_000, pool: ['もう少し確認しています'] },
+];
+export const WAITING = ['モデルの応答を待っています'];
+export const NIGHT = ['作業を続けています'];
+export const RARE = ['確認を進めています'];
+export const WEEKEND = ['作業を進めています'];
+export const RETRY = ['再試行を待っています'];
+export const APPROVAL = ['承認を待っています'];
+export const COMPACTION_START = ['会話を整理しています'];
+export const CONTINUE = ['作業を再開します'];
+export const COMPACT = ['会話を整理しました'];
+export const OVERFLOW = ['会話の整理を試みています'];
+export const COMPACT_RETRY = ['会話を整理し直しています'];
+export const TOOL_OPENING = ['ツールを使って確認します'];
+export const FAIL = ['ツールの実行に失敗しました'];
+export const DONE = ['完了しました'];
+export const NEW_YEAR = ['作業を進めています'];
+export const HOLIDAYS = {};
+export const MODEL_QUIPS = {
+    claude: ['Claude に切り替えました'],
+    gpt: ['GPT に切り替えました'],
+    grok: ['Grok に切り替えました'],
+    gemini: ['Gemini に切り替えました'],
+    deepseek: ['DeepSeek に切り替えました'],
+    haiku: ['Haiku に切り替えました'],
+    sonnet: ['Sonnet に切り替えました'],
+    opus: ['Opus に切り替えました'],
+    flash: ['Flash に切り替えました'],
+    pro: ['Pro に切り替えました'],
+    mini: ['Mini に切り替えました'],
+};
+export const ACTION_MAP = [
+    { test: /^(read|read_file|cat)$/i, actions: ['読み取り'] },
+    { test: /^(write|write_file|create_file)$/i, actions: ['書き込み'] },
+    { test: /^(edit|edit_file|str_replace|apply_patch|search_replace)$/i, actions: ['編集'] },
+    { test: /^(bash|shell|run|exec|powershell|cmd)$/i, actions: ['コマンド実行'] },
+    { test: /^(grep|rg|search|search_in_files|ffgrep)$/i, actions: ['検索'] },
+    { test: /^(find|glob|fffind)$/i, actions: ['ファイル検索'] },
+    { test: /^(subagent|agent|task)$/i, actions: ['サブエージェント実行'] },
+    { test: /^(web_search|browse|fetch)$/i, actions: ['Web 検索'] },
+];
+export const FALLBACK_ACTIONS = ['ツール実行'];

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

@@ -0,0 +1,140 @@
+/**
+ * Language resolution + copy dictionary for the working-activity plugin.
+ *
+ * The plugin follows the dsh-tui UI language without importing it: the same
+ * chain dsh-tui resolves (`DSH_TUI_LANG` env → `~/.dsh-tui/lang.json` → OS
+ * locale → zh) is read here directly, so a `/lang en|zh` switch (or the
+ * /settings language pick) hot-swaps this plugin's narration and status-line
+ * copy on the next render tick.
+ *
+ * Resolution order:
+ *   1. `setLangOverride()` — a plugin-level `lang: zh|en` config key
+ *      (cordis.yml) or an explicit test pin.
+ *   2. `DSH_TUI_LANG` env var — pinned at process start.
+ *   3. `~/.dsh-tui/lang.json` — the persisted dsh-tui choice, mtime-cached
+ *      so the per-tick status render never re-reads an unchanged file.
+ *   4. OS locale guess (`LC_ALL` / `LC_MESSAGES` / `LANG`); POSIX/C means
+ *      "no locale selected" and maps to English.
+ *   5. `zh` — the original hard-coded language.
+ *
+ * The dictionary is a flat key → per-language string map; `t(key, params)`
+ * substitutes `{{name}}` placeholders. Missing keys render the key itself so
+ * a typo is visible instead of silently blank.
+ * @module @deepseek-ai/dsh-working-activity/lang
+ */
+export type Lang = 'zh' | 'en' | 'ja';
+/** The languages shipped with the plugin, in display order. */
+export declare const LANGS: readonly ["zh", "en", "ja"];
+/** Scope a rendered status line to its own session without changing the UI language. */
+export declare function withProgressLang<T>(lang: Lang, render: () => T): T;
+/** Use the terminal locale only for the first ambiguous prompt in a session. */
+export declare function terminalProgressLang(): Lang;
+/** Detect only confident language signals in user-authored prose. */
+export declare function detectInputLanguage(input: string): Lang | undefined;
+declare const dict: {
+    readonly 'narrate-instruction': {
+        readonly zh: "[状态栏] 你有一个状态栏展示给用户。【必须】在每个步骤/子任务开始时（不只是调用工具前），在回复正文的最前面单独写一行：⏵ 你在做的具体事情（不超过20字），然后换行继续正常回复。整轮回复只写一行 ⏵，不要重复。信息为主——让人一眼知道你在干什么，风格自然、可以带点俏皮。例：⏵ 修复登录页样式、⏵ 查一下报错原因、⏵ 给补丁跑个验证。切换任务时必须更新。";
+        readonly en: "[Status line] You have a status line visible to the user. [Required] At the start of each step or subtask (not only before tool calls), write exactly one standalone line at the very beginning of your response: ⏵ a concrete description of what you are doing (20 words max), then continue with the normal response on the next line. Write only one ⏵ line per response and do not repeat it. Prioritize information so the user can understand the current work at a glance; keep the style natural and optionally playful. Examples: ⏵ Fixing the login page styles, ⏵ Investigating the error, ⏵ Running validation for the patch. Update it when the task changes.";
+    };
+    /** Plain (non-playful) phase labels. */
+    readonly 'waiting-label': {
+        readonly zh: "等待模型响应";
+        readonly en: "Waiting for model";
+        readonly ja: "モデルの応答待ち";
+    };
+    readonly 'thinking-label': {
+        readonly zh: "思考中";
+        readonly en: "Thinking";
+        readonly ja: "考えています";
+    };
+    /** Elapsed suffix: zh glues the char, en keeps a space. */
+    readonly 'line-elapsed': {
+        readonly zh: "总{{elapsed}}";
+        readonly en: "total {{elapsed}}";
+        readonly ja: "合計 {{elapsed}}";
+    };
+    /** Plain-mode completion prefix (playful pools pick their own). */
+    readonly 'done-prefix': {
+        readonly zh: "搞定 ✓";
+        readonly en: "Finished";
+        readonly ja: "完了 ✓";
+    };
+    /** Turn-completion summary. */
+    readonly 'done-summary': {
+        readonly zh: "{{tools}} · 想{{thinking}} 干{{tooling}}";
+        readonly en: "{{tools}} · thought {{thinking}} worked {{tooling}}";
+        readonly ja: "{{tools}} · 思考 {{thinking}} 作業 {{tooling}}";
+    };
+    readonly 'tool-count-one': {
+        readonly zh: "{{count}} 工具";
+        readonly en: "{{count}} tool";
+        readonly ja: "ツール {{count}} 件";
+    };
+    readonly 'tool-count-many': {
+        readonly zh: "{{count}} 工具";
+        readonly en: "{{count}} tools";
+        readonly ja: "ツール {{count}} 件";
+    };
+    /** Consecutive-tool streak badge (replaces the old flame emoji). */
+    readonly 'tool-streak': {
+        readonly zh: "工具x{{count}}";
+        readonly en: "tool x{{count}}";
+        readonly ja: "ツール連続 {{count}} 件";
+    };
+    /** Approval badge while a tool is parked on the user's decision. */
+    readonly 'tool-waiting-approval': {
+        readonly zh: "在等你批准";
+        readonly en: "awaiting your approval";
+        readonly ja: "承認待ち";
+    };
+    /** Subagent count in the done summary. */
+    readonly 'subagent-count': {
+        readonly zh: "子代理 {{count}} 个";
+        readonly en: "{{count}} subagents";
+        readonly ja: "サブエージェント {{count}} 件";
+    };
+    /** Work-reminder copy after `workRemindAt` turn-hours. */
+    readonly 'work-remind': {
+        readonly zh: "已连续工作 {{hours}} 小时，歇会儿？";
+        readonly en: "Worked {{hours}}h straight — take a break?";
+        readonly ja: "{{hours}} 時間続けて作業しています。少し休みますか？";
+    };
+};
+export type I18nKey = keyof typeof dict;
+export type I18nParams = Record<string, string | number>;
+/** Force (or release) the active language; `auto` re-enables the chain. */
+export declare function setLangOverride(lang: Lang | 'auto'): void;
+/** The currently active language. */
+export declare function langNow(): Lang;
+/** Translate a dictionary key, substituting `{{name}}` placeholders. */
+export declare function t(key: I18nKey, params?: I18nParams): string;
+/** Is a value a valid shipped language code? */
+export declare function isLang(value: unknown): value is Lang;
+/**
+ * Read the persisted dsh-tui language choice.
+ *
+ * The probe is cached twice over: the parsed value is reused while the file's
+ * mtime is unchanged, and even the `statSync` itself is skipped for
+ * {@link LANG_FILE_PROBE_TTL_MS}. Both halves matter — one render translates
+ * several keys, and a host that never wrote the file would otherwise pay a
+ * FAILED stat on every one of them (issue #14).
+ *
+ * @param nowMs - Instant to measure the probe cache against.
+ * @returns the persisted language, or `undefined` when the file is absent or
+ * holds no valid `{ lang }` value.
+ */
+export declare function readLangFile(nowMs?: number): Lang | undefined;
+/**
+ * Drop the file cache so the next read probes the filesystem immediately.
+ * Called whenever the language is pinned explicitly, so a switch is never
+ * delayed by the probe TTL.
+ */
+export declare function invalidateLangCache(): void;
+/**
+ * Guess the language from the OS locale (`LC_ALL`, `LC_MESSAGES`, `LANG`),
+ * defaulting to `zh`. POSIX/C means "no locale selected" and conventionally
+ * maps to English (what CI runners report). An absent locale variable
+ * (typical on Windows) defaults to `zh`.
+ */
+export declare function detectLocaleLang(): Lang;
+export {};