@ai-agent-forge/agent-forge 0.85.0

package/dist/cli/trace-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-view.d.ts","sourceRoot":"","sources":["../../src/cli/trace-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAUvE,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,OAAO,EAAE,aAAa,EAAE,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACvC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAgD3D;AAED,MAAM,MAAM,mBAAmB,GAC5B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oGAAoG;IACpG,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACvC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,yBAAyB,GAChC,OAAO,CAAC,mBAAmB,CAAC,CAoC9B;AAkDD,oFAAoF;AACpF,wBAAgB,eAAe,CAC9B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,qBAAqB,EAAE,MAAM,EAC7B,UAAU,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAqD,EACtF,QAAQ,UAAQ,GACd,MAAM,CA2BR;AAED,MAAM,WAAW,gBAAgB;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qFAAqF;AACrF,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAsE1G","sourcesContent":["/**\n * `--trace <session>` viewer (设计 docs/design/会话轨迹与日志设计.md §8 第 3 期第 1 条).\n *\n * Resolves a session argument to its paired trace file (getTraceFilePathForSession\n * is the single source of the pairing convention) and renders the records as a\n * deterministic text timeline or structured JSON. Read-only: the JSONL reader\n * tolerates trailing partial lines but never repairs or appends to the file\n * (loadEntriesFromFile is deliberately not reused — its header validation\n * rejects trace files and it has an append side effect).\n */\n\nimport { closeSync, existsSync, openSync, readSync } from \"node:fs\";\nimport { StringDecoder } from \"node:string_decoder\";\nimport { getAgentDir } from \"../config.ts\";\nimport { agentSessionsDir } from \"../core/agent-session-paths.ts\";\nimport { findSessionFile } from \"../core/agent-session-store.ts\";\nimport { findMostRecentSession, getDefaultSessionDir, getTraceFilePathForSession } from \"../core/session-manager.ts\";\nimport type { TraceRecordV1 } from \"../plugins/observability-types.ts\";\nimport { resolvePath } from \"../utils/paths.ts\";\nimport { resolveSessionPath } from \"./session-picker.ts\";\n\n/** Mirrors SESSION_READ_BUFFER_SIZE in session-manager.ts (same line-scan pattern). */\nconst TRACE_READ_BUFFER_SIZE = 1024 * 1024;\n\n/** Upper bound for the free-form data summary column (设计 §8 第 3 期). */\nconst TRACE_SUMMARY_MAX_CHARS = 160;\n\nexport interface TraceReadResult {\n\treadonly records: TraceRecordV1[];\n\t/**\n\t * Lines that failed JSON.parse and were skipped. Blank lines are skipped\n\t * like parseSessionEntryLine does, without counting (a trailing newline\n\t * must not look like corruption).\n\t */\n\treadonly skippedMalformedLines: number;\n}\n\n/**\n * Stream a JSONL trace file line by line (same bounded-buffer pattern as\n * loadEntriesFromFile) and parse every line independently. Blank and\n * malformed lines are skipped; malformed ones are counted.\n */\nexport function readTraceFile(path: string): TraceReadResult {\n\tconst records: TraceRecordV1[] = [];\n\tlet skippedMalformedLines = 0;\n\n\tconst consumeLine = (line: string): void => {\n\t\tif (!line.trim()) return;\n\t\ttry {\n\t\t\tconst parsed: unknown = JSON.parse(line);\n\t\t\t// 外部改动可能产生合法 JSON 但非记录对象的行（null/数字/数组）；\n\t\t\t// 与 parse 失败同走跳过计数，渲染阶段因此只需处理真记录。\n\t\t\tif (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n\t\t\t\tskippedMalformedLines += 1;\n\t\t\t\treturn;\n\t\t\t}\n\t\t\trecords.push(parsed as TraceRecordV1);\n\t\t} catch {\n\t\t\tskippedMalformedLines += 1;\n\t\t}\n\t};\n\n\tlet pending = \"\";\n\tconst fd = openSync(path, \"r\");\n\ttry {\n\t\tconst decoder = new StringDecoder(\"utf8\");\n\t\tconst buffer = Buffer.allocUnsafe(TRACE_READ_BUFFER_SIZE);\n\n\t\twhile (true) {\n\t\t\tconst bytesRead = readSync(fd, buffer, 0, buffer.length, null);\n\t\t\tif (bytesRead === 0) break;\n\n\t\t\tpending += decoder.write(buffer.subarray(0, bytesRead));\n\t\t\tlet lineStart = 0;\n\t\t\tlet newlineIndex = pending.indexOf(\"\\n\", lineStart);\n\t\t\twhile (newlineIndex !== -1) {\n\t\t\t\tconsumeLine(pending.slice(lineStart, newlineIndex));\n\t\t\t\tlineStart = newlineIndex + 1;\n\t\t\t\tnewlineIndex = pending.indexOf(\"\\n\", lineStart);\n\t\t\t}\n\t\t\tpending = pending.slice(lineStart);\n\t\t}\n\n\t\tpending += decoder.end();\n\t\tconsumeLine(pending);\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n\n\treturn { records, skippedMalformedLines };\n}\n\nexport type ResolvedTraceTarget =\n\t| { readonly ok: true; readonly sessionFile: string; readonly traceFile: string }\n\t| { readonly ok: false; readonly message: string };\n\nexport interface ResolveTraceTargetOptions {\n\treadonly cwd: string;\n\t/** Explicit session directory (--session-dir chain); default is the per-cwd default session dir. */\n\treadonly sessionDir?: string;\n\t/** Injectable agent dir for the subagent-session lookup; defaults to getAgentDir(). */\n\treadonly agentDir?: string;\n}\n\n/**\n * Four-level fallback from a session argument to a trace file:\n * 1. path-like argument (separators or a `.jsonl` suffix) → used directly;\n *    getTraceFilePathForSession maps an already-paired `.trace.jsonl` input\n *    to itself (idempotent by convention).\n * 2. otherwise resolveSessionPath (exact session id or prefix, local then global).\n * 3. otherwise findSessionFile under <agentDir>/sessions/_agents (subagent\n *    sessions live outside the user's session list; exact id).\n * 4. empty argument → findMostRecentSession in the session dir.\n */\nexport async function resolveTraceTarget(\n\tsessionArg: string,\n\toptions: ResolveTraceTargetOptions,\n): Promise<ResolvedTraceTarget> {\n\tconst { cwd } = options;\n\tconst sessionDir = options.sessionDir === undefined ? undefined : resolvePath(options.sessionDir);\n\tconst agentDir = options.agentDir === undefined ? getAgentDir() : resolvePath(options.agentDir);\n\n\tlet sessionFile: string | undefined;\n\tif (sessionArg.length > 0) {\n\t\tconst resolved = await resolveSessionPath(sessionArg, cwd, sessionDir);\n\t\tif (resolved.type === \"path\" || resolved.type === \"local\" || resolved.type === \"global\") {\n\t\t\tsessionFile = resolved.path;\n\t\t} else {\n\t\t\t// Subagent sessions by exact id: they live in the _agents directory,\n\t\t\t// outside the session lists resolveSessionPath searches.\n\t\t\tconst subagentFile = findSessionFile(agentSessionsDir(agentDir), sessionArg);\n\t\t\tif (subagentFile !== undefined) {\n\t\t\t\tsessionFile = subagentFile;\n\t\t\t} else {\n\t\t\t\treturn { ok: false, message: `No session found matching '${resolved.arg}'` };\n\t\t\t}\n\t\t}\n\t} else {\n\t\tconst mostRecent = findMostRecentSession(sessionDir ?? getDefaultSessionDir(cwd), cwd);\n\t\tif (mostRecent === null) {\n\t\t\treturn { ok: false, message: \"No sessions found for this project; pass a session id or trace file path\" };\n\t\t}\n\t\tsessionFile = mostRecent;\n\t}\n\n\tconst traceFile = getTraceFilePathForSession(sessionFile);\n\tif (!existsSync(traceFile)) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tmessage: `Session has no trace file (${traceFile}); it ran with --no-trace or on an older version`,\n\t\t};\n\t}\n\treturn { ok: true, sessionFile, traceFile };\n}\n\n/** Bounded projection of one record's kind-specific data for the text timeline. */\nfunction summarizeRecord(record: TraceRecordV1): string {\n\tconst data = record.data;\n\tconst fields = data !== null && typeof data === \"object\" ? (data as Record<string, unknown>) : undefined;\n\tconst parts: string[] = [];\n\tswitch (record.kind) {\n\t\tcase \"llm.request\": {\n\t\t\tconst model = fields?.[\"gen_ai.request.model\"];\n\t\t\tif (typeof model === \"string\") parts.push(`model=${model}`);\n\t\t\tbreak;\n\t\t}\n\t\tcase \"llm.response\": {\n\t\t\tif (typeof fields?.stopReason === \"string\") parts.push(`stop=${fields.stopReason}`);\n\t\t\tconst tokens = fields?.[\"gen_ai.usage.total_tokens\"];\n\t\t\tif (typeof tokens === \"number\") parts.push(`tokens=${tokens}`);\n\t\t\tbreak;\n\t\t}\n\t\tcase \"tool.span\": {\n\t\t\tconst toolName = typeof fields?.toolName === \"string\" ? fields.toolName : \"unknown\";\n\t\t\tparts.push(`tool=${toolName}`);\n\t\t\tif (fields?.isError === true) parts.push(\"(error)\");\n\t\t\tbreak;\n\t\t}\n\t\tcase \"decision\": {\n\t\t\tif (typeof fields?.reason === \"string\") parts.push(`reason=${fields.reason}`);\n\t\t\tbreak;\n\t\t}\n\t\tcase \"error\": {\n\t\t\tif (typeof fields?.errorMessage === \"string\") {\n\t\t\t\tconst message = fields.errorMessage;\n\t\t\t\tparts.push(\n\t\t\t\t\tmessage.length > TRACE_SUMMARY_MAX_CHARS ? `${message.slice(0, TRACE_SUMMARY_MAX_CHARS)}…` : message,\n\t\t\t\t);\n\t\t\t}\n\t\t\tbreak;\n\t\t}\n\t\tdefault:\n\t\t\tbreak;\n\t}\n\tif (parts.length === 0 && data !== undefined) {\n\t\tconst json = JSON.stringify(data);\n\t\tif (json !== undefined) {\n\t\t\tparts.push(json.length > TRACE_SUMMARY_MAX_CHARS ? `${json.slice(0, TRACE_SUMMARY_MAX_CHARS)}…` : json);\n\t\t}\n\t}\n\treturn parts.join(\" \");\n}\n\n/** Render the deterministic text timeline (ISO-8601 UTC time column by default). */\nexport function renderTraceText(\n\tsessionFile: string,\n\ttraceFile: string,\n\trecords: readonly TraceRecordV1[],\n\tskippedMalformedLines: number,\n\tformatTime: (epochMs: number) => string = (epochMs) => new Date(epochMs).toISOString(),\n\tfiltered = false,\n): string {\n\tconst recordsLine = `Records: ${records.length} (skipped malformed lines: ${skippedMalformedLines})`;\n\tconst header = [\n\t\t`Session: ${sessionFile}`,\n\t\t`Trace: ${traceFile}`,\n\t\t// Appended only when a --trace-kind/--trace-limit filter is active, so the\n\t\t// unfiltered output stays byte-identical to the pre-filter command.\n\t\tfiltered ? `${recordsLine} (filtered)` : recordsLine,\n\t];\n\tconst lines = [...header];\n\tlet previousAt: number | undefined;\n\tfor (const record of records) {\n\t\tconst deltaMs = previousAt === undefined ? 0 : Math.max(0, record.t - previousAt);\n\t\tpreviousAt = record.t;\n\t\tconst columns = [\n\t\t\t`[${record.seq}]`,\n\t\t\tformatTime(record.t),\n\t\t\t`(+${deltaMs}ms)`,\n\t\t\trecord.kind,\n\t\t\t...(record.level === undefined ? [] : [record.level]),\n\t\t\t...(record.traceId === undefined ? [] : [record.traceId]),\n\t\t\t...(record.dur === undefined ? [] : [`dur=${record.dur}ms`]),\n\t\t];\n\t\tconst summary = summarizeRecord(record);\n\t\tlines.push(summary.length > 0 ? `${columns.join(\" \")} ${summary}` : columns.join(\" \"));\n\t}\n\treturn lines.join(\"\\n\");\n}\n\nexport interface TraceViewOptions {\n\t/** Structured records output instead of the text timeline. */\n\treadonly json?: boolean;\n\treadonly cwd: string;\n\treadonly sessionDir?: string;\n\t/** Injectable agent dir for the subagent-session lookup; defaults to getAgentDir(). */\n\treadonly agentDir?: string;\n\t/**\n\t * When true, exit the process with the resolved exit code after emitting\n\t * output. Default false: return the structured result and let the caller\n\t * (main.ts --trace dispatch) decide.\n\t */\n\treadonly exitProcess?: boolean;\n\t/** Injectable time formatter for deterministic tests; defaults to toISOString. */\n\treadonly formatTime?: (epochMs: number) => string;\n\t/**\n\t * Whitelist of trace record kinds to show (CLI `--trace-kind`). `undefined`\n\t * means no kind filter; records keep their original seq numbers.\n\t */\n\treadonly kinds?: readonly string[];\n\t/** Show only the last N records after the kind filter (CLI `--trace-limit`). */\n\treadonly limit?: number;\n}\n\nexport interface TraceViewResult {\n\treadonly ok: boolean;\n\treadonly exitCode: number;\n\t/** Failure message; surfaced by the caller on stderr. */\n\treadonly message?: string;\n}\n\n/** Entry point for the `--trace` view command: resolve, read, render, and report. */\nexport async function runTraceView(sessionArg: string, options: TraceViewOptions): Promise<TraceViewResult> {\n\tconst finish = (result: TraceViewResult): TraceViewResult => {\n\t\tif (options.exitProcess === true) {\n\t\t\tprocess.exit(result.exitCode);\n\t\t}\n\t\treturn result;\n\t};\n\n\tlet target: ResolvedTraceTarget;\n\ttry {\n\t\ttarget = await resolveTraceTarget(sessionArg, {\n\t\t\tcwd: options.cwd,\n\t\t\t...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),\n\t\t\t...(options.agentDir === undefined ? {} : { agentDir: options.agentDir }),\n\t\t});\n\t} catch (error: unknown) {\n\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\treturn finish({ ok: false, exitCode: 1, message: `Failed to resolve trace target: ${message}` });\n\t}\n\n\tif (!target.ok) {\n\t\treturn finish({ ok: false, exitCode: 1, message: target.message });\n\t}\n\n\tlet read: TraceReadResult;\n\ttry {\n\t\tread = readTraceFile(target.traceFile);\n\t} catch (error: unknown) {\n\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\treturn finish({ ok: false, exitCode: 1, message: `Failed to read trace file: ${message}` });\n\t}\n\n\t// Filter before rendering (design §8 第三批 R2): kind whitelist first, then\n\t// the tail-N limit. Without either option the read result passes through\n\t// untouched so text/json output stays byte-identical to the unfiltered\n\t// command.\n\tconst totalRecords = read.records.length;\n\tlet records = read.records;\n\tif (options.kinds !== undefined) {\n\t\tconst kinds = new Set(options.kinds);\n\t\trecords = records.filter((candidate) => kinds.has(candidate.kind));\n\t}\n\tif (options.limit !== undefined) {\n\t\trecords = records.slice(-options.limit);\n\t}\n\tconst filtered = records.length !== totalRecords;\n\n\tconst envelope = {\n\t\tsessionFile: target.sessionFile,\n\t\ttraceFile: target.traceFile,\n\t\trecordCount: records.length,\n\t\tskippedMalformedLines: read.skippedMalformedLines,\n\t\t...(filtered ? { filteredOut: totalRecords - records.length } : {}),\n\t\trecords,\n\t};\n\tif (options.json === true) {\n\t\tconsole.log(JSON.stringify(envelope, null, 2));\n\t} else {\n\t\tconsole.log(\n\t\t\trenderTraceText(\n\t\t\t\ttarget.sessionFile,\n\t\t\t\ttarget.traceFile,\n\t\t\t\trecords,\n\t\t\t\tread.skippedMalformedLines,\n\t\t\t\toptions.formatTime,\n\t\t\t\tfiltered,\n\t\t\t),\n\t\t);\n\t}\n\treturn finish({ ok: true, exitCode: 0 });\n}\n"]}

