@khorsheed/dsh-local-agent-dsh 0.1.0-rc.6

package/lib/types/records.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Session records adapter for the `dsh` harness: list the sub-dsh's own
+ * sessions from its scoped-home store. The sub-dsh persists JSONL logs under
+ * `<scoped home>/sessions/<project>/<session-id>/` (the same physical layout
+ * the official JSONL persistence backend writes), so the adapter reads headers
+ * directly instead of asking the parent's persistence service, which is bound
+ * to the parent's own store root. WHICH file in that directory holds the log
+ * is the host's generation choice, resolved through the same
+ * {@link resolveDshSessionLog} the session mirror uses — the two readers must
+ * never disagree about where a session's history lives.
+ * @module @khorsheed/dsh-local-agent-dsh/records
+ */
+import type { LocalAgentSessionRecord } from '@khorsheed/dsh-local-agent';
+/** A stored session's header line, the subset this adapter reads. */
+interface DshSessionHeader {
+    id: string;
+    cwd?: string;
+    createdAt?: number;
+}
+/** Parse the header line of a session log; undefined when it is not one. */
+export declare function parseDshSessionHeader(firstLine: string): DshSessionHeader | undefined;
+/**
+ * Read a session log's first line (its header). The JSONL backend stores one
+ * zstd frame per append batch; node's zstdDecompress decodes the first frame,
+ * which holds the header line written at session creation.
+ * @param logPath - the session log file to read (any generation, compressed
+ *   or raw — the caller resolved which one).
+ * @param compressed - whether the file is zstd-compressed; a raw log is read
+ *   as text. Defaults to compressed, the backend's own default.
+ * @returns the first line, or undefined when the file is empty/half-written.
+ */
+export declare function readDshSessionHeaderLine(logPath: string, compressed?: boolean): Promise<string | undefined>;
+/**
+ * List the sessions recorded in the harness scoped home, in the store's own
+ * order (project directories first, then session directories).
+ * @param homeDir - the `dsh` harness's scoped home (its `$DSH_HOME` root).
+ * @returns the session records; an absent store yields an empty list.
+ */
+export declare function listDshSessions(homeDir: string): Promise<readonly LocalAgentSessionRecord[]>;
+export {};
+//# sourceMappingURL=records.d.ts.map

package/lib/types/records.js