package/dist/cli/trace-view.js

@@ -0,0 +1,263 @@
+/**
+ * `--trace <session>` viewer (设计 docs/design/会话轨迹与日志设计.md §8 第 3 期第 1 条).
+ *
+ * Resolves a session argument to its paired trace file (getTraceFilePathForSession
+ * is the single source of the pairing convention) and renders the records as a
+ * deterministic text timeline or structured JSON. Read-only: the JSONL reader
+ * tolerates trailing partial lines but never repairs or appends to the file
+ * (loadEntriesFromFile is deliberately not reused — its header validation
+ * rejects trace files and it has an append side effect).
+ */
+import { closeSync, existsSync, openSync, readSync } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+import { getAgentDir } from "../config.js";
+import { agentSessionsDir } from "../core/agent-session-paths.js";
+import { findSessionFile } from "../core/agent-session-store.js";
+import { findMostRecentSession, getDefaultSessionDir, getTraceFilePathForSession } from "../core/session-manager.js";
+import { resolvePath } from "../utils/paths.js";
+import { resolveSessionPath } from "./session-picker.js";
+/** Mirrors SESSION_READ_BUFFER_SIZE in session-manager.ts (same line-scan pattern). */
+const TRACE_READ_BUFFER_SIZE = 1024 * 1024;
+/** Upper bound for the free-form data summary column (设计 §8 第 3 期). */
+const TRACE_SUMMARY_MAX_CHARS = 160;
+/**
+ * Stream a JSONL trace file line by line (same bounded-buffer pattern as
+ * loadEntriesFromFile) and parse every line independently. Blank and
+ * malformed lines are skipped; malformed ones are counted.
+ */
+export function readTraceFile(path) {
+    const records = [];
+    let skippedMalformedLines = 0;
+    const consumeLine = (line) => {
+        if (!line.trim())
+            return;
+        try {
+            const parsed = JSON.parse(line);
+            // 外部改动可能产生合法 JSON 但非记录对象的行（null/数字/数组）；
+            // 与 parse 失败同走跳过计数，渲染阶段因此只需处理真记录。
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                skippedMalformedLines += 1;
+                return;
+            }
+            records.push(parsed);
+        }
+        catch {
+            skippedMalformedLines += 1;
+        }
+    };
+    let pending = "";
+    const fd = openSync(path, "r");
+    try {
+        const decoder = new StringDecoder("utf8");
+        const buffer = Buffer.allocUnsafe(TRACE_READ_BUFFER_SIZE);
+        while (true) {
+            const bytesRead = readSync(fd, buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            pending += decoder.write(buffer.subarray(0, bytesRead));
+            let lineStart = 0;
+            let newlineIndex = pending.indexOf("\n", lineStart);
+            while (newlineIndex !== -1) {
+                consumeLine(pending.slice(lineStart, newlineIndex));
+                lineStart = newlineIndex + 1;
+                newlineIndex = pending.indexOf("\n", lineStart);
+            }
+            pending = pending.slice(lineStart);
+        }
+        pending += decoder.end();
+        consumeLine(pending);
+    }
+    finally {
+        closeSync(fd);
+    }
+    return { records, skippedMalformedLines };
+}
+/**
+ * Four-level fallback from a session argument to a trace file:
+ * 1. path-like argument (separators or a `.jsonl` suffix) → used directly;
+ *    getTraceFilePathForSession maps an already-paired `.trace.jsonl` input
+ *    to itself (idempotent by convention).
+ * 2. otherwise resolveSessionPath (exact session id or prefix, local then global).
+ * 3. otherwise findSessionFile under <agentDir>/sessions/_agents (subagent
+ *    sessions live outside the user's session list; exact id).
+ * 4. empty argument → findMostRecentSession in the session dir.
+ */
+export async function resolveTraceTarget(sessionArg, options) {
+    const { cwd } = options;
+    const sessionDir = options.sessionDir === undefined ? undefined : resolvePath(options.sessionDir);
+    const agentDir = options.agentDir === undefined ? getAgentDir() : resolvePath(options.agentDir);
+    let sessionFile;
+    if (sessionArg.length > 0) {
+        const resolved = await resolveSessionPath(sessionArg, cwd, sessionDir);
+        if (resolved.type === "path" || resolved.type === "local" || resolved.type === "global") {
+            sessionFile = resolved.path;
+        }
+        else {
+            // Subagent sessions by exact id: they live in the _agents directory,
+            // outside the session lists resolveSessionPath searches.
+            const subagentFile = findSessionFile(agentSessionsDir(agentDir), sessionArg);
+            if (subagentFile !== undefined) {
+                sessionFile = subagentFile;
+            }
+            else {
+                return { ok: false, message: `No session found matching '${resolved.arg}'` };
+            }
+        }
+    }
+    else {
+        const mostRecent = findMostRecentSession(sessionDir ?? getDefaultSessionDir(cwd), cwd);
+        if (mostRecent === null) {
+            return { ok: false, message: "No sessions found for this project; pass a session id or trace file path" };
+        }
+        sessionFile = mostRecent;
+    }
+    const traceFile = getTraceFilePathForSession(sessionFile);
+    if (!existsSync(traceFile)) {
+        return {
+            ok: false,
+            message: `Session has no trace file (${traceFile}); it ran with --no-trace or on an older version`,
+        };
+    }
+    return { ok: true, sessionFile, traceFile };
+}
+/** Bounded projection of one record's kind-specific data for the text timeline. */
+function summarizeRecord(record) {
+    const data = record.data;
+    const fields = data !== null && typeof data === "object" ? data : undefined;
+    const parts = [];
+    switch (record.kind) {
+        case "llm.request": {
+            const model = fields?.["gen_ai.request.model"];
+            if (typeof model === "string")
+                parts.push(`model=${model}`);
+            break;
+        }
+        case "llm.response": {
+            if (typeof fields?.stopReason === "string")
+                parts.push(`stop=${fields.stopReason}`);
+            const tokens = fields?.["gen_ai.usage.total_tokens"];
+            if (typeof tokens === "number")
+                parts.push(`tokens=${tokens}`);
+            break;
+        }
+        case "tool.span": {
+            const toolName = typeof fields?.toolName === "string" ? fields.toolName : "unknown";
+            parts.push(`tool=${toolName}`);
+            if (fields?.isError === true)
+                parts.push("(error)");
+            break;
+        }
+        case "decision": {
+            if (typeof fields?.reason === "string")
+                parts.push(`reason=${fields.reason}`);
+            break;
+        }
+        case "error": {
+            if (typeof fields?.errorMessage === "string") {
+                const message = fields.errorMessage;
+                parts.push(message.length > TRACE_SUMMARY_MAX_CHARS ? `${message.slice(0, TRACE_SUMMARY_MAX_CHARS)}…` : message);
+            }
+            break;
+        }
+        default:
+            break;
+    }
+    if (parts.length === 0 && data !== undefined) {
+        const json = JSON.stringify(data);
+        if (json !== undefined) {
+            parts.push(json.length > TRACE_SUMMARY_MAX_CHARS ? `${json.slice(0, TRACE_SUMMARY_MAX_CHARS)}…` : json);
+        }
+    }
+    return parts.join(" ");
+}
+/** Render the deterministic text timeline (ISO-8601 UTC time column by default). */
+export function renderTraceText(sessionFile, traceFile, records, skippedMalformedLines, formatTime = (epochMs) => new Date(epochMs).toISOString(), filtered = false) {
+    const recordsLine = `Records: ${records.length} (skipped malformed lines: ${skippedMalformedLines})`;
+    const header = [
+        `Session: ${sessionFile}`,
+        `Trace: ${traceFile}`,
+        // Appended only when a --trace-kind/--trace-limit filter is active, so the
+        // unfiltered output stays byte-identical to the pre-filter command.
+        filtered ? `${recordsLine} (filtered)` : recordsLine,
+    ];
+    const lines = [...header];
+    let previousAt;
+    for (const record of records) {
+        const deltaMs = previousAt === undefined ? 0 : Math.max(0, record.t - previousAt);
+        previousAt = record.t;
+        const columns = [
+            `[${record.seq}]`,
+            formatTime(record.t),
+            `(+${deltaMs}ms)`,
+            record.kind,
+            ...(record.level === undefined ? [] : [record.level]),
+            ...(record.traceId === undefined ? [] : [record.traceId]),
+            ...(record.dur === undefined ? [] : [`dur=${record.dur}ms`]),
+        ];
+        const summary = summarizeRecord(record);
+        lines.push(summary.length > 0 ? `${columns.join(" ")} ${summary}` : columns.join(" "));
+    }
+    return lines.join("\n");
+}
+/** Entry point for the `--trace` view command: resolve, read, render, and report. */
+export async function runTraceView(sessionArg, options) {
+    const finish = (result) => {
+        if (options.exitProcess === true) {
+            process.exit(result.exitCode);
+        }
+        return result;
+    };
+    let target;
+    try {
+        target = await resolveTraceTarget(sessionArg, {
+            cwd: options.cwd,
+            ...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
+            ...(options.agentDir === undefined ? {} : { agentDir: options.agentDir }),
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return finish({ ok: false, exitCode: 1, message: `Failed to resolve trace target: ${message}` });
+    }
+    if (!target.ok) {
+        return finish({ ok: false, exitCode: 1, message: target.message });
+    }
+    let read;
+    try {
+        read = readTraceFile(target.traceFile);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return finish({ ok: false, exitCode: 1, message: `Failed to read trace file: ${message}` });
+    }
+    // Filter before rendering (design §8 第三批 R2): kind whitelist first, then
+    // the tail-N limit. Without either option the read result passes through
+    // untouched so text/json output stays byte-identical to the unfiltered
+    // command.
+    const totalRecords = read.records.length;
+    let records = read.records;
+    if (options.kinds !== undefined) {
+        const kinds = new Set(options.kinds);
+        records = records.filter((candidate) => kinds.has(candidate.kind));
+    }
+    if (options.limit !== undefined) {
+        records = records.slice(-options.limit);
+    }
+    const filtered = records.length !== totalRecords;
+    const envelope = {
+        sessionFile: target.sessionFile,
+        traceFile: target.traceFile,
+        recordCount: records.length,
+        skippedMalformedLines: read.skippedMalformedLines,
+        ...(filtered ? { filteredOut: totalRecords - records.length } : {}),
+        records,
+    };
+    if (options.json === true) {
+        console.log(JSON.stringify(envelope, null, 2));
+    }
+    else {
+        console.log(renderTraceText(target.sessionFile, target.traceFile, records, read.skippedMalformedLines, options.formatTime, filtered));
+    }
+    return finish({ ok: true, exitCode: 0 });
+}
+//# sourceMappingURL=trace-view.js.map

package/dist/cli/trace-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-view.js","sourceRoot":"","sources":["../../src/cli/trace-view.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `--trace <session>` viewer (设计 docs/design/会话轨迹与日志设计.md §8 第 3 期第 1 条).\n *\n * Resolves a session argument to its paired trace file (getTraceFilePathForSession\n * is the single source of the pairing convention) and renders the records as a\n * deterministic text timeline or structured JSON. Read-only: the JSONL reader\n * tolerates trailing partial lines but never repairs or appends to the file\n * (loadEntriesFromFile is deliberately not reused — its header validation\n * rejects trace files and it has an append side effect).\n */\n\nimport { closeSync, existsSync, openSync, readSync } from \"node:fs\";\nimport { StringDecoder } from \"node:string_decoder\";\nimport { getAgentDir } from \"../config.ts\";\nimport { agentSessionsDir } from \"../core/agent-session-paths.ts\";\nimport { findSessionFile } from \"../core/agent-session-store.ts\";\nimport { findMostRecentSession, getDefaultSessionDir, getTraceFilePathForSession } from \"../core/session-manager.ts\";\nimport type { TraceRecordV1 } from \"../plugins/observability-types.ts\";\nimport { resolvePath } from \"../utils/paths.ts\";\nimport { resolveSessionPath } from \"./session-picker.ts\";\n\n/** Mirrors SESSION_READ_BUFFER_SIZE in session-manager.ts (same line-scan pattern). */\nconst TRACE_READ_BUFFER_SIZE = 1024 * 1024;\n\n/** Upper bound for the free-form data summary column (设计 §8 第 3 期). */\nconst TRACE_SUMMARY_MAX_CHARS = 160;\n\nexport interface TraceReadResult {\n\treadonly records: TraceRecordV1[];\n\t/**\n\t * Lines that failed JSON.parse and were skipped. Blank lines are skipped\n\t * like parseSessionEntryLine does, without counting (a trailing newline\n\t * must not look like corruption).\n\t */\n\treadonly skippedMalformedLines: number;\n}\n\n/**\n * Stream a JSONL trace file line by line (same bounded-buffer pattern as\n * loadEntriesFromFile) and parse every line independently. Blank and\n * malformed lines are skipped; malformed ones are counted.\n */\nexport function readTraceFile(path: string): TraceReadResult {\n\tconst records: TraceRecordV1[] = [];\n\tlet skippedMalformedLines = 0;\n\n\tconst consumeLine = (line: string): void => {\n\t\tif (!line.trim()) return;\n\t\ttry {\n\t\t\tconst parsed: unknown = JSON.parse(line);\n\t\t\t// 外部改动可能产生合法 JSON 但非记录对象的行（null/数字/数组）；\n\t\t\t// 与 parse 失败同走跳过计数，渲染阶段因此只需处理真记录。\n\t\t\tif (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n\t\t\t\tskippedMalformedLines += 1;\n\t\t\t\treturn;\n\t\t\t}\n\t\t\trecords.push(parsed as TraceRecordV1);\n\t\t} catch {\n\t\t\tskippedMalformedLines += 1;\n\t\t}\n\t};\n\n\tlet pending = \"\";\n\tconst fd = openSync(path, \"r\");\n\ttry {\n\t\tconst decoder = new StringDecoder(\"utf8\");\n\t\tconst buffer = Buffer.allocUnsafe(TRACE_READ_BUFFER_SIZE);\n\n\t\twhile (true) {\n\t\t\tconst bytesRead = readSync(fd, buffer, 0, buffer.length, null);\n\t\t\tif (bytesRead === 0) break;\n\n\t\t\tpending += decoder.write(buffer.subarray(0, bytesRead));\n\t\t\tlet lineStart = 0;\n\t\t\tlet newlineIndex = pending.indexOf(\"\\n\", lineStart);\n\t\t\twhile (newlineIndex !== -1) {\n\t\t\t\tconsumeLine(pending.slice(lineStart, newlineIndex));\n\t\t\t\tlineStart = newlineIndex + 1;\n\t\t\t\tnewlineIndex = pending.indexOf(\"\\n\", lineStart);\n\t\t\t}\n\t\t\tpending = pending.slice(lineStart);\n\t\t}\n\n\t\tpending += decoder.end();\n\t\tconsumeLine(pending);\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n\n\treturn { records, skippedMalformedLines };\n}\n\nexport type ResolvedTraceTarget =\n\t| { readonly ok: true; readonly sessionFile: string; readonly traceFile: string }\n\t| { readonly ok: false; readonly message: string };\n\nexport interface ResolveTraceTargetOptions {\n\treadonly cwd: string;\n\t/** Explicit session directory (--session-dir chain); default is the per-cwd default session dir. */\n\treadonly sessionDir?: string;\n\t/** Injectable agent dir for the subagent-session lookup; defaults to getAgentDir(). */\n\treadonly agentDir?: string;\n}\n\n/**\n * Four-level fallback from a session argument to a trace file:\n * 1. path-like argument (separators or a `.jsonl` suffix) → used directly;\n *    getTraceFilePathForSession maps an already-paired `.trace.jsonl` input\n *    to itself (idempotent by convention).\n * 2. otherwise resolveSessionPath (exact session id or prefix, local then global).\n * 3. otherwise findSessionFile under <agentDir>/sessions/_agents (subagent\n *    sessions live outside the user's session list; exact id).\n * 4. empty argument → findMostRecentSession in the session dir.\n */\nexport async function resolveTraceTarget(\n\tsessionArg: string,\n\toptions: ResolveTraceTargetOptions,\n): Promise<ResolvedTraceTarget> {\n\tconst { cwd } = options;\n\tconst sessionDir = options.sessionDir === undefined ? undefined : resolvePath(options.sessionDir);\n\tconst agentDir = options.agentDir === undefined ? getAgentDir() : resolvePath(options.agentDir);\n\n\tlet sessionFile: string | undefined;\n\tif (sessionArg.length > 0) {\n\t\tconst resolved = await resolveSessionPath(sessionArg, cwd, sessionDir);\n\t\tif (resolved.type === \"path\" || resolved.type === \"local\" || resolved.type === \"global\") {\n\t\t\tsessionFile = resolved.path;\n\t\t} else {\n\t\t\t// Subagent sessions by exact id: they live in the _agents directory,\n\t\t\t// outside the session lists resolveSessionPath searches.\n\t\t\tconst subagentFile = findSessionFile(agentSessionsDir(agentDir), sessionArg);\n\t\t\tif (subagentFile !== undefined) {\n\t\t\t\tsessionFile = subagentFile;\n\t\t\t} else {\n\t\t\t\treturn { ok: false, message: `No session found matching '${resolved.arg}'` };\n\t\t\t}\n\t\t}\n\t} else {\n\t\tconst mostRecent = findMostRecentSession(sessionDir ?? getDefaultSessionDir(cwd), cwd);\n\t\tif (mostRecent === null) {\n\t\t\treturn { ok: false, message: \"No sessions found for this project; pass a session id or trace file path\" };\n\t\t}\n\t\tsessionFile = mostRecent;\n\t}\n\n\tconst traceFile = getTraceFilePathForSession(sessionFile);\n\tif (!existsSync(traceFile)) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tmessage: `Session has no trace file (${traceFile}); it ran with --no-trace or on an older version`,\n\t\t};\n\t}\n\treturn { ok: true, sessionFile, traceFile };\n}\n\n/** Bounded projection of one record's kind-specific data for the text timeline. */\nfunction summarizeRecord(record: TraceRecordV1): string {\n\tconst data = record.data;\n\tconst fields = data !== null && typeof data === \"object\" ? (data as Record<string, unknown>) : undefined;\n\tconst parts: string[] = [];\n\tswitch (record.kind) {\n\t\tcase \"llm.request\": {\n\t\t\tconst model = fields?.[\"gen_ai.request.model\"];\n\t\t\tif (typeof model === \"string\") parts.push(`model=${model}`);\n\t\t\tbreak;\n\t\t}\n\t\tcase \"llm.response\": {\n\t\t\tif (typeof fields?.stopReason === \"string\") parts.push(`stop=${fields.stopReason}`);\n\t\t\tconst tokens = fields?.[\"gen_ai.usage.total_tokens\"];\n\t\t\tif (typeof tokens === \"number\") parts.push(`tokens=${tokens}`);\n\t\t\tbreak;\n\t\t}\n\t\tcase \"tool.span\": {\n\t\t\tconst toolName = typeof fields?.toolName === \"string\" ? fields.toolName : \"unknown\";\n\t\t\tparts.push(`tool=${toolName}`);\n\t\t\tif (fields?.isError === true) parts.push(\"(error)\");\n\t\t\tbreak;\n\t\t}\n\t\tcase \"decision\": {\n\t\t\tif (typeof fields?.reason === \"string\") parts.push(`reason=${fields.reason}`);\n\t\t\tbreak;\n\t\t}\n\t\tcase \"error\": {\n\t\t\tif (typeof fields?.errorMessage === \"string\") {\n\t\t\t\tconst message = fields.errorMessage;\n\t\t\t\tparts.push(\n\t\t\t\t\tmessage.length > TRACE_SUMMARY_MAX_CHARS ? `${message.slice(0, TRACE_SUMMARY_MAX_CHARS)}…` : message,\n\t\t\t\t);\n\t\t\t}\n\t\t\tbreak;\n\t\t}\n\t\tdefault:\n\t\t\tbreak;\n\t}\n\tif (parts.length === 0 && data !== undefined) {\n\t\tconst json = JSON.stringify(data);\n\t\tif (json !== undefined) {\n\t\t\tparts.push(json.length > TRACE_SUMMARY_MAX_CHARS ? `${json.slice(0, TRACE_SUMMARY_MAX_CHARS)}…` : json);\n\t\t}\n\t}\n\treturn parts.join(\" \");\n}\n\n/** Render the deterministic text timeline (ISO-8601 UTC time column by default). */\nexport function renderTraceText(\n\tsessionFile: string,\n\ttraceFile: string,\n\trecords: readonly TraceRecordV1[],\n\tskippedMalformedLines: number,\n\tformatTime: (epochMs: number) => string = (epochMs) => new Date(epochMs).toISOString(),\n\tfiltered = false,\n): string {\n\tconst recordsLine = `Records: ${records.length} (skipped malformed lines: ${skippedMalformedLines})`;\n\tconst header = [\n\t\t`Session: ${sessionFile}`,\n\t\t`Trace: ${traceFile}`,\n\t\t// Appended only when a --trace-kind/--trace-limit filter is active, so the\n\t\t// unfiltered output stays byte-identical to the pre-filter command.\n\t\tfiltered ? `${recordsLine} (filtered)` : recordsLine,\n\t];\n\tconst lines = [...header];\n\tlet previousAt: number | undefined;\n\tfor (const record of records) {\n\t\tconst deltaMs = previousAt === undefined ? 0 : Math.max(0, record.t - previousAt);\n\t\tpreviousAt = record.t;\n\t\tconst columns = [\n\t\t\t`[${record.seq}]`,\n\t\t\tformatTime(record.t),\n\t\t\t`(+${deltaMs}ms)`,\n\t\t\trecord.kind,\n\t\t\t...(record.level === undefined ? [] : [record.level]),\n\t\t\t...(record.traceId === undefined ? [] : [record.traceId]),\n\t\t\t...(record.dur === undefined ? [] : [`dur=${record.dur}ms`]),\n\t\t];\n\t\tconst summary = summarizeRecord(record);\n\t\tlines.push(summary.length > 0 ? `${columns.join(\" \")} ${summary}` : columns.join(\" \"));\n\t}\n\treturn lines.join(\"\\n\");\n}\n\nexport interface TraceViewOptions {\n\t/** Structured records output instead of the text timeline. */\n\treadonly json?: boolean;\n\treadonly cwd: string;\n\treadonly sessionDir?: string;\n\t/** Injectable agent dir for the subagent-session lookup; defaults to getAgentDir(). */\n\treadonly agentDir?: string;\n\t/**\n\t * When true, exit the process with the resolved exit code after emitting\n\t * output. Default false: return the structured result and let the caller\n\t * (main.ts --trace dispatch) decide.\n\t */\n\treadonly exitProcess?: boolean;\n\t/** Injectable time formatter for deterministic tests; defaults to toISOString. */\n\treadonly formatTime?: (epochMs: number) => string;\n\t/**\n\t * Whitelist of trace record kinds to show (CLI `--trace-kind`). `undefined`\n\t * means no kind filter; records keep their original seq numbers.\n\t */\n\treadonly kinds?: readonly string[];\n\t/** Show only the last N records after the kind filter (CLI `--trace-limit`). */\n\treadonly limit?: number;\n}\n\nexport interface TraceViewResult {\n\treadonly ok: boolean;\n\treadonly exitCode: number;\n\t/** Failure message; surfaced by the caller on stderr. */\n\treadonly message?: string;\n}\n\n/** Entry point for the `--trace` view command: resolve, read, render, and report. */\nexport async function runTraceView(sessionArg: string, options: TraceViewOptions): Promise<TraceViewResult> {\n\tconst finish = (result: TraceViewResult): TraceViewResult => {\n\t\tif (options.exitProcess === true) {\n\t\t\tprocess.exit(result.exitCode);\n\t\t}\n\t\treturn result;\n\t};\n\n\tlet target: ResolvedTraceTarget;\n\ttry {\n\t\ttarget = await resolveTraceTarget(sessionArg, {\n\t\t\tcwd: options.cwd,\n\t\t\t...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),\n\t\t\t...(options.agentDir === undefined ? {} : { agentDir: options.agentDir }),\n\t\t});\n\t} catch (error: unknown) {\n\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\treturn finish({ ok: false, exitCode: 1, message: `Failed to resolve trace target: ${message}` });\n\t}\n\n\tif (!target.ok) {\n\t\treturn finish({ ok: false, exitCode: 1, message: target.message });\n\t}\n\n\tlet read: TraceReadResult;\n\ttry {\n\t\tread = readTraceFile(target.traceFile);\n\t} catch (error: unknown) {\n\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\treturn finish({ ok: false, exitCode: 1, message: `Failed to read trace file: ${message}` });\n\t}\n\n\t// Filter before rendering (design §8 第三批 R2): kind whitelist first, then\n\t// the tail-N limit. Without either option the read result passes through\n\t// untouched so text/json output stays byte-identical to the unfiltered\n\t// command.\n\tconst totalRecords = read.records.length;\n\tlet records = read.records;\n\tif (options.kinds !== undefined) {\n\t\tconst kinds = new Set(options.kinds);\n\t\trecords = records.filter((candidate) => kinds.has(candidate.kind));\n\t}\n\tif (options.limit !== undefined) {\n\t\trecords = records.slice(-options.limit);\n\t}\n\tconst filtered = records.length !== totalRecords;\n\n\tconst envelope = {\n\t\tsessionFile: target.sessionFile,\n\t\ttraceFile: target.traceFile,\n\t\trecordCount: records.length,\n\t\tskippedMalformedLines: read.skippedMalformedLines,\n\t\t...(filtered ? { filteredOut: totalRecords - records.length } : {}),\n\t\trecords,\n\t};\n\tif (options.json === true) {\n\t\tconsole.log(JSON.stringify(envelope, null, 2));\n\t} else {\n\t\tconsole.log(\n\t\t\trenderTraceText(\n\t\t\t\ttarget.sessionFile,\n\t\t\t\ttarget.traceFile,\n\t\t\t\trecords,\n\t\t\t\tread.skippedMalformedLines,\n\t\t\t\toptions.formatTime,\n\t\t\t\tfiltered,\n\t\t\t),\n\t\t);\n\t}\n\treturn finish({ ok: true, exitCode: 0 });\n}\n"]}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"","sourcesContent":["#!/usr/bin/env node\n/**\n * CLI entry point for the refactored coding agent.\n * Uses main.ts with AgentSession and new mode modules.\n *\n * Test with: npx tsx src/cli.ts [args...]\n */\nimport { APP_NAME } from \"./config.ts\";\nimport { configureHttpDispatcher } from \"./core/http-dispatcher.ts\";\nimport { main } from \"./main.ts\";\n\nprocess.title = APP_NAME;\nprocess.env.AGENT_FORGE = \"true\";\nprocess.env.AI_AGENT = \"agent-forge\";\nprocess.emitWarning = (() => {}) as typeof process.emitWarning;\n\n// Configure undici's global dispatcher before provider SDKs issue requests.\n// Runtime settings are applied once SettingsManager has loaded global/project settings.\nconfigureHttpDispatcher();\n\nmain(process.argv.slice(2));\n"]}

package/dist/cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for the refactored coding agent.
+ * Uses main.ts with AgentSession and new mode modules.
+ *
+ * Test with: npx tsx src/cli.ts [args...]
+ */
+import { APP_NAME } from "./config.js";
+import { configureHttpDispatcher } from "./core/http-dispatcher.js";
+import { main } from "./main.js";
+process.title = APP_NAME;
+process.env.AGENT_FORGE = "true";
+process.env.AI_AGENT = "agent-forge";
+process.emitWarning = (() => { });
+// Configure undici's global dispatcher before provider SDKs issue requests.
+// Runtime settings are applied once SettingsManager has loaded global/project settings.
+configureHttpDispatcher();
+main(process.argv.slice(2));
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,CAAC,KAAK,GAAG,QAAQ,CAAC;AACzB,OAAO,CAAC,GAAG,CAAC,WAAW,GAAG,MAAM,CAAC;AACjC,OAAO,CAAC,GAAG,CAAC,QAAQ,GAAG,aAAa,CAAC;AACrC,OAAO,CAAC,WAAW,GAAG,CAAC,GAAG,EAAE,CAAC,EAAC,CAAC,CAA+B,CAAC;AAE/D,4EAA4E;AAC5E,wFAAwF;AACxF,uBAAuB,EAAE,CAAC;AAE1B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\n/**\n * CLI entry point for the refactored coding agent.\n * Uses main.ts with AgentSession and new mode modules.\n *\n * Test with: npx tsx src/cli.ts [args...]\n */\nimport { APP_NAME } from \"./config.ts\";\nimport { configureHttpDispatcher } from \"./core/http-dispatcher.ts\";\nimport { main } from \"./main.ts\";\n\nprocess.title = APP_NAME;\nprocess.env.AGENT_FORGE = \"true\";\nprocess.env.AI_AGENT = \"agent-forge\";\nprocess.emitWarning = (() => {}) as typeof process.emitWarning;\n\n// Configure undici's global dispatcher before provider SDKs issue requests.\n// Runtime settings are applied once SettingsManager has loaded global/project settings.\nconfigureHttpDispatcher();\n\nmain(process.argv.slice(2));\n"]}