@@ -0,0 +1,125 @@
+/**
+ * Session records adapter for the `dsh` harness: list the sub-dsh's own
+ * sessions from its scoped-home store. The sub-dsh persists JSONL logs under
+ * `<scoped home>/sessions/<project>/<session-id>/` (the same physical layout
+ * the official JSONL persistence backend writes), so the adapter reads headers
+ * directly instead of asking the parent's persistence service, which is bound
+ * to the parent's own store root. WHICH file in that directory holds the log
+ * is the host's generation choice, resolved through the same
+ * {@link resolveDshSessionLog} the session mirror uses — the two readers must
+ * never disagree about where a session's history lives.
+ * @module @khorsheed/dsh-local-agent-dsh/records
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { zstdDecompressSync } from 'node:zlib';
+import { resolveDshSessionLog } from './session-log.js';
+/** Parse the header line of a session log; undefined when it is not one. */
+export function parseDshSessionHeader(firstLine) {
+    let parsed;
+    try {
+        parsed = JSON.parse(firstLine);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const header = parsed;
+    if (header.type !== 'session' || typeof header.id !== 'string')
+        return undefined;
+    return {
+        id: header.id,
+        ...(typeof header.cwd === 'string' ? { cwd: header.cwd } : {}),
+        ...(typeof header.createdAt === 'number' ? { createdAt: header.createdAt } : {}),
+    };
+}
+/** Whether an fs error is a missing entry. */
+function isENOENT(error) {
+    return error.code === 'ENOENT';
+}
+/**
+ * Read a session log's first line (its header). The JSONL backend stores one
+ * zstd frame per append batch; node's zstdDecompress decodes the first frame,
+ * which holds the header line written at session creation.
+ * @param logPath - the session log file to read (any generation, compressed
+ *   or raw — the caller resolved which one).
+ * @param compressed - whether the file is zstd-compressed; a raw log is read
+ *   as text. Defaults to compressed, the backend's own default.
+ * @returns the first line, or undefined when the file is empty/half-written.
+ */
+export async function readDshSessionHeaderLine(logPath, compressed = true) {
+    let buffer;
+    try {
+        buffer = await readFile(logPath);
+    }
+    catch (error) {
+        if (isENOENT(error))
+            return undefined;
+        throw error;
+    }
+    if (buffer.length === 0)
+        return undefined;
+    let text;
+    try {
+        text = compressed ? zstdDecompressSync(buffer).toString('utf8') : buffer.toString('utf8');
+    }
+    catch {
+        // A torn or non-zstd file is not a readable session; treat as absent.
+        return undefined;
+    }
+    const firstLine = text.split('\n', 1)[0];
+    return firstLine === undefined ? undefined : firstLine;
+}
+/**
+ * List the sessions recorded in the harness scoped home, in the store's own
+ * order (project directories first, then session directories).
+ * @param homeDir - the `dsh` harness's scoped home (its `$DSH_HOME` root).
+ * @returns the session records; an absent store yields an empty list.
+ */
+export async function listDshSessions(homeDir) {
+    const root = join(homeDir, 'sessions');
+    let projects;
+    try {
+        projects = await readdir(root);
+    }
+    catch (error) {
+        if (isENOENT(error))
+            return [];
+        throw error;
+    }
+    const records = [];
+    for (const project of projects) {
+        // Project directories are the `--<slug>--` grouping the backend writes.
+        if (!project.startsWith('--'))
+            continue;
+        let sessionIds;
+        try {
+            sessionIds = await readdir(join(root, project));
+        }
+        catch (error) {
+            if (isENOENT(error))
+                continue;
+            throw error;
+        }
+        for (const sessionId of sessionIds) {
+            // The generation the store actually wrote — hardcoding one filename is
+            // what made `/dsh sessions` list nothing at all on host 0.1.5.
+            const log = await resolveDshSessionLog(join(root, project, sessionId));
+            if (log === undefined)
+                continue;
+            const headerLine = await readDshSessionHeaderLine(log.path, log.compressed);
+            if (headerLine === undefined)
+                continue;
+            const header = parseDshSessionHeader(headerLine);
+            if (header === undefined)
+                continue;
+            records.push({
+                id: header.id,
+                ...(header.cwd !== undefined ? { workDir: header.cwd } : { workDir: project }),
+                ...(header.createdAt !== undefined ? { startedAt: header.createdAt } : {}),
+            });
+        }
+    }
+    return records;
+}

package/lib/types/session-log.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Locating one sub-dsh session's log file inside its session directory.
+ *
+ * The host's JSONL persistence backend addresses its logs by SESSION FORMAT
+ * GENERATION: version zero keeps the original `session.jsonl`, and every later
+ * generation carries a lowercase `vN` component — `session.v3.jsonl` on host
+ * 0.1.5. Either basename may additionally carry `.zstd` for the compressed
+ * default. The backend itself "selects the numerically highest canonical
+ * generation", and so does this module: a reader that hardcodes one filename
+ * reads nothing the moment the host advances a generation, which is exactly
+ * how a 0.1.5 sub-dsh round lost its observed model, its usage and its tool
+ * calls at once while still settling `completed`.
+ *
+ * Both readers in this package — the session mirror's read-back and the
+ * `/dsh sessions` records adapter — resolve through here, so the two can never
+ * disagree about which file a session's history lives in.
+ * @module @khorsheed/dsh-local-agent-dsh/session-log
+ */
+/** One session directory's chosen log file. */
+export interface DshSessionLog {
+    /** Absolute path to the file. */
+    readonly path: string;
+    /**
+     * Its basename — carried into the read-back result so a record says which
+     * generation it was read from, rather than leaving a future filename change
+     * to look like an empty session.
+     */
+    readonly filename: string;
+    /** The generation the name encodes; 0 is the original unversioned log. */
+    readonly version: number;
+    /** Whether the bytes are zstd-compressed (the backend's default). */
+    readonly compressed: boolean;
+}
+/**
+ * Read the generation one session-directory entry names.
+ * @param filename - one basename from a session directory.
+ * @returns its generation and encoding, or undefined when the name is not a
+ *   canonical log (`session.lock`, a temporary file, `session.v0.jsonl`, …).
+ */
+export declare function parseDshSessionLogFilename(filename: string): {
+    readonly version: number;
+    readonly compressed: boolean;
+} | undefined;
+/**
+ * Choose the log file of one session directory: the numerically HIGHEST
+ * canonical generation present, preferring the compressed artifact when a
+ * generation somehow has both (the backend writes one per its configured
+ * encoding, so the pair only appears when a store changed settings).
+ *
+ * A directory with no canonical log — including one that holds only a
+ * `session.lock` — yields undefined. Absence is reported, never guessed: a
+ * caller that cannot find a log records nothing rather than inventing an empty
+ * history.
+ * @param dir - the session-owned directory.
+ * @returns the chosen log, or undefined when the directory holds none.
+ */
+export declare function resolveDshSessionLog(dir: string): Promise<DshSessionLog | undefined>;
+//# sourceMappingURL=session-log.d.ts.map

package/lib/types/session-log.js

@@ -0,0 +1,83 @@
+/**
+ * Locating one sub-dsh session's log file inside its session directory.
+ *
+ * The host's JSONL persistence backend addresses its logs by SESSION FORMAT
+ * GENERATION: version zero keeps the original `session.jsonl`, and every later
+ * generation carries a lowercase `vN` component — `session.v3.jsonl` on host
+ * 0.1.5. Either basename may additionally carry `.zstd` for the compressed
+ * default. The backend itself "selects the numerically highest canonical
+ * generation", and so does this module: a reader that hardcodes one filename
+ * reads nothing the moment the host advances a generation, which is exactly
+ * how a 0.1.5 sub-dsh round lost its observed model, its usage and its tool
+ * calls at once while still settling `completed`.
+ *
+ * Both readers in this package — the session mirror's read-back and the
+ * `/dsh sessions` records adapter — resolve through here, so the two can never
+ * disagree about which file a session's history lives in.
+ * @module @khorsheed/dsh-local-agent-dsh/session-log
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * The canonical raw-log basename, matched AFTER any compression suffix is
+ * removed. Deliberately the host's own rule, character for character
+ * (`@deepseek-ai/dsh-session-format`): `.v0`, leading zeros, uppercase and
+ * temporary names are NOT canonical generations, and a reader that accepted
+ * them would read a file the writer never published.
+ */
+const CANONICAL_LOG_FILENAME = /^session(?:\.v([1-9][0-9]*))?\.jsonl$/u;
+/**
+ * Read the generation one session-directory entry names.
+ * @param filename - one basename from a session directory.
+ * @returns its generation and encoding, or undefined when the name is not a
+ *   canonical log (`session.lock`, a temporary file, `session.v0.jsonl`, …).
+ */
+export function parseDshSessionLogFilename(filename) {
+    const compressed = filename.endsWith('.zstd');
+    const raw = compressed ? filename.slice(0, -'.zstd'.length) : filename;
+    const match = CANONICAL_LOG_FILENAME.exec(raw);
+    if (match === null)
+        return undefined;
+    if (match[1] === undefined)
+        return { version: 0, compressed };
+    const version = Number(match[1]);
+    return Number.isSafeInteger(version) ? { version, compressed } : undefined;
+}
+/**
+ * Choose the log file of one session directory: the numerically HIGHEST
+ * canonical generation present, preferring the compressed artifact when a
+ * generation somehow has both (the backend writes one per its configured
+ * encoding, so the pair only appears when a store changed settings).
+ *
+ * A directory with no canonical log — including one that holds only a
+ * `session.lock` — yields undefined. Absence is reported, never guessed: a
+ * caller that cannot find a log records nothing rather than inventing an empty
+ * history.
+ * @param dir - the session-owned directory.
+ * @returns the chosen log, or undefined when the directory holds none.
+ */
+export async function resolveDshSessionLog(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return undefined;
+    }
+    let best;
+    for (const filename of entries) {
+        const parsed = parseDshSessionLogFilename(filename);
+        if (parsed === undefined)
+            continue;
+        // Higher generation wins; within one generation the compressed artifact
+        // is the backend's default, so it wins a tie.
+        if (best !== undefined) {
+            if (parsed.version < best.version)
+                continue;
+            if (parsed.version === best.version && !(parsed.compressed && !best.compressed))
+                continue;
+        }
+        best = { path: join(dir, filename), filename, ...parsed };
+    }
+    return best;
+}