package/dist/client/index.d.ts

@@ -0,0 +1,3 @@
+export { type CreateRemoteSessionOptions, RemoteSession, type RemoteSessionLifecycle, type RemoteSessionOperation, type RemoteSessionOptions, type RemoteSessionState, } from "./remote-session.ts";
+export { applyTranscriptProgress, applyTranscriptSnapshot, createTranscriptState, selectTranscript, type TranscriptState, } from "./transcript.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,0BAA0B,EAC/B,aAAa,EACb,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,eAAe,GACpB,MAAM,iBAAiB,CAAC","sourcesContent":["export {\n\ttype CreateRemoteSessionOptions,\n\tRemoteSession,\n\ttype RemoteSessionLifecycle,\n\ttype RemoteSessionOperation,\n\ttype RemoteSessionOptions,\n\ttype RemoteSessionState,\n} from \"./remote-session.ts\";\nexport {\n\tapplyTranscriptProgress,\n\tapplyTranscriptSnapshot,\n\tcreateTranscriptState,\n\tselectTranscript,\n\ttype TranscriptState,\n} from \"./transcript.ts\";\n"]}

package/dist/client/index.js

@@ -0,0 +1,3 @@
+export { RemoteSession, } from "./remote-session.js";
+export { applyTranscriptProgress, applyTranscriptSnapshot, createTranscriptState, selectTranscript, } from "./transcript.js";
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,aAAa,GAKb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,GAEhB,MAAM,iBAAiB,CAAC","sourcesContent":["export {\n\ttype CreateRemoteSessionOptions,\n\tRemoteSession,\n\ttype RemoteSessionLifecycle,\n\ttype RemoteSessionOperation,\n\ttype RemoteSessionOptions,\n\ttype RemoteSessionState,\n} from \"./remote-session.ts\";\nexport {\n\tapplyTranscriptProgress,\n\tapplyTranscriptSnapshot,\n\tcreateTranscriptState,\n\tselectTranscript,\n\ttype TranscriptState,\n} from \"./transcript.ts\";\n"]}

package/dist/client/remote-session.d.ts

@@ -0,0 +1,53 @@
+import type { ConnectionState, ConnectionStateChange, PiClient, Unsubscribe } from "@agent-forge/client";
+import type { ModelMetadata, ModelRef, SessionMetadata, SessionPhase, SessionSnapshot, ThinkingLevel, TranscriptItem } from "@agent-forge/protocol";
+export type RemoteSessionOperation = "open" | "create" | "submit" | "abort" | "setModel" | "setThinking" | "reconnect";
+export type RemoteSessionLifecycle = {
+    readonly status: "unbound";
+} | {
+    readonly status: "ready";
+} | {
+    readonly status: "busy";
+    readonly operation: RemoteSessionOperation;
+} | {
+    readonly status: "disposed";
+};
+export interface RemoteSessionState {
+    readonly lifecycle: RemoteSessionLifecycle;
+    readonly snapshot?: SessionSnapshot;
+    readonly transcript: readonly TranscriptItem[];
+}
+export interface CreateRemoteSessionOptions {
+    cwd: string;
+    model?: ModelRef;
+    thinkingLevel?: ThinkingLevel;
+}
+export interface RemoteSessionOptions {
+    onListenerError?: (error: Error) => void;
+}
+export declare class RemoteSession {
+    #private;
+    private constructor();
+    get id(): string | undefined;
+    get state(): RemoteSessionState;
+    get snapshot(): SessionSnapshot | undefined;
+    get phase(): SessionPhase | undefined;
+    get operation(): RemoteSessionOperation | undefined;
+    get models(): readonly ModelMetadata[];
+    get sessions(): readonly SessionMetadata[];
+    get connectionState(): ConnectionState;
+    get disposed(): boolean;
+    subscribe(listener: (state: RemoteSessionState) => void): Unsubscribe;
+    onConnectionStateChange(listener: (change: ConnectionStateChange) => void): Unsubscribe;
+    static open(client: PiClient, sessionId: string, options?: RemoteSessionOptions): Promise<RemoteSession>;
+    open(sessionId: string): Promise<void>;
+    static create(client: PiClient, createOptions: CreateRemoteSessionOptions, options?: RemoteSessionOptions): Promise<RemoteSession>;
+    create(options: CreateRemoteSessionOptions): Promise<void>;
+    submit(text: string): Promise<void>;
+    abort(): Promise<void>;
+    setModel(model: ModelRef): Promise<void>;
+    setThinking(thinkingLevel: ThinkingLevel): Promise<void>;
+    reconnect(): Promise<void>;
+    dispose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=remote-session.d.ts.map

package/dist/client/remote-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-session.d.ts","sourceRoot":"","sources":["../../src/client/remote-session.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ConnectionState, ConnectionStateChange, PiClient, SessionLease, Unsubscribe } from \"@agent-forge/client\";\nimport type {\n\tModelMetadata,\n\tModelRef,\n\tServerEvent,\n\tSessionMetadata,\n\tSessionPhase,\n\tSessionSnapshot,\n\tThinkingLevel,\n\tTranscriptItem,\n} from \"@agent-forge/protocol\";\nimport {\n\tapplyTranscriptProgress,\n\tapplyTranscriptSnapshot,\n\tcreateTranscriptState,\n\tselectTranscript,\n\ttype TranscriptState,\n} from \"./transcript.ts\";\n\nexport type RemoteSessionOperation = \"open\" | \"create\" | \"submit\" | \"abort\" | \"setModel\" | \"setThinking\" | \"reconnect\";\n\nexport type RemoteSessionLifecycle =\n\t| { readonly status: \"unbound\" }\n\t| { readonly status: \"ready\" }\n\t| { readonly status: \"busy\"; readonly operation: RemoteSessionOperation }\n\t| { readonly status: \"disposed\" };\n\nexport interface RemoteSessionState {\n\treadonly lifecycle: RemoteSessionLifecycle;\n\treadonly snapshot?: SessionSnapshot;\n\treadonly transcript: readonly TranscriptItem[];\n}\n\nexport interface CreateRemoteSessionOptions {\n\tcwd: string;\n\tmodel?: ModelRef;\n\tthinkingLevel?: ThinkingLevel;\n}\n\nexport interface RemoteSessionOptions {\n\tonListenerError?: (error: Error) => void;\n}\n\nclass RemoteSessionDisposedError extends Error {\n\tconstructor() {\n\t\tsuper(\"Remote session is disposed\");\n\t\tthis.name = \"RemoteSessionDisposedError\";\n\t}\n}\n\nasync function settleRemoteSessionDisposal(cleanup: readonly Promise<void>[]): Promise<void> {\n\tconst results = await Promise.allSettled(cleanup);\n\tconst errors = results.flatMap((result) =>\n\t\tresult.status === \"rejected\" && !(result.reason instanceof RemoteSessionDisposedError) ? [result.reason] : [],\n\t);\n\tif (errors.length === 1) throw errors[0];\n\tif (errors.length > 1) throw new AggregateError(errors, \"Failed to dispose remote session\");\n}\n\nexport class RemoteSession {\n\treadonly #client: PiClient;\n\treadonly #onListenerError: ((error: Error) => void) | undefined;\n\t#lifecycle: RemoteSessionLifecycle = { status: \"unbound\" };\n\t#handle: SessionLease | undefined;\n\t#transcript: TranscriptState | undefined;\n\t#unsubscribeSnapshot: Unsubscribe | undefined;\n\t#unsubscribeEvents: Unsubscribe | undefined;\n\treadonly #listeners = new Set<(state: RemoteSessionState) => void>();\n\treadonly #pendingAttachmentOperations = new Set<Promise<void>>();\n\treadonly #activeOperationStates = new Set<RemoteSessionLifecycle>();\n\t#disposePromise: Promise<void> | undefined;\n\t#resolveDisposeSignal: () => void = () => {};\n\treadonly #disposeSignal = new Promise<void>((resolve) => {\n\t\tthis.#resolveDisposeSignal = resolve;\n\t});\n\n\tprivate constructor(client: PiClient, options: RemoteSessionOptions = {}) {\n\t\tthis.#client = client;\n\t\tthis.#onListenerError = options.onListenerError;\n\t}\n\n\tget id(): string | undefined {\n\t\treturn this.#handle?.id;\n\t}\n\n\tget state(): RemoteSessionState {\n\t\treturn {\n\t\t\tlifecycle: this.#lifecycle,\n\t\t\tsnapshot: this.#transcript?.snapshot,\n\t\t\ttranscript: this.#transcript ? selectTranscript(this.#transcript) : [],\n\t\t};\n\t}\n\n\tget snapshot(): SessionSnapshot | undefined {\n\t\treturn this.#transcript?.snapshot;\n\t}\n\n\tget phase(): SessionPhase | undefined {\n\t\treturn this.snapshot?.phase;\n\t}\n\n\tget operation(): RemoteSessionOperation | undefined {\n\t\treturn this.#lifecycle.status === \"busy\" ? this.#lifecycle.operation : undefined;\n\t}\n\n\tget models(): readonly ModelMetadata[] {\n\t\treturn this.#client.snapshot?.models ?? [];\n\t}\n\n\tget sessions(): readonly SessionMetadata[] {\n\t\treturn this.#client.snapshot?.sessions ?? [];\n\t}\n\n\tget connectionState(): ConnectionState {\n\t\treturn this.#client.connectionState;\n\t}\n\n\tget disposed(): boolean {\n\t\treturn this.#lifecycle.status === \"disposed\";\n\t}\n\n\tsubscribe(listener: (state: RemoteSessionState) => void): Unsubscribe {\n\t\tthis.#assertNotDisposed();\n\t\tthis.#listeners.add(listener);\n\t\tthis.#callListener(listener, this.state);\n\t\treturn () => this.#listeners.delete(listener);\n\t}\n\n\tonConnectionStateChange(listener: (change: ConnectionStateChange) => void): Unsubscribe {\n\t\tthis.#assertNotDisposed();\n\t\treturn this.#client.onConnectionStateChange(listener);\n\t}\n\n\tstatic async open(client: PiClient, sessionId: string, options: RemoteSessionOptions = {}): Promise<RemoteSession> {\n\t\tconst session = new RemoteSession(client, options);\n\t\ttry {\n\t\t\tawait session.open(sessionId);\n\t\t\treturn session;\n\t\t} catch (error) {\n\t\t\tawait session.dispose();\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tasync open(sessionId: string): Promise<void> {\n\t\tif (this.#handle?.id === sessionId && this.#lifecycle.status === \"ready\") return;\n\t\tawait this.#replace(\"open\", () => this.#client.acquireSession(sessionId, { mode: \"exclusive\" }));\n\t}\n\n\tstatic async create(\n\t\tclient: PiClient,\n\t\tcreateOptions: CreateRemoteSessionOptions,\n\t\toptions: RemoteSessionOptions = {},\n\t): Promise<RemoteSession> {\n\t\tconst session = new RemoteSession(client, options);\n\t\ttry {\n\t\t\tawait session.create(createOptions);\n\t\t\treturn session;\n\t\t} catch (error) {\n\t\t\tawait session.dispose();\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tasync create(options: CreateRemoteSessionOptions): Promise<void> {\n\t\tawait this.#replace(\"create\", () => this.#client.createSession(options));\n\t}\n\n\tasync submit(text: string): Promise<void> {\n\t\tconst normalized = text.trim();\n\t\tif (!normalized) return;\n\t\tthis.#assertAvailable();\n\t\tconst handle = this.#requireHandle();\n\t\tif (this.phase !== \"idle\" && this.phase !== \"turn\") {\n\t\t\tthrow new Error(`Session cannot accept input during ${this.phase ?? \"unknown\"} phase`);\n\t\t}\n\t\tawait this.#runOperation(\"submit\", () =>\n\t\t\t(this.phase === \"idle\" ? handle.prompt(normalized) : handle.steer(normalized)).then(() => undefined),\n\t\t);\n\t}\n\n\tasync abort(): Promise<void> {\n\t\tconst preemptingSubmit = this.#lifecycle.status === \"busy\" && this.#lifecycle.operation === \"submit\";\n\t\tif (preemptingSubmit) this.#assertNotDisposed();\n\t\telse this.#assertAvailable();\n\t\tconst handle = this.#requireHandle();\n\t\tif (this.phase === \"idle\" && !preemptingSubmit) return;\n\t\tawait this.#runOperation(\"abort\", () => handle.abort().then(() => undefined), preemptingSubmit);\n\t}\n\n\tasync setModel(model: ModelRef): Promise<void> {\n\t\tawait this.#runIdleOperation(\"setModel\", \"change model\", () =>\n\t\t\tthis.#requireHandle()\n\t\t\t\t.setModel(model)\n\t\t\t\t.then(() => undefined),\n\t\t);\n\t}\n\n\tasync setThinking(thinkingLevel: ThinkingLevel): Promise<void> {\n\t\tawait this.#runIdleOperation(\"setThinking\", \"change thinking level\", () =>\n\t\t\tthis.#requireHandle()\n\t\t\t\t.setThinking(thinkingLevel)\n\t\t\t\t.then(() => undefined),\n\t\t);\n\t}\n\n\tasync reconnect(): Promise<void> {\n\t\tthis.#assertAvailable();\n\t\tconst sessionId = this.#requireHandle().id;\n\t\tawait this.#runOperation(\"reconnect\", () =>\n\t\t\tthis.#trackAttachmentOperation(async () => {\n\t\t\t\tawait this.#client.reconnect();\n\t\t\t\tconst handle = await this.#client.acquireSession(sessionId, { mode: \"exclusive\" });\n\t\t\t\tawait this.#assertNotDisposedAfterAwait(handle);\n\t\t\t\tthis.#bind(handle);\n\t\t\t}),\n\t\t);\n\t}\n\n\tdispose(): Promise<void> {\n\t\tif (this.#disposePromise) return this.#disposePromise;\n\t\tconst handle = this.#handle;\n\t\tthis.#lifecycle = { status: \"disposed\" };\n\t\tthis.#resolveDisposeSignal();\n\t\tthis.#clearSubscriptions();\n\t\tthis.#handle = undefined;\n\t\tthis.#transcript = undefined;\n\t\tconst cleanup = [...this.#pendingAttachmentOperations];\n\t\tif (handle) cleanup.push(handle.dispose());\n\t\tthis.#disposePromise = settleRemoteSessionDisposal(cleanup);\n\t\tthis.#notify();\n\t\tthis.#listeners.clear();\n\t\treturn this.#disposePromise;\n\t}\n\n\t[Symbol.asyncDispose](): Promise<void> {\n\t\treturn this.dispose();\n\t}\n\n\tasync #replace(operation: \"open\" | \"create\", prepare: () => Promise<SessionLease>): Promise<void> {\n\t\tthis.#assertAvailable();\n\t\tif (this.#handle && this.phase !== \"idle\") {\n\t\t\tthrow new Error(`Cannot ${operation} a session while session is ${this.phase ?? \"unavailable\"}`);\n\t\t}\n\t\tawait this.#runOperation(operation, () =>\n\t\t\tthis.#trackAttachmentOperation(() => this.#prepareReplacement(operation, prepare)),\n\t\t);\n\t}\n\n\tasync #trackAttachmentOperation(run: () => Promise<void>): Promise<void> {\n\t\tconst pending = run();\n\t\tthis.#pendingAttachmentOperations.add(pending);\n\t\ttry {\n\t\t\tawait pending;\n\t\t} finally {\n\t\t\tthis.#pendingAttachmentOperations.delete(pending);\n\t\t}\n\t}\n\n\tasync #prepareReplacement(operation: \"open\" | \"create\", prepare: () => Promise<SessionLease>): Promise<void> {\n\t\tconst previous = this.#handle;\n\t\tconst next = await prepare();\n\t\tawait this.#assertNotDisposedAfterAwait(next);\n\t\tconst snapshot = next.snapshot;\n\t\tif (!snapshot) {\n\t\t\tawait this.#detach(next);\n\t\t\tthrow new Error(`Session ${next.id} did not provide a snapshot`);\n\t\t}\n\t\tif (previous && previous.id !== next.id && previous.attached && this.phase !== \"idle\") {\n\t\t\tawait this.#detach(next);\n\t\t\tthrow new Error(`Cannot ${operation} a session while session is ${this.phase ?? \"unavailable\"}`);\n\t\t}\n\t\tif (previous && previous.id !== next.id && previous.attached) {\n\t\t\ttry {\n\t\t\t\tawait previous.detach();\n\t\t\t} catch (error) {\n\t\t\t\ttry {\n\t\t\t\t\tawait this.#detach(next);\n\t\t\t\t} catch (cleanupError) {\n\t\t\t\t\tthrow new AggregateError([error, cleanupError], \"Failed to replace remote session attachment\");\n\t\t\t\t}\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t\tawait this.#assertNotDisposedAfterAwait(next);\n\t\tthis.#bind(next, snapshot);\n\t}\n\n\tasync #runIdleOperation(\n\t\toperation: \"setModel\" | \"setThinking\",\n\t\tdescription: string,\n\t\trun: () => Promise<void>,\n\t): Promise<void> {\n\t\tthis.#assertAvailable();\n\t\tthis.#requireHandle();\n\t\tif (this.phase !== \"idle\") {\n\t\t\tthrow new Error(`Cannot ${description} while session is ${this.phase ?? \"unavailable\"}`);\n\t\t}\n\t\tawait this.#runOperation(operation, run);\n\t}\n\n\tasync #runOperation(operation: RemoteSessionOperation, run: () => Promise<void>, preempt = false): Promise<void> {\n\t\tif (preempt) this.#assertNotDisposed();\n\t\telse this.#assertAvailable();\n\t\tconst previous = this.#lifecycle;\n\t\tconst busy: RemoteSessionLifecycle = { status: \"busy\", operation };\n\t\tthis.#lifecycle = busy;\n\t\tthis.#activeOperationStates.add(busy);\n\t\tthis.#notify();\n\t\tconst running = run();\n\t\ttry {\n\t\t\tawait Promise.race([\n\t\t\t\trunning,\n\t\t\t\tthis.#disposeSignal.then(() => {\n\t\t\t\t\tthrow new Error(\"Remote session is disposed\");\n\t\t\t\t}),\n\t\t\t]);\n\t\t} finally {\n\t\t\tthis.#activeOperationStates.delete(busy);\n\t\t\tif (!this.disposed && this.#lifecycle === busy) {\n\t\t\t\tthis.#lifecycle =\n\t\t\t\t\tpreempt && this.#activeOperationStates.has(previous)\n\t\t\t\t\t\t? previous\n\t\t\t\t\t\t: this.#handle\n\t\t\t\t\t\t\t? { status: \"ready\" }\n\t\t\t\t\t\t\t: { status: \"unbound\" };\n\t\t\t\tthis.#notify();\n\t\t\t}\n\t\t}\n\t}\n\n\t#bind(handle: SessionLease, knownSnapshot?: SessionSnapshot): void {\n\t\tconst snapshot = knownSnapshot ?? handle.snapshot;\n\t\tif (!snapshot) throw new Error(`Session ${handle.id} did not provide a snapshot`);\n\t\tthis.#clearSubscriptions();\n\t\tthis.#handle = handle;\n\t\tthis.#transcript = createTranscriptState(snapshot);\n\t\tthis.#unsubscribeSnapshot = handle.subscribe((next) => {\n\t\t\tif (!this.#transcript) return;\n\t\t\tthis.#transcript = applyTranscriptSnapshot(this.#transcript, next);\n\t\t\tthis.#notify();\n\t\t});\n\t\tthis.#unsubscribeEvents = handle.onEvent((event) => this.#handleEvent(event));\n\t}\n\n\t#handleEvent(event: ServerEvent): void {\n\t\tif (event.type === \"session_removed\") {\n\t\t\tthis.#clearSubscriptions();\n\t\t\tthis.#handle = undefined;\n\t\t\tthis.#transcript = undefined;\n\t\t\tif (this.#lifecycle.status !== \"busy\") this.#lifecycle = { status: \"unbound\" };\n\t\t\tthis.#notify();\n\t\t\treturn;\n\t\t}\n\t\tif (event.type !== \"session_progress\" || !this.#transcript) return;\n\t\tthis.#transcript = applyTranscriptProgress(this.#transcript, event.progress);\n\t\tthis.#notify();\n\t}\n\n\t#notify(): void {\n\t\tconst state = this.state;\n\t\tfor (const listener of this.#listeners) this.#callListener(listener, state);\n\t}\n\n\t#callListener(listener: (state: RemoteSessionState) => void, state: RemoteSessionState): void {\n\t\ttry {\n\t\t\tlistener(state);\n\t\t} catch (error) {\n\t\t\tthis.#reportListenerError(error);\n\t\t}\n\t}\n\n\t#reportListenerError(error: unknown): void {\n\t\tif (!this.#onListenerError) return;\n\t\ttry {\n\t\t\tthis.#onListenerError(error instanceof Error ? error : new Error(String(error)));\n\t\t} catch {\n\t\t\t// Diagnostics cannot affect session or transport state.\n\t\t}\n\t}\n\n\t#clearSubscriptions(): void {\n\t\tthis.#unsubscribeSnapshot?.();\n\t\tthis.#unsubscribeEvents?.();\n\t\tthis.#unsubscribeSnapshot = undefined;\n\t\tthis.#unsubscribeEvents = undefined;\n\t}\n\n\t#requireHandle(): SessionLease {\n\t\tif (!this.#handle) throw new Error(\"No remote session is attached\");\n\t\treturn this.#handle;\n\t}\n\n\t#assertAvailable(): void {\n\t\tthis.#assertNotDisposed();\n\t\tif (this.#lifecycle.status === \"busy\") {\n\t\t\tthrow new Error(`Remote session is busy with ${this.#lifecycle.operation}`);\n\t\t}\n\t}\n\n\t#assertNotDisposed(): void {\n\t\tif (this.disposed) throw new Error(\"Remote session is disposed\");\n\t}\n\n\tasync #assertNotDisposedAfterAwait(handle: SessionLease): Promise<void> {\n\t\tif (!this.disposed) return;\n\t\tawait this.#detach(handle);\n\t\tthrow new RemoteSessionDisposedError();\n\t}\n\n\tasync #detach(handle: SessionLease): Promise<void> {\n\t\tawait handle.dispose();\n\t}\n}\n"]}