package/lib/types/session-mirror.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Mirror a sub-dsh session's events into the parent-side dsh subagent session,
+ * so a dsh delegation shows its full conversation (task, replies, thinking)
+ * and real token usage in the standard 子代理 surface — the same fidelity the
+ * other family harnesses get from their CLI transcript files. The sub-dsh
+ * writes a real dsh session into the harness scoped home with the SAME id as
+ * the parent-side child session and the same SessionEvent format, so the
+ * mirror copies finalized `user/message`/`assistant/message` events verbatim
+ * (no parsing, no re-encoding): reasoning blocks render natively and usage
+ * rides the assistant events' own `usage` field into the tokenUsage
+ * projection.
+ *
+ * Round scoping: the parent provider appends one `turn/start` per delegation
+ * round, and the sub-dsh session numbers its turns identically (fresh = 1,
+ * each resume +1), so a round's span is the sub-dsh events from its
+ * `turn/start` with `turn === round` to the next `turn/start`. The sub-dsh's
+ * own scaffolding user messages (agent-instructions, plugin, skill-catalog
+ * sources) are filtered — only the caller task (`source.kind === 'user'`)
+ * crosses. The sub-dsh's own `step/start`/`step/end` pairs cross verbatim
+ * (each carries its (turn, step) coordinates): the real-time conversation
+ * assembler only registers a step — and materializes its assistant message —
+ * at a boundary, so without them the live subsession view renders the prompt
+ * and tool cards but no replies. Turn boundaries are NOT copied: the parent's
+ * real-time spawn→settle boundaries stay the authoritative timing.
+ *
+ * `todo/write` passthrough: the sub-dsh's task list is a standing whole-list
+ * snapshot (last-wins). Each pass appends the round's LATEST snapshot only
+ * when it differs from the child session's last mirrored one, so repeated
+ * passes never duplicate an identical snapshot and the child's `todos`
+ * projection (and the official TodoPanel in non-takeover views) reads the
+ * member's task list for free.
+ * @module @khorsheed/dsh-local-agent-dsh/session-mirror
+ */
+import type { DshSessionLog } from './session-log.ts';
+import type { Context } from '@deepseek-ai/cordis';
+import type { TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
+import type { LocalAgentToolCalls } from '@khorsheed/dsh-local-agent/types';
+/** One session log read back: its events, and which file they came from. */
+export interface SubDshEventLog {
+    /** The session's events, header line excluded. */
+    readonly events: SessionEvent[];
+    /** The log file the events were read from (its generation and encoding). */
+    readonly log: DshSessionLog;
+}
+/**
+ * Read a sub-dsh session's event log from the scoped home. The session lives
+ * at `<homeDir>/sessions/<workspace>/<id>/` (the runner passes the bare uuid);
+ * WHICH file inside that directory holds the history is the host's choice —
+ * `session.jsonl` on the original generation, `session.v3.jsonl.zstd` on host
+ * 0.1.5 — so the name is resolved, never assumed (see
+ * {@link resolveDshSessionLog}). The first line is the header, the rest are
+ * events.
+ * @param homeDir - the `dsh` harness's scoped home.
+ * @param sessionId - the sub-dsh session id (same uuid as the child session).
+ * @returns the events and their source file, or undefined when the session is
+ *   absent or unreadable.
+ */
+export declare function readSubDshEvents(homeDir: string, sessionId: string): Promise<SubDshEventLog | undefined>;
+/** The result of one dsh session-mirror pass. */
+export interface DshMirrorDelta {
+    /** Text of each content event this pass newly mirrored (delta progress payloads); mirrored step boundaries carry no text. */
+    texts: string[];
+    /** Total round events mirrored into the child session after this pass. */
+    total: number;
+    /**
+     * The round's observed model identifier, read from the sub-dsh session's
+     * own assistant events: the `message.source` of the round's LAST
+     * `assistant/message`, formatted `provider/model` (the same shape the
+     * effectiveSettings snapshot reports the configured model in) or the bare
+     * model when no provider is named. Absent when the round's events name no
+     * model — absence is recorded, never guessed.
+     */
+    observedModel?: string;
+    /**
+     * The round's token usage: the span's assistant events' own `usage` fields
+     * summed (each event carries one LLM call's accounting, the same caliber
+     * the tokenUsage projection sums). Absent when the round recorded none.
+     */
+    usage?: TokenUsage;
+    /**
+     * The round's tool-call accounting: the span's `tool/call` events counted
+     * under the names they carry. Read off the SAME round window the model and
+     * usage come from — the pre-skip span, so a settle pass a live poll already
+     * drained still reports the round's real count. Absent when the round made
+     * no tool call.
+     */
+    toolCalls?: LocalAgentToolCalls;
+    /**
+     * The session-log file this pass read, by basename (`session.jsonl.zstd`,
+     * `session.v3.jsonl.zstd`, …). Carried so a read-back says WHICH generation
+     * it read rather than leaving a future filename change to look like an empty
+     * session — the failure this field exists because of. Absent when no log was
+     * found, which is the same "nothing to read" the other fields report by
+     * staying absent.
+     */
+    sessionLogFile?: string;
+}
+/** How much of the live event stream crosses into the child session. */
+export type DshLiveMirrorGranularity = 'event' | 'token';
+/**
+ * Mirror ONE live-pushed sub-dsh session event (the serve mode's
+ * `session/event` wire notification) into the child session. This is the
+ * live driver's transport-side entry into the SAME fold the file mirror
+ * owns: the filter (only the caller task's `user/message`, every
+ * `assistant/message`, the tool events, and the `step/start`/`step/end`
+ * boundaries cross — verbatim; turn boundaries stay the parent's; scaffolding
+ * stays behind) and the verbatim append are exactly `mirrorDshSession`'s
+ * span-loop rules. The 0.1.5 sub-dsh emits no per-chunk events (the
+ * `assistant/chunk` type is retired — an interrupted attempt settles as
+ * `assistant/attempt`, which carries no surface content and never crosses),
+ * so the `token` granularity no longer streams deltas into the child log;
+ * live text rides the run-progress channel only.
+ * The caller owns offset/dedupe (the live runtime pushes
+ * each event once) and persistence batching.
+ * @param childSession - the parent-side dsh subagent session.
+ * @param event - the live event from the resident sub-dsh.
+ * @param _options - granularity; retained for caller compatibility — the
+ *   retirement of per-chunk events leaves the mirror granularity-invariant.
+ * @returns the mirrored text for delta progress, or undefined when the event
+ *   was filtered out or carries no progress text (a step boundary crosses but
+ *   is structure, not content).
+ */
+export declare function mirrorDshLiveEvent(childSession: Session, event: SessionEvent, _options?: {
+    granularity?: DshLiveMirrorGranularity;
+}): string | undefined;
+/**
+ * Mirror the current round's events from the sub-dsh session into the child
+ * session, then persist (a live session syncs through the core's cached write
+ * handle, a standalone one through a one-shot handle; see
+ * {@link persistIfStandalone}). Runs both
+ * from the provider's live poll (while the
+ * sub-dsh writes its log in batches — a torn final zstd frame is skipped
+ * until the next pass) and after the child process exits (the settle pass);
+ * the round's already-mirrored prefix in the child session is the offset, so
+ * the settle pass is a no-op when polling kept up. An aborted round still
+ * preserves its partial work and real usage. All failures degrade to a warn:
+ * the delegation result is already settled.
+ * @param ctx - host context carrying session persistence.
+ * @param childSession - the parent-side dsh subagent session.
+ * @param homeDir - the `dsh` harness's scoped home.
+ * @param subSessionId - the sub-dsh session id (same uuid as the child session).
+ * @returns the newly mirrored events' texts and the round's mirrored total.
+ */
+export declare function mirrorDshSession(ctx: Context, childSession: Session, homeDir: string, subSessionId: string): Promise<DshMirrorDelta>;
+/**
+ * Persist the child session's mirrored events. Thin wrapper over the core's
+ * {@link persistChildSession}: a live session syncs through the core's cached
+ * per-child write handle (host 0.1.5's live write-behind never checkpoints a
+ * mirror session — it has no agent loop — so production child logs stayed
+ * header-only until the explicit sync), a standalone one through a one-shot
+ * handle flow. Kept under the historical name for the live driver.
+ */
+export declare function persistIfStandalone(ctx: Context, childSession: Session): Promise<void>;
+//# sourceMappingURL=session-mirror.d.ts.map