@ponythewhite/base-context 1.0.0 → 1.0.2

package/docs/usage.md

@@ -42,13 +42,13 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/login`, `/logout` | Manage OAuth or API-key credentials |
 | `/model` | Switch models |
 | `/effort` | Set the reasoning/thinking level |
+| `/agents [N]` | Show or save the maximum live subagents (default: 4) |
 | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
 | `/settings` | Thinking level, theme, message delivery, transport |
 | `/resume [id\|path]` | Open the agents view, or resume a session directly |
 | `/new` | Start a new session |
 | `/name <name>` | Set session display name |
 | `/session` | Show session file, ID, and message counts |
-| `/traces [status\|on\|off\|preview\|upload-current\|upload-all\|login]` | Preview, upload, or manage opt-in trace sharing |
 | `/usage`, `/context` | Show the parent and subagent context, token, and cost breakdown |
 | `/tree` | Jump to any point in the session and continue from there |
 | `/fork` | Create a new session from a previous user message |
@@ -58,12 +58,21 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/copy` | Copy last assistant message to clipboard |
 | `/btw <question>`, `/side <question>` | Ask an inline side question without adding it to the session; replies continue the side conversation, esc returns |
 | `/export [file]` | Export session to HTML |
-| `/share` | Upload as private GitHub gist with shareable HTML link |
 | `/reload` | Reload keybindings, extensions, skills, prompts, and context files |
 | `/hotkeys` | Show all keyboard shortcuts |
 | `/changelog` | Display version history |
 | `/quit` | Quit Base Context |
 
+### Limit concurrent subagents
+
+`/agents` reads the current configured limit from the active root-agent family and displays exactly `The current maximum number of concurrent subagents is {N}.`, with `{N}` replaced by that current value, not a hardcoded default.
+
+`/agents 6` sets the limit to 6 for the current root agent and all its descendants. The main agent does not count. Running and idle subagents count; inactive saved sessions do not. A fresh installation defaults to **4** live subagents.
+
+The value is saved as the global `rlmMaxSubagents` preference, so it survives restarts and supplies the limit for later sessions. Use a non-negative safe integer. `/agents 0` disables new subagent spawns. Malformed, fractional, negative, and unsafe integer values are rejected without changing the setting.
+
+Lowering the limit never kills or passivates existing agents. They keep running or remain idle. Only new spawns/admissions are blocked until the live count is below the limit. This slash command is separate from `base-context agents`, which lists agents.
+
 ## Message Queue
 
 You can submit messages while the agent is still working:
@@ -165,11 +174,9 @@ Replace the default system prompt with:
 
 Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
 
-## Exporting and Sharing Sessions
-
-Use `/export [file]` to write a session to HTML.
+## Exporting Sessions
 
-Use `/share` to upload a private GitHub gist with a shareable HTML link.
+Use `/export [file]` to write a session to a local HTML file.
 
 ## CLI Reference
 
@@ -373,15 +380,12 @@ base-context --tools ipython -p "Review the code"
 | `BASE_CONTEXT_SKIP_VERSION_CHECK` | Skip the Base Context version lookup at startup |
 | `BASE_CONTEXT_DOWNLOAD_BASE_URL` | Explicit custom static update-manifest base; leave unset for owned npm updates. A GitHub repository URL is not that manifest endpoint; see [update settings](settings.md#update-checks) |
 | `BASE_CONTEXT_CACHE_RETENTION` | Set to `long` for extended prompt cache where the provider supports it |
-| `PRIME_API_KEY` | Prime Inference API key; not a trace-sharing credential |
-| `BASE_CONTEXT_TRACES_API_KEY` | Dedicated key for explicitly configured, opt-in Base Context trace sharing |
-| `BASE_CONTEXT_TRACES_BASE_URL` | Explicit trace upload API base; no upstream destination is selected by default |
 | `BASE_CONTEXT_KERNEL_PYTHON` | Explicit Python executable with a current `base-context-runtime` for a manual runtime route |
 | `BASE_CONTEXT_KERNEL_VENV` | Explicit manual kernel environment directory; owned preparation still creates its own fresh release-local environment |
 | `BASE_CONTEXT_INSTALL_UV` | Set to `1` to allow uv installation for kernel bootstrap |
 | `VISUAL`, `EDITOR` | External editor for Ctrl+G |
 
-`BASE_CONTEXT_HOME`, `BASE_CONTEXT_SESSION_DIR` and kernel path overrides require non-empty absolute paths (`~/` is supported). The project configuration directory is `.base-context/`; changing the product HOME does not rename it. These product settings do not redirect into old Prime state. `PRIME_API_KEY` remains a provider name, not a product-prefix alias. The Python import stays `rlm`, but an upstream `prime-agent-runtime` environment is not the Base Context runtime. Non-owned default bootstrap uses `~/.base-context/runtime`; the owned installer prepares each release's runtime before activation.
+`BASE_CONTEXT_HOME`, `BASE_CONTEXT_SESSION_DIR` and kernel path overrides require non-empty absolute paths (`~/` is supported). The project configuration directory is `.base-context/`; changing the product HOME does not rename it. These product settings do not redirect into old Prime state. Provider variables such as `OPENAI_API_KEY` keep their provider names; they are not product-prefix aliases. The Python import stays `rlm`, but an upstream `prime-agent-runtime` environment is not the Base Context runtime. Non-owned default bootstrap uses `~/.base-context/runtime`; the owned installer prepares each release's runtime before activation.
 
 ## Design Principles
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ponythewhite/base-context",
-	"version": "1.0.0",
+	"version": "1.0.2",
 	"description": "Synerise base-context: a coding and research agent with durable context and a persistent Python REPL",
 	"type": "module",
 	"bin": {
@@ -42,9 +42,9 @@
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "^1.3.0",
-		"@ponythewhite/base-context-agent": "1.0.0",
-		"@ponythewhite/base-context-ai": "1.0.0",
-		"@ponythewhite/base-context-tui": "1.0.0",
+		"@ponythewhite/base-context-agent": "1.0.2",
+		"@ponythewhite/base-context-ai": "1.0.2",
+		"@ponythewhite/base-context-tui": "1.0.2",
 		"@silvia-odwyer/photon-node": "^0.3.4",
 		"chalk": "^5.5.0",
 		"cli-highlight": "^2.1.11",

package/dist/core/agent-traces.d.ts

@@ -1,149 +0,0 @@
-import type { AuthStorage } from "./auth-storage.js";
-import { type SessionHeader, type SessionManager } from "./session-manager.js";
-import type { SettingsManager } from "./settings-manager.js";
-export type AgentTraceCredentialSource = "environment" | "stored";
-export interface AgentTraceCredential {
-    apiKey: string;
-    source: AgentTraceCredentialSource;
-    label: string;
-}
-export type AgentTraceUploadResult = {
-    status: "uploaded";
-    sessionId: string;
-    traceId: string;
-    bytesStored: number;
-    key?: string;
-} | {
-    status: "disabled";
-} | {
-    status: "unchanged";
-} | {
-    status: "missing_credentials";
-} | {
-    status: "no_session_file";
-} | {
-    status: "empty_session";
-} | {
-    status: "invalid_session";
-    message: string;
-} | {
-    status: "too_large";
-    size: number;
-    maxBytes: number;
-} | {
-    status: "failed";
-    statusCode?: number;
-    message: string;
-    retryAfterMs?: number;
-};
-export interface AgentTraceUploadOptions {
-    sessionFile: string | undefined;
-    authStorage: AuthStorage;
-    settingsManager: SettingsManager;
-    /** Require the global automatic-sharing opt-in. Set false only for an explicit one-shot upload command. */
-    requireEnabled?: boolean;
-    baseUrl?: string;
-    configPath?: string;
-    fetchFn?: typeof fetch;
-    reloadConfig?: boolean;
-    requestTimeoutMs?: number;
-    signal?: AbortSignal;
-}
-export interface AgentTraceSessionUploadOptions extends Omit<AgentTraceUploadOptions, "sessionFile"> {
-    sessionManager: SessionManager;
-}
-export interface AgentTraceUploadInstallOptions {
-    authStorage: AuthStorage;
-    settingsManager: SettingsManager;
-    baseUrl?: string;
-    configPath?: string;
-    fetchFn?: typeof fetch;
-    requestTimeoutMs?: number;
-    /** The session's semantic-edge ledger; registered with the outbox as its own delivery kind. */
-    semanticEdgesLedgerPath?: string;
-}
-export type AgentTracePreviewResult = {
-    status: "ready";
-    sessionFile: string;
-    sessionId: string;
-    traceId: string;
-    parentSessionId?: string;
-    cwd: string;
-    size: number;
-    maxBytes: number;
-    uploadable: boolean;
-    endpoint?: string;
-    gitRepo?: string;
-    gitCommit?: string;
-    contentPreview: string;
-    truncated: boolean;
-} | {
-    status: "no_session_file";
-} | {
-    status: "empty_session";
-} | {
-    status: "invalid_session";
-    message: string;
-} | {
-    status: "failed";
-    message: string;
-};
-export interface AgentTracePreviewOptions {
-    sessionFile: string | undefined;
-    baseUrl?: string;
-    maxContentChars?: number;
-}
-export interface AgentTraceUploadAllProgress {
-    completed: number;
-    total: number;
-    sessionFile?: string;
-    result?: AgentTraceUploadResult;
-}
-export interface AgentTraceUploadAllOptions extends Omit<AgentTraceUploadOptions, "sessionFile"> {
-    sessionDir?: string;
-    concurrency?: number;
-    onProgress?: (progress: AgentTraceUploadAllProgress) => void;
-}
-export interface AgentTraceUploadAllResult {
-    total: number;
-    uploaded: number;
-    failed: number;
-    skipped: number;
-    bytesStored: number;
-    results: Array<{
-        sessionFile: string;
-        result: AgentTraceUploadResult;
-    }>;
-}
-/** Active-branch git for the indexing headers: walk leaf to root, not the last git_state in
- * file order (which may belong to a sibling branch). */
-export declare function activeGitContext(body: string, header: SessionHeader): {
-    repoUrl?: string;
-    commit?: string;
-} | undefined;
-export declare function previewAgentTraceFile(options: AgentTracePreviewOptions): Promise<AgentTracePreviewResult>;
-export declare function findAgentTraceFiles(sessionDir?: string): Promise<string[]>;
-export declare function uploadAllAgentTraces(options: AgentTraceUploadAllOptions): Promise<AgentTraceUploadAllResult>;
-export declare const SEMANTIC_EDGES_OUTBOX_KIND = "semantic-edges";
-export interface AgentTraceCatchUpResult {
-    pruned: number;
-    /** Registered semantic-edge ledgers with bytes beyond their cursor; no delivery endpoint exists yet. */
-    semanticEdgeLedgersPending: number;
-    results: Array<{
-        sessionFile: string;
-        result: AgentTraceUploadResult;
-    }>;
-}
-/**
- * Explicit catch-up for the Base Context export outbox. This is never run at
- * startup and does not read inherited agent-traces-outbox entries.
- */
-export declare function catchUpAgentTraceUploads(options: Omit<AgentTraceUploadOptions, "sessionFile">): Promise<AgentTraceCatchUpResult>;
-export declare function getPrimeAgentTraceCredential(authStorage: AuthStorage, options?: {
-    reloadAuth?: boolean;
-    configPath?: string;
-}): Promise<AgentTraceCredential | undefined>;
-export declare function uploadAgentTraceFile(options: AgentTraceUploadOptions): Promise<AgentTraceUploadResult>;
-export declare function uploadAgentTraceSession(options: AgentTraceSessionUploadOptions): Promise<AgentTraceUploadResult>;
-export declare function installAgentTraceUpload(sessionManager: SessionManager, options: AgentTraceUploadInstallOptions): void;
-//# sourceMappingURL=agent-traces.d.ts.map

package/dist/core/agent-traces.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent-traces.d.ts","sourceRoot":"","sources":["../../src/core/agent-traces.ts"],"names":[],"mappings":"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","sourcesContent":["import { Buffer } from \"node:buffer\";\nimport { createHash, randomUUID } from \"node:crypto\";\nimport { type Dirent, existsSync, mkdirSync, renameSync, writeFileSync } from \"node:fs\";\nimport { mkdir, readdir, readFile, rename, stat, unlink, writeFile } from \"node:fs/promises\";\nimport { dirname, isAbsolute, join, resolve } from \"node:path\";\nimport { appendRotatingLog, getAgentDir, getAgentTracesLogPath, getSessionsDir, VERSION } from \"../config.js\";\nimport { assertProductStatePath } from \"../runtime-paths.js\";\nimport type { AuthStorage } from \"./auth-storage.js\";\nimport { BASE_CONTEXT_TRACES_PROVIDER_ID, resolvePrimeAgentTracesBaseUrl } from \"./prime-inference-auth.js\";\nimport { readSessionJournal, readSessionJournalHeader } from \"./session-journal-reader.js\";\nimport { getSessionArtifactsRoot, type SessionHeader, type SessionManager } from \"./session-manager.js\";\nimport type { SettingsManager } from \"./settings-manager.js\";\n\nconst MAX_TRACE_BYTES = 20 * 1024 * 1024;\nconst DEFAULT_REQUEST_TIMEOUT_MS = 15_000;\nconst TRACE_UPLOAD_DEBOUNCE_MS = 1_000;\nconst TRACE_UPLOAD_MIN_INTERVAL_MS = 60_000;\nconst TRACE_UPLOAD_RETRY_BASE_DELAY_MS = 500;\nconst TRACE_UPLOAD_RETRY_MAX_DELAY_MS = 10_000;\nconst TRACE_UPLOAD_MAX_RETRIES = 3;\nconst TRACE_UPLOAD_RETRY_JITTER = 0.2;\nconst TRACE_PREVIEW_MAX_CHARS = 8_000;\nconst TRACE_UPLOAD_ALL_CONCURRENCY = 4;\nconst TRACE_UPLOAD_RATE_LIMIT_REQUESTS = 5;\nconst TRACE_UPLOAD_RATE_LIMIT_WINDOW_MS = 60_000;\nconst TRACE_UPLOAD_RATE_LIMIT_SAFETY_MS = 100;\nconst MAX_TIMER_DELAY_MS = 2 ** 31 - 1;\nconst TRACE_UPLOAD_ALL_MIN_REQUEST_INTERVAL_MS =\n\tMath.ceil(TRACE_UPLOAD_RATE_LIMIT_WINDOW_MS / TRACE_UPLOAD_RATE_LIMIT_REQUESTS) + TRACE_UPLOAD_RATE_LIMIT_SAFETY_MS;\n\nexport type AgentTraceCredentialSource = \"environment\" | \"stored\";\n\nexport interface AgentTraceCredential {\n\tapiKey: string;\n\tsource: AgentTraceCredentialSource;\n\tlabel: string;\n}\n\nexport type AgentTraceUploadResult =\n\t| {\n\t\t\tstatus: \"uploaded\";\n\t\t\tsessionId: string;\n\t\t\ttraceId: string;\n\t\t\tbytesStored: number;\n\t\t\tkey?: string;\n\t  }\n\t| { status: \"disabled\" }\n\t| { status: \"unchanged\" }\n\t| { status: \"missing_credentials\" }\n\t| { status: \"no_session_file\" }\n\t| { status: \"empty_session\" }\n\t| { status: \"invalid_session\"; message: string }\n\t| { status: \"too_large\"; size: number; maxBytes: number }\n\t| { status: \"failed\"; statusCode?: number; message: string; retryAfterMs?: number };\n\nexport interface AgentTraceUploadOptions {\n\tsessionFile: string | undefined;\n\tauthStorage: AuthStorage;\n\tsettingsManager: SettingsManager;\n\t/** Require the global automatic-sharing opt-in. Set false only for an explicit one-shot upload command. */\n\trequireEnabled?: boolean;\n\tbaseUrl?: string;\n\tconfigPath?: string;\n\tfetchFn?: typeof fetch;\n\treloadConfig?: boolean;\n\trequestTimeoutMs?: number;\n\tsignal?: AbortSignal;\n}\n\nexport interface AgentTraceSessionUploadOptions extends Omit<AgentTraceUploadOptions, \"sessionFile\"> {\n\tsessionManager: SessionManager;\n}\n\nexport interface AgentTraceUploadInstallOptions {\n\tauthStorage: AuthStorage;\n\tsettingsManager: SettingsManager;\n\tbaseUrl?: string;\n\tconfigPath?: string;\n\tfetchFn?: typeof fetch;\n\trequestTimeoutMs?: number;\n\t/** The session's semantic-edge ledger; registered with the outbox as its own delivery kind. */\n\tsemanticEdgesLedgerPath?: string;\n}\n\nexport type AgentTracePreviewResult =\n\t| {\n\t\t\tstatus: \"ready\";\n\t\t\tsessionFile: string;\n\t\t\tsessionId: string;\n\t\t\ttraceId: string;\n\t\t\tparentSessionId?: string;\n\t\t\tcwd: string;\n\t\t\tsize: number;\n\t\t\tmaxBytes: number;\n\t\t\tuploadable: boolean;\n\t\t\tendpoint?: string;\n\t\t\tgitRepo?: string;\n\t\t\tgitCommit?: string;\n\t\t\tcontentPreview: string;\n\t\t\ttruncated: boolean;\n\t  }\n\t| { status: \"no_session_file\" }\n\t| { status: \"empty_session\" }\n\t| { status: \"invalid_session\"; message: string }\n\t| { status: \"failed\"; message: string };\n\nexport interface AgentTracePreviewOptions {\n\tsessionFile: string | undefined;\n\tbaseUrl?: string;\n\tmaxContentChars?: number;\n}\n\nexport interface AgentTraceUploadAllProgress {\n\tcompleted: number;\n\ttotal: number;\n\tsessionFile?: string;\n\tresult?: AgentTraceUploadResult;\n}\n\nexport interface AgentTraceUploadAllOptions extends Omit<AgentTraceUploadOptions, \"sessionFile\"> {\n\tsessionDir?: string;\n\tconcurrency?: number;\n\tonProgress?: (progress: AgentTraceUploadAllProgress) => void;\n}\n\nexport interface AgentTraceUploadAllResult {\n\ttotal: number;\n\tuploaded: number;\n\tfailed: number;\n\tskipped: number;\n\tbytesStored: number;\n\tresults: Array<{ sessionFile: string; result: AgentTraceUploadResult }>;\n}\n\nfunction stringEnv(name: string): string | undefined {\n\tconst value = process.env[name];\n\treturn typeof value === \"string\" && value.trim() ? value.trim() : undefined;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction describeError(error: unknown): string {\n\tif (!(error instanceof Error)) {\n\t\treturn String(error);\n\t}\n\tconst cause = (error as { cause?: unknown }).cause;\n\tif (isRecord(cause)) {\n\t\tconst code = typeof cause.code === \"string\" ? cause.code : undefined;\n\t\tconst causeMessage = typeof cause.message === \"string\" ? cause.message : undefined;\n\t\tconst detail = code ?? causeMessage;\n\t\tif (detail && detail !== error.message) {\n\t\t\treturn `${error.message} (${detail})`;\n\t\t}\n\t}\n\treturn error.message;\n}\n\nclass TraceUploadTimeoutError extends Error {\n\tconstructor(timeoutMs: number) {\n\t\tsuper(`Trace upload timed out after ${timeoutMs}ms`);\n\t\tthis.name = \"TraceUploadTimeoutError\";\n\t}\n}\n\nconst RETRIABLE_NETWORK_CODES = new Set([\n\t\"ECONNRESET\",\n\t\"ECONNREFUSED\",\n\t\"ECONNABORTED\",\n\t\"EPIPE\",\n\t\"ETIMEDOUT\",\n\t\"ENETUNREACH\",\n\t\"ENETDOWN\",\n\t\"EAI_AGAIN\",\n\t\"UND_ERR_SOCKET\",\n\t\"UND_ERR_CONNECT_TIMEOUT\",\n]);\n\n// 429 is deliberately absent: a rate-limited upload is rescheduled by its caller instead of sleeping in-request.\nconst RETRIABLE_HTTP_STATUSES = new Set([408, 425, 500, 502, 503, 504]);\n\nfunction isRetriableNetworkError(error: unknown): boolean {\n\tif (error instanceof TraceUploadTimeoutError) {\n\t\treturn true;\n\t}\n\tif (!(error instanceof Error) || error.name === \"AbortError\") {\n\t\treturn false;\n\t}\n\tconst cause = (error as { cause?: unknown }).cause;\n\treturn isRecord(cause) && typeof cause.code === \"string\" && RETRIABLE_NETWORK_CODES.has(cause.code);\n}\n\nfunction stringField(data: Record<string, unknown>, key: string): string | undefined {\n\tconst value = data[key];\n\treturn typeof value === \"string\" && value.trim() ? value.trim() : undefined;\n}\n\nfunction numberField(data: Record<string, unknown>, key: string): number | undefined {\n\tconst value = data[key];\n\treturn typeof value === \"number\" && Number.isFinite(value) ? value : undefined;\n}\n\nfunction isSessionHeader(value: unknown): value is SessionHeader {\n\treturn (\n\t\tisRecord(value) &&\n\t\tvalue.type === \"session\" &&\n\t\ttypeof value.id === \"string\" &&\n\t\ttypeof value.timestamp === \"string\" &&\n\t\ttypeof value.cwd === \"string\" &&\n\t\t(value.parentSession === undefined || typeof value.parentSession === \"string\")\n\t);\n}\n\nfunction readSessionHeader(sessionFile: string): SessionHeader | undefined {\n\ttry {\n\t\tconst parsed = readSessionJournalHeader(sessionFile);\n\t\treturn isSessionHeader(parsed) ? parsed : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nasync function readSessionTraceBody(sessionFile: string): Promise<string> {\n\tconst lines: string[] = [];\n\tfor await (const { json } of readSessionJournal(sessionFile)) {\n\t\tlines.push(`${json}\\n`);\n\t}\n\treturn lines.join(\"\");\n}\n\n/** Active-branch git for the indexing headers: walk leaf to root, not the last git_state in\n * file order (which may belong to a sibling branch). */\nexport function activeGitContext(\n\tbody: string,\n\theader: SessionHeader,\n): { repoUrl?: string; commit?: string } | undefined {\n\tconst byId = new Map<string, { parentId: string | null; type: string; git?: unknown }>();\n\tlet leafId: string | null = null;\n\tfor (const line of body.split(\"\\n\")) {\n\t\tif (!line.trim()) continue;\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(line);\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tif (!isRecord(parsed) || parsed.type === \"session\" || typeof parsed.id !== \"string\") continue;\n\t\tbyId.set(parsed.id, {\n\t\t\tparentId: typeof parsed.parentId === \"string\" ? parsed.parentId : null,\n\t\t\ttype: typeof parsed.type === \"string\" ? parsed.type : \"\",\n\t\t\tgit: parsed.git,\n\t\t});\n\t\tleafId = parsed.id;\n\t}\n\n\tlet current = leafId ? byId.get(leafId) : undefined;\n\tfor (let depth = 0; current && depth < byId.size + 1; depth += 1) {\n\t\tif (current.type === \"git_state\" && isRecord(current.git)) {\n\t\t\treturn current.git as { repoUrl?: string; commit?: string };\n\t\t}\n\t\tcurrent = current.parentId ? byId.get(current.parentId) : undefined;\n\t}\n\treturn header.git;\n}\n\nfunction resolveParentSessionPath(sessionFile: string, parentSession: string): string {\n\treturn isAbsolute(parentSession) ? parentSession : resolve(dirname(sessionFile), parentSession);\n}\n\nfunction resolveTraceContext(\n\tsessionFile: string,\n\theader: SessionHeader,\n): { traceId: string; parentSessionId?: string } {\n\tlet traceId = header.id;\n\tlet parentSessionId: string | undefined;\n\tlet currentFile = sessionFile;\n\tlet currentHeader = header;\n\n\tfor (let depth = 0; depth < 32; depth += 1) {\n\t\tif (!currentHeader.parentSession) {\n\t\t\tbreak;\n\t\t}\n\n\t\tconst parentPath = resolveParentSessionPath(currentFile, currentHeader.parentSession);\n\t\tconst parentHeader = readSessionHeader(parentPath);\n\t\tif (!parentHeader) {\n\t\t\tbreak;\n\t\t}\n\n\t\tif (depth === 0) {\n\t\t\tparentSessionId = parentHeader.id;\n\t\t}\n\t\ttraceId = parentHeader.id;\n\t\tcurrentFile = parentPath;\n\t\tcurrentHeader = parentHeader;\n\t}\n\n\treturn { traceId, parentSessionId };\n}\n\nfunction parseResponseObject(text: string): Record<string, unknown> | undefined {\n\tif (!text.trim()) {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\tconst parsed = JSON.parse(text) as unknown;\n\t\treturn isRecord(parsed) ? parsed : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nasync function readResponseMessage(response: Response): Promise<string> {\n\tconst text = await response.text().catch(() => \"\");\n\tif (!text.trim()) {\n\t\treturn response.statusText || \"Unknown error\";\n\t}\n\n\tconst parsed = parseResponseObject(text);\n\tif (parsed) {\n\t\tconst error = parsed.error;\n\t\tif (isRecord(error)) {\n\t\t\tconst message = stringField(error, \"message\");\n\t\t\tif (message) return message;\n\t\t}\n\t\tconst detail = stringField(parsed, \"detail\");\n\t\tif (detail) return detail;\n\t\tconst message = stringField(parsed, \"message\");\n\t\tif (message) return message;\n\t}\n\n\treturn text.trim();\n}\n\nasync function fetchWithTimeout(\n\tfetchFn: typeof fetch,\n\turl: string,\n\tinit: RequestInit,\n\ttimeoutMs: number,\n\tsignal?: AbortSignal,\n): Promise<Response> {\n\tconst controller = new AbortController();\n\tconst timeoutError = new TraceUploadTimeoutError(timeoutMs);\n\tlet timedOut = false;\n\tconst timeout = setTimeout(() => {\n\t\ttimedOut = true;\n\t\tcontroller.abort(timeoutError);\n\t}, timeoutMs);\n\ttimeout.unref();\n\tconst onAbort = () => controller.abort(signal?.reason);\n\tif (signal?.aborted) {\n\t\tonAbort();\n\t} else {\n\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t}\n\n\ttry {\n\t\treturn await fetchFn(url, { ...init, signal: controller.signal });\n\t} catch (error) {\n\t\tif (timedOut) {\n\t\t\tthrow timeoutError;\n\t\t}\n\t\tthrow error;\n\t} finally {\n\t\tclearTimeout(timeout);\n\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t}\n}\n\nfunction delay(ms: number, signal?: AbortSignal): Promise<void> {\n\treturn new Promise((resolve) => {\n\t\tif (signal?.aborted) {\n\t\t\tresolve();\n\t\t\treturn;\n\t\t}\n\t\tconst timeout = setTimeout(finish, ms);\n\t\ttimeout.unref();\n\t\tconst onAbort = () => finish();\n\t\tfunction finish() {\n\t\t\tclearTimeout(timeout);\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\tresolve();\n\t\t}\n\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t});\n}\n\nfunction traceUploadRetryDelay(retryIndex: number): number {\n\tconst exponentialDelay = Math.min(\n\t\tTRACE_UPLOAD_RETRY_MAX_DELAY_MS,\n\t\tTRACE_UPLOAD_RETRY_BASE_DELAY_MS * 2 ** retryIndex,\n\t);\n\tconst jitterMultiplier = 1 - TRACE_UPLOAD_RETRY_JITTER + Math.random() * TRACE_UPLOAD_RETRY_JITTER * 2;\n\treturn Math.max(0, Math.round(exponentialDelay * jitterMultiplier));\n}\n\nfunction retryAfterDelay(response: Response, capMs: number = TRACE_UPLOAD_RATE_LIMIT_WINDOW_MS): number | undefined {\n\tconst value = response.headers.get(\"retry-after\")?.trim();\n\tif (!value) {\n\t\treturn undefined;\n\t}\n\tconst seconds = Number(value);\n\tif (Number.isFinite(seconds) && seconds >= 0) {\n\t\treturn Math.min(Math.ceil(seconds * 1_000), capMs);\n\t}\n\tconst retryAt = Date.parse(value);\n\treturn Number.isFinite(retryAt) ? Math.min(Math.max(0, retryAt - Date.now()), capMs) : undefined;\n}\n\ntype BeforeTraceUploadRequest = () => Promise<void>;\n\nasync function fetchWithRetry(\n\tfetchFn: typeof fetch,\n\turl: string,\n\tinit: RequestInit,\n\ttimeoutMs: number,\n\tsignal?: AbortSignal,\n\tbeforeRequest?: BeforeTraceUploadRequest,\n): Promise<Response> {\n\tfor (let attempt = 0; ; attempt += 1) {\n\t\tlet retryDelayMs: number | undefined;\n\t\ttry {\n\t\t\tawait beforeRequest?.();\n\t\t\tif (signal?.aborted) {\n\t\t\t\tthrow signal.reason ?? new Error(\"Trace upload cancelled\");\n\t\t\t}\n\t\t\tconst response = await fetchWithTimeout(fetchFn, url, init, timeoutMs, signal);\n\t\t\tif (attempt >= TRACE_UPLOAD_MAX_RETRIES || !RETRIABLE_HTTP_STATUSES.has(response.status)) {\n\t\t\t\treturn response;\n\t\t\t}\n\t\t\tif (response.status === 503) {\n\t\t\t\tretryDelayMs = retryAfterDelay(response);\n\t\t\t}\n\t\t\tawait response.body?.cancel().catch(() => undefined);\n\t\t} catch (error) {\n\t\t\tif (signal?.aborted) {\n\t\t\t\tthrow signal.reason ?? error;\n\t\t\t}\n\t\t\tif (attempt >= TRACE_UPLOAD_MAX_RETRIES || !isRetriableNetworkError(error)) {\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\n\t\tawait delay(retryDelayMs ?? traceUploadRetryDelay(attempt), signal);\n\t\tif (signal?.aborted) {\n\t\t\tthrow signal.reason ?? new Error(\"Trace upload cancelled\");\n\t\t}\n\t}\n}\n\nfunction traceContentPreview(body: string, maxChars: number): { content: string; truncated: boolean } {\n\tif (body.length <= maxChars) {\n\t\treturn { content: body.trimEnd(), truncated: false };\n\t}\n\tconst marker = \"\\n... middle of trace omitted ...\\n\";\n\tconst available = Math.max(0, maxChars - marker.length);\n\tconst headChars = Math.ceil(available / 2);\n\tconst tailChars = Math.floor(available / 2);\n\treturn {\n\t\tcontent: `${body.slice(0, headChars).trimEnd()}${marker}${body.slice(body.length - tailChars).trimStart()}`,\n\t\ttruncated: true,\n\t};\n}\n\nexport async function previewAgentTraceFile(options: AgentTracePreviewOptions): Promise<AgentTracePreviewResult> {\n\tif (!options.sessionFile) {\n\t\treturn { status: \"no_session_file\" };\n\t}\n\n\tlet fileSize: number;\n\ttry {\n\t\tconst stats = await stat(options.sessionFile);\n\t\tif (!stats.isFile()) {\n\t\t\treturn { status: \"no_session_file\" };\n\t\t}\n\t\tfileSize = stats.size;\n\t} catch {\n\t\treturn { status: \"no_session_file\" };\n\t}\n\tif (fileSize === 0) {\n\t\treturn { status: \"empty_session\" };\n\t}\n\n\tconst header = readSessionHeader(options.sessionFile);\n\tif (!header) {\n\t\treturn { status: \"invalid_session\", message: \"Session file is missing a valid session header\" };\n\t}\n\n\tlet body = \"\";\n\tif (fileSize <= MAX_TRACE_BYTES) {\n\t\ttry {\n\t\t\tbody = await readSessionTraceBody(options.sessionFile);\n\t\t} catch (error) {\n\t\t\treturn { status: \"failed\", message: describeError(error) };\n\t\t}\n\t\tif (!body.trim()) {\n\t\t\treturn { status: \"empty_session\" };\n\t\t}\n\t}\n\n\tconst traceContext = resolveTraceContext(options.sessionFile, header);\n\tconst baseUrl = resolvePrimeAgentTracesBaseUrl(options.baseUrl);\n\tconst git = body ? activeGitContext(body, header) : header.git;\n\tconst preview = body\n\t\t? traceContentPreview(body, Math.max(256, options.maxContentChars ?? TRACE_PREVIEW_MAX_CHARS))\n\t\t: { content: \"\", truncated: true };\n\treturn {\n\t\tstatus: \"ready\",\n\t\tsessionFile: options.sessionFile,\n\t\tsessionId: header.id,\n\t\ttraceId: traceContext.traceId,\n\t\tparentSessionId: traceContext.parentSessionId,\n\t\tcwd: header.cwd,\n\t\tsize: fileSize,\n\t\tmaxBytes: MAX_TRACE_BYTES,\n\t\tuploadable: fileSize <= MAX_TRACE_BYTES && baseUrl !== undefined,\n\t\tendpoint: baseUrl ? `${baseUrl}/api/v1/agent-traces/sessions/${encodeURIComponent(header.id)}` : undefined,\n\t\tgitRepo: git?.repoUrl,\n\t\tgitCommit: git?.commit,\n\t\tcontentPreview: preview.content,\n\t\ttruncated: preview.truncated,\n\t};\n}\n\nasync function findSessionFilesUnder(root: string, files: Set<string>): Promise<void> {\n\tlet entries: Dirent[];\n\ttry {\n\t\tentries = await readdir(root, { withFileTypes: true });\n\t} catch {\n\t\treturn;\n\t}\n\n\tfor (const entry of entries) {\n\t\tconst entryPath = join(root, entry.name);\n\t\tif (entry.isDirectory()) {\n\t\t\tawait findSessionFilesUnder(entryPath, files);\n\t\t\tcontinue;\n\t\t}\n\t\tif (entry.isFile() && entry.name.endsWith(\".jsonl\") && readSessionHeader(entryPath)) {\n\t\t\tfiles.add(entryPath);\n\t\t}\n\t}\n}\n\nexport async function findAgentTraceFiles(sessionDir: string = getSessionsDir()): Promise<string[]> {\n\tconst files = new Set<string>();\n\tconst roots = new Set([resolve(sessionDir), resolve(getSessionArtifactsRoot(sessionDir))]);\n\tawait Promise.all([...roots].map((root) => findSessionFilesUnder(root, files)));\n\treturn [...files].sort();\n}\n\nfunction createTraceUploadAllRequestGate(signal?: AbortSignal): BeforeTraceUploadRequest {\n\tlet nextRequestAt = 0;\n\tlet queue = Promise.resolve();\n\treturn () => {\n\t\tconst slot = queue.then(async () => {\n\t\t\tconst waitMs = Math.max(0, nextRequestAt - Date.now());\n\t\t\tif (waitMs > 0) {\n\t\t\t\tawait delay(waitMs, signal);\n\t\t\t}\n\t\t\tif (!signal?.aborted) {\n\t\t\t\tnextRequestAt = Date.now() + TRACE_UPLOAD_ALL_MIN_REQUEST_INTERVAL_MS;\n\t\t\t}\n\t\t});\n\t\tqueue = slot.catch(() => undefined);\n\t\treturn slot;\n\t};\n}\n\nexport async function uploadAllAgentTraces(options: AgentTraceUploadAllOptions): Promise<AgentTraceUploadAllResult> {\n\tconst { sessionDir, concurrency, onProgress, ...uploadOptions } = options;\n\tconst sessionFiles = await findAgentTraceFiles(sessionDir);\n\ttype UploadResultItem = AgentTraceUploadAllResult[\"results\"][number];\n\tconst results: Array<UploadResultItem | undefined> = new Array(sessionFiles.length);\n\tlet cursor = 0;\n\tlet completed = 0;\n\tconst beforeRequest = createTraceUploadAllRequestGate(uploadOptions.signal);\n\tonProgress?.({ completed, total: sessionFiles.length });\n\n\tconst worker = async () => {\n\t\twhile (true) {\n\t\t\tif (uploadOptions.signal?.aborted) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst index = cursor;\n\t\t\tcursor += 1;\n\t\t\tconst sessionFile = sessionFiles[index];\n\t\t\tif (!sessionFile) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst result = await uploadAgentTraceFileWithRequestGate(\n\t\t\t\t{\n\t\t\t\t\t...uploadOptions,\n\t\t\t\t\tsessionFile,\n\t\t\t\t\treloadConfig: false,\n\t\t\t\t},\n\t\t\t\tbeforeRequest,\n\t\t\t);\n\t\t\tif (uploadOptions.signal?.aborted && result.status === \"failed\") {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tresults[index] = { sessionFile, result };\n\t\t\tcompleted += 1;\n\t\t\tonProgress?.({ completed, total: sessionFiles.length, sessionFile, result });\n\t\t}\n\t};\n\n\tconst requestedConcurrency = concurrency ?? TRACE_UPLOAD_ALL_CONCURRENCY;\n\tconst normalizedConcurrency =\n\t\tNumber.isFinite(requestedConcurrency) && requestedConcurrency > 0\n\t\t\t? Math.max(1, Math.floor(requestedConcurrency))\n\t\t\t: TRACE_UPLOAD_ALL_CONCURRENCY;\n\tconst workerCount = Math.min(sessionFiles.length, normalizedConcurrency);\n\tawait Promise.all(Array.from({ length: workerCount }, worker));\n\n\tconst completedResults = results.filter((item): item is UploadResultItem => item !== undefined);\n\tlet uploaded = 0;\n\tlet failed = 0;\n\tlet bytesStored = 0;\n\tfor (const item of completedResults) {\n\t\tif (item.result.status === \"uploaded\") {\n\t\t\tuploaded += 1;\n\t\t\tbytesStored += item.result.bytesStored;\n\t\t} else if (item.result.status === \"failed\") {\n\t\t\tfailed += 1;\n\t\t}\n\t}\n\treturn {\n\t\ttotal: sessionFiles.length,\n\t\tuploaded,\n\t\tfailed,\n\t\tskipped: sessionFiles.length - uploaded - failed,\n\t\tbytesStored,\n\t\tresults: completedResults,\n\t};\n}\n\ninterface AgentTraceUploadedSignature {\n\tsize: number;\n\tmtimeMs: number;\n}\n\nexport const SEMANTIC_EDGES_OUTBOX_KIND = \"semantic-edges\";\n\nexport interface AgentTraceCatchUpResult {\n\tpruned: number;\n\t/** Registered semantic-edge ledgers with bytes beyond their cursor; no delivery endpoint exists yet. */\n\tsemanticEdgeLedgersPending: number;\n\tresults: Array<{ sessionFile: string; result: AgentTraceUploadResult }>;\n}\n\nfunction getAgentTraceOutboxDir(): string {\n\treturn assertProductStatePath(join(getAgentDir(), \"trace-export-outbox\"));\n}\n\n// One entry file per session file (keyed by path hash): concurrent writers cannot lose each other's cursors, and a bad read costs only its own entry.\nfunction agentTraceOutboxEntryPath(sessionFile: string): string {\n\tconst key = createHash(\"sha256\").update(sessionFile).digest(\"hex\").slice(0, 32);\n\treturn join(getAgentTraceOutboxDir(), `${key}.json`);\n}\n\nfunction parseOutboxEntry(raw: string):\n\t| {\n\t\t\tsessionFile: string;\n\t\t\tkind?: string;\n\t\t\tuploaded: AgentTraceUploadedSignature | null;\n\t\t\tuploadedBytes?: number;\n\t  }\n\t| undefined {\n\tconst parsed = parseResponseObject(raw);\n\tif (!parsed || typeof parsed.sessionFile !== \"string\") {\n\t\treturn undefined;\n\t}\n\tconst uploaded =\n\t\ttypeof parsed.size === \"number\" && typeof parsed.mtimeMs === \"number\"\n\t\t\t? { size: parsed.size, mtimeMs: parsed.mtimeMs }\n\t\t\t: null;\n\treturn {\n\t\tsessionFile: parsed.sessionFile,\n\t\tkind: typeof parsed.kind === \"string\" ? parsed.kind : undefined,\n\t\tuploaded,\n\t\tuploadedBytes: typeof parsed.uploadedBytes === \"number\" ? parsed.uploadedBytes : undefined,\n\t};\n}\n\n/** `undefined` = no usable cursor; `null` = scheduled but never uploaded. */\nasync function readAgentTraceOutboxEntry(sessionFile: string): Promise<AgentTraceUploadedSignature | null | undefined> {\n\tlet raw: string;\n\ttry {\n\t\traw = await readFile(agentTraceOutboxEntryPath(sessionFile), \"utf8\");\n\t} catch {\n\t\treturn undefined;\n\t}\n\tconst entry = parseOutboxEntry(raw);\n\treturn entry && entry.sessionFile === sessionFile ? entry.uploaded : undefined;\n}\n\nfunction signatureEquals(a: AgentTraceUploadedSignature | null | undefined, b: AgentTraceUploadedSignature): boolean {\n\treturn a != null && a.size === b.size && a.mtimeMs === b.mtimeMs;\n}\n\n/** Session files with a live upload controller in this process; catch-up leaves them to their controller. */\nconst locallyManagedSessionFiles = new Set<string>();\n\n/** Best-effort and synchronous: upload intent must be on disk the moment the transcript persist returns. */\nfunction markAgentTraceOutboxPendingSync(sessionFile: string, kind?: string): boolean {\n\ttry {\n\t\tconst entryPath = agentTraceOutboxEntryPath(sessionFile);\n\t\tif (existsSync(entryPath)) {\n\t\t\treturn true;\n\t\t}\n\t\tmkdirSync(getAgentTraceOutboxDir(), { recursive: true });\n\t\tconst tempPath = `${entryPath}.${process.pid}.${randomUUID()}.tmp`;\n\t\twriteFileSync(\n\t\t\ttempPath,\n\t\t\t`${JSON.stringify(kind === undefined ? { sessionFile } : { sessionFile, kind })}\\n`,\n\t\t\t\"utf8\",\n\t\t);\n\t\trenameSync(tempPath, entryPath);\n\t\treturn true;\n\t} catch {\n\t\t// A broken agent dir must not break session persists.\n\t\treturn false;\n\t}\n}\n\nasync function recordAgentTraceOutboxUpload(\n\tsessionFile: string,\n\tsignature: AgentTraceUploadedSignature,\n): Promise<void> {\n\tconst entryPath = agentTraceOutboxEntryPath(sessionFile);\n\tawait mkdir(getAgentTraceOutboxDir(), { recursive: true });\n\tconst tempPath = `${entryPath}.${process.pid}.${randomUUID()}.tmp`;\n\tawait writeFile(tempPath, `${JSON.stringify({ sessionFile, ...signature })}\\n`, \"utf8\");\n\tawait rename(tempPath, entryPath);\n}\n\n/**\n * Explicit catch-up for the Base Context export outbox. This is never run at\n * startup and does not read inherited agent-traces-outbox entries.\n */\nexport async function catchUpAgentTraceUploads(\n\toptions: Omit<AgentTraceUploadOptions, \"sessionFile\">,\n): Promise<AgentTraceCatchUpResult> {\n\tconst catchUp: AgentTraceCatchUpResult = { pruned: 0, semanticEdgeLedgersPending: 0, results: [] };\n\tif (options.requireEnabled !== false && !(await getAgentTracesEnabled(options))) {\n\t\treturn catchUp;\n\t}\n\tlet entryNames: string[];\n\ttry {\n\t\tentryNames = await readdir(getAgentTraceOutboxDir());\n\t} catch {\n\t\treturn catchUp;\n\t}\n\tconst beforeRequest = createTraceUploadAllRequestGate(options.signal);\n\tfor (const entryName of entryNames) {\n\t\tif (options.signal?.aborted) {\n\t\t\tbreak;\n\t\t}\n\t\tif (!entryName.endsWith(\".json\")) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst entryPath = join(getAgentTraceOutboxDir(), entryName);\n\t\tlet raw: string;\n\t\ttry {\n\t\t\traw = await readFile(entryPath, \"utf8\");\n\t\t} catch {\n\t\t\t// Transient read error: keep the entry and retry at the next startup.\n\t\t\tcontinue;\n\t\t}\n\t\tconst entry = parseOutboxEntry(raw);\n\t\tif (!entry) {\n\t\t\tawait unlink(entryPath).catch(() => undefined);\n\t\t\tcatchUp.pruned += 1;\n\t\t\tcontinue;\n\t\t}\n\t\tif (entry.kind === SEMANTIC_EDGES_OUTBOX_KIND) {\n\t\t\tlet ledgerStats: Awaited<ReturnType<typeof stat>>;\n\t\t\ttry {\n\t\t\t\tledgerStats = await stat(entry.sessionFile);\n\t\t\t} catch (error) {\n\t\t\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n\t\t\t\t\tawait unlink(entryPath).catch(() => undefined);\n\t\t\t\t\tcatchUp.pruned += 1;\n\t\t\t\t}\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!ledgerStats.isFile()) {\n\t\t\t\tawait unlink(entryPath).catch(() => undefined);\n\t\t\t\tcatchUp.pruned += 1;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\t// Append-only byte cursor: a ledger whose size equals its delivered offset has nothing new.\n\t\t\tif (ledgerStats.size === entry.uploadedBytes) {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\t// No delivery endpoint exists yet (verifiers#2449 consumes edges in-band over ACP\n\t\t\t// metadata; the trace server has no semantic-edges route). The delta and cursor stay\n\t\t\t// untouched so the first real sender delivers the whole backlog.\n\t\t\tcatchUp.semanticEdgeLedgersPending += 1;\n\t\t\tcontinue;\n\t\t}\n\t\tif (entry.kind !== undefined) {\n\t\t\t// A newer build may register kinds this one cannot deliver; leave their cursors alone.\n\t\t\tcontinue;\n\t\t}\n\t\tif (locallyManagedSessionFiles.has(entry.sessionFile)) {\n\t\t\tcontinue;\n\t\t}\n\t\tlet stats: Awaited<ReturnType<typeof stat>>;\n\t\ttry {\n\t\t\tstats = await stat(entry.sessionFile);\n\t\t} catch (error) {\n\t\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n\t\t\t\tawait unlink(entryPath).catch(() => undefined);\n\t\t\t\tcatchUp.pruned += 1;\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\tif (!stats.isFile()) {\n\t\t\tawait unlink(entryPath).catch(() => undefined);\n\t\t\tcatchUp.pruned += 1;\n\t\t\tcontinue;\n\t\t}\n\t\tif (signatureEquals(entry.uploaded, { size: stats.size, mtimeMs: stats.mtimeMs })) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst result = await uploadAgentTraceFileWithRequestGate(\n\t\t\t{ ...options, sessionFile: entry.sessionFile, reloadConfig: false },\n\t\t\tbeforeRequest,\n\t\t);\n\t\tcatchUp.results.push({ sessionFile: entry.sessionFile, result });\n\t}\n\treturn catchUp;\n}\n\nexport async function getPrimeAgentTraceCredential(\n\tauthStorage: AuthStorage,\n\toptions: { reloadAuth?: boolean; configPath?: string } = {},\n): Promise<AgentTraceCredential | undefined> {\n\tconst traceEnvKey = stringEnv(\"BASE_CONTEXT_TRACES_API_KEY\");\n\tif (traceEnvKey) {\n\t\treturn { apiKey: traceEnvKey, source: \"environment\", label: \"BASE_CONTEXT_TRACES_API_KEY\" };\n\t}\n\n\tif (options.reloadAuth !== false) {\n\t\tauthStorage.reload();\n\t}\n\n\tconst traceKey = await authStorage.getApiKey(BASE_CONTEXT_TRACES_PROVIDER_ID, { includeFallback: false });\n\tif (traceKey) {\n\t\treturn { apiKey: traceKey, source: \"stored\", label: \"Base Context Traces credential\" };\n\t}\n\n\treturn undefined;\n}\n\nasync function getAgentTracesEnabled(\n\toptions: Pick<AgentTraceUploadOptions, \"reloadConfig\" | \"settingsManager\">,\n): Promise<boolean> {\n\tif (options.reloadConfig !== false) {\n\t\tawait options.settingsManager.reload().catch(() => undefined);\n\t}\n\treturn options.settingsManager.getAgentTracesEnabled();\n}\n\nasync function uploadAgentTraceFileWithRequestGate(\n\toptions: AgentTraceUploadOptions,\n\tbeforeRequest?: BeforeTraceUploadRequest,\n): Promise<AgentTraceUploadResult> {\n\tconst result = await performAgentTraceUpload(options, beforeRequest);\n\tlogAgentTraceOutcome(options.sessionFile, result);\n\treturn result;\n}\n\nexport function uploadAgentTraceFile(options: AgentTraceUploadOptions): Promise<AgentTraceUploadResult> {\n\treturn uploadAgentTraceFileWithRequestGate(options);\n}\n\nfunction logAgentTraceOutcome(sessionFile: string | undefined, result: AgentTraceUploadResult): void {\n\tlet line: string | undefined;\n\tswitch (result.status) {\n\t\tcase \"uploaded\":\n\t\t\tline = `uploaded session ${result.sessionId} (${result.bytesStored} bytes)`;\n\t\t\tbreak;\n\t\tcase \"failed\":\n\t\t\tline = `upload failed${result.statusCode ? ` (HTTP ${result.statusCode})` : \"\"}: ${result.message}`;\n\t\t\tbreak;\n\t\tcase \"too_large\":\n\t\t\tline = `upload skipped: session is ${result.size} bytes (limit ${result.maxBytes})`;\n\t\t\tbreak;\n\t\tcase \"invalid_session\":\n\t\t\tline = `upload skipped: ${result.message}`;\n\t\t\tbreak;\n\t\tcase \"missing_credentials\":\n\t\t\tline = \"upload skipped: configure a dedicated BASE_CONTEXT_TRACES_API_KEY or Base Context Traces credential\";\n\t\t\tbreak;\n\t\tdefault:\n\t\t\treturn;\n\t}\n\tconst suffix = sessionFile ? ` [${sessionFile}]` : \"\";\n\tappendRotatingLog(getAgentTracesLogPath(), `[${new Date().toISOString()}] ${line}${suffix}`);\n}\n\nasync function performAgentTraceUpload(\n\toptions: AgentTraceUploadOptions,\n\tbeforeRequest?: BeforeTraceUploadRequest,\n): Promise<AgentTraceUploadResult> {\n\tconst requireEnabled = options.requireEnabled !== false;\n\tif (requireEnabled && !(await getAgentTracesEnabled(options))) {\n\t\treturn { status: \"disabled\" };\n\t}\n\tconst baseUrl = resolvePrimeAgentTracesBaseUrl(options.baseUrl);\n\tif (!baseUrl) {\n\t\treturn {\n\t\t\tstatus: \"failed\",\n\t\t\tmessage:\n\t\t\t\t\"Trace export requires an explicit BASE_CONTEXT_TRACES_BASE_URL and dedicated BASE_CONTEXT_TRACES_API_KEY.\",\n\t\t};\n\t}\n\tif (!options.sessionFile) {\n\t\treturn { status: \"no_session_file\" };\n\t}\n\n\tlet signature: AgentTraceUploadedSignature;\n\ttry {\n\t\tconst stats = await stat(options.sessionFile);\n\t\tif (!stats.isFile()) {\n\t\t\treturn { status: \"no_session_file\" };\n\t\t}\n\t\tsignature = { size: stats.size, mtimeMs: stats.mtimeMs };\n\t} catch {\n\t\treturn { status: \"no_session_file\" };\n\t}\n\tconst fileSize = signature.size;\n\tif (fileSize === 0) {\n\t\treturn { status: \"empty_session\" };\n\t}\n\tif (fileSize > MAX_TRACE_BYTES) {\n\t\treturn { status: \"too_large\", size: fileSize, maxBytes: MAX_TRACE_BYTES };\n\t}\n\t// Cursor invariant: an automatic upload never re-sends a file whose content already matches its uploaded cursor.\n\tif (requireEnabled && signatureEquals(await readAgentTraceOutboxEntry(options.sessionFile), signature)) {\n\t\treturn { status: \"unchanged\" };\n\t}\n\n\tconst header = readSessionHeader(options.sessionFile);\n\tif (!header) {\n\t\treturn { status: \"invalid_session\", message: \"Session file is missing a valid session header\" };\n\t}\n\n\tconst credential = await getPrimeAgentTraceCredential(options.authStorage, {\n\t\tconfigPath: options.configPath,\n\t\treloadAuth: options.reloadConfig !== false,\n\t});\n\tif (!credential) {\n\t\treturn { status: \"missing_credentials\" };\n\t}\n\n\tif (requireEnabled && !(await getAgentTracesEnabled(options))) {\n\t\treturn { status: \"disabled\" };\n\t}\n\n\tlet body: string;\n\ttry {\n\t\tbody = await readSessionTraceBody(options.sessionFile);\n\t} catch (error) {\n\t\treturn { status: \"failed\", message: describeError(error) };\n\t}\n\tif (!body.trim()) {\n\t\treturn { status: \"empty_session\" };\n\t}\n\n\tconst traceContext = resolveTraceContext(options.sessionFile, header);\n\tconst bodyBytes = Buffer.byteLength(body, \"utf8\");\n\tconst headers: Record<string, string> = {\n\t\tAuthorization: `Bearer ${credential.apiKey}`,\n\t\t\"Content-Type\": \"application/x-ndjson\",\n\t\tAccept: \"application/json\",\n\t\t\"X-Trace-Id\": traceContext.traceId,\n\t\t\"X-Cwd\": header.cwd,\n\t\t\"X-Agent-Version\": VERSION,\n\t};\n\tif (traceContext.parentSessionId) {\n\t\theaders[\"X-Parent-Session\"] = traceContext.parentSessionId;\n\t}\n\tconst git = activeGitContext(body, header);\n\tif (git?.repoUrl) {\n\t\theaders[\"X-Git-Repo\"] = git.repoUrl;\n\t}\n\tif (git?.commit) {\n\t\theaders[\"X-Git-Commit\"] = git.commit;\n\t}\n\n\tif (requireEnabled && !(await getAgentTracesEnabled(options))) {\n\t\treturn { status: \"disabled\" };\n\t}\n\n\tconst url = `${baseUrl}/api/v1/agent-traces/sessions/${encodeURIComponent(header.id)}`;\n\tconst fetchFn = options.fetchFn ?? fetch;\n\n\tlet response: Response;\n\ttry {\n\t\tresponse = await fetchWithRetry(\n\t\t\tfetchFn,\n\t\t\turl,\n\t\t\t{\n\t\t\t\tmethod: \"PUT\",\n\t\t\t\tredirect: \"error\",\n\t\t\t\theaders,\n\t\t\t\tbody,\n\t\t\t},\n\t\t\toptions.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,\n\t\t\toptions.signal,\n\t\t\tbeforeRequest,\n\t\t);\n\t} catch (error) {\n\t\treturn { status: \"failed\", message: describeError(error) };\n\t}\n\n\tif (!response.ok) {\n\t\treturn {\n\t\t\tstatus: \"failed\",\n\t\t\tstatusCode: response.status,\n\t\t\tmessage: await readResponseMessage(response),\n\t\t\tretryAfterMs: retryAfterDelay(response, MAX_TIMER_DELAY_MS),\n\t\t};\n\t}\n\n\tconst responseText = await response.text().catch(() => \"\");\n\tconst responseData = parseResponseObject(responseText);\n\ttry {\n\t\tawait recordAgentTraceOutboxUpload(options.sessionFile, signature);\n\t} catch (error) {\n\t\treturn { status: \"failed\", message: `stored, but recording the upload cursor failed: ${describeError(error)}` };\n\t}\n\treturn {\n\t\tstatus: \"uploaded\",\n\t\tsessionId: responseData ? (stringField(responseData, \"session_id\") ?? header.id) : header.id,\n\t\ttraceId: responseData ? (stringField(responseData, \"trace_id\") ?? traceContext.traceId) : traceContext.traceId,\n\t\tbytesStored: responseData ? (numberField(responseData, \"bytes_stored\") ?? bodyBytes) : bodyBytes,\n\t\tkey: responseData ? stringField(responseData, \"key\") : undefined,\n\t};\n}\n\nexport function uploadAgentTraceSession(options: AgentTraceSessionUploadOptions): Promise<AgentTraceUploadResult> {\n\treturn uploadAgentTraceFile({\n\t\t...options,\n\t\tsessionFile: options.sessionManager.getSessionFile(),\n\t});\n}\n\nclass AgentTraceUploadController {\n\tprivate timeout: NodeJS.Timeout | undefined;\n\tprivate pending = false;\n\tprivate inFlight: Promise<void> | undefined;\n\tprivate lastUploadStartedAt: number | undefined;\n\tprivate notBeforeAt = 0;\n\n\tconstructor(\n\t\tprivate readonly sessionManager: SessionManager,\n\t\tprivate options: AgentTraceUploadInstallOptions,\n\t) {}\n\n\tupdate(options: AgentTraceUploadInstallOptions): void {\n\t\tthis.options = options;\n\t}\n\n\tschedule = (): void => {\n\t\tif (\n\t\t\t!this.options.settingsManager.getAgentTracesEnabled() ||\n\t\t\t!resolvePrimeAgentTracesBaseUrl(this.options.baseUrl)\n\t\t) {\n\t\t\treturn;\n\t\t}\n\t\tthis.pending = true;\n\t\t// Intent is consent-gated at persist time: an entry created while sharing\n\t\t// is off would turn a later enable into retroactive collection of\n\t\t// opted-out sessions. Marking re-runs every persist (existsSync-cheap),\n\t\t// so an entry pruned by a racing catch-up is re-registered.\n\t\tif (this.options.settingsManager.getAgentTracesEnabled()) {\n\t\t\tconst sessionFile = this.sessionManager.getSessionFile();\n\t\t\tif (\n\t\t\t\tsessionFile &&\n\t\t\t\t!locallyManagedSessionFiles.has(sessionFile) &&\n\t\t\t\tmarkAgentTraceOutboxPendingSync(sessionFile)\n\t\t\t) {\n\t\t\t\tlocallyManagedSessionFiles.add(sessionFile);\n\t\t\t}\n\t\t\tconst ledgerPath = this.options.semanticEdgesLedgerPath;\n\t\t\tif (ledgerPath) {\n\t\t\t\tmarkAgentTraceOutboxPendingSync(ledgerPath, SEMANTIC_EDGES_OUTBOX_KIND);\n\t\t\t}\n\t\t}\n\t\tthis.arm();\n\t};\n\n\tprivate arm(): void {\n\t\tif (this.timeout) {\n\t\t\tclearTimeout(this.timeout);\n\t\t}\n\t\tconst elapsed = this.lastUploadStartedAt === undefined ? undefined : Date.now() - this.lastUploadStartedAt;\n\t\tconst throttleDelay = elapsed === undefined ? 0 : Math.max(0, TRACE_UPLOAD_MIN_INTERVAL_MS - elapsed);\n\t\tconst notBeforeDelay = Math.max(0, this.notBeforeAt - Date.now());\n\t\tthis.timeout = setTimeout(\n\t\t\t() => {\n\t\t\t\tthis.timeout = undefined;\n\t\t\t\tvoid this.runScheduledUpload();\n\t\t\t},\n\t\t\tMath.max(TRACE_UPLOAD_DEBOUNCE_MS, throttleDelay, notBeforeDelay),\n\t\t);\n\t\tthis.timeout.unref();\n\t}\n\n\tprivate async runScheduledUpload(): Promise<void> {\n\t\tif (this.inFlight) {\n\t\t\treturn;\n\t\t}\n\t\tthis.pending = false;\n\t\tthis.lastUploadStartedAt = Date.now();\n\t\tthis.inFlight = uploadAgentTraceSession({\n\t\t\t...this.options,\n\t\t\tsessionManager: this.sessionManager,\n\t\t}).then(\n\t\t\t(result) => {\n\t\t\t\tif (result.status === \"failed\" && isRescheduledUploadFailure(result.statusCode)) {\n\t\t\t\t\tthis.pending = true;\n\t\t\t\t\tif (result.retryAfterMs !== undefined) {\n\t\t\t\t\t\tthis.notBeforeAt = Date.now() + result.retryAfterMs;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t},\n\t\t\t() => undefined,\n\t\t);\n\t\tawait this.inFlight;\n\t\tthis.inFlight = undefined;\n\t\tif (this.pending) {\n\t\t\tthis.arm();\n\t\t}\n\t}\n}\n\nfunction isRescheduledUploadFailure(statusCode: number | undefined): boolean {\n\treturn statusCode === undefined || statusCode === 429 || RETRIABLE_HTTP_STATUSES.has(statusCode);\n}\n\nconst traceUploadControllers = new WeakMap<SessionManager, AgentTraceUploadController>();\nexport function installAgentTraceUpload(sessionManager: SessionManager, options: AgentTraceUploadInstallOptions): void {\n\t// Enabling export applies to live sessions, not an inherited outbox backlog.\n\tlet controller = traceUploadControllers.get(sessionManager);\n\tif (controller) {\n\t\tcontroller.update(options);\n\t\treturn;\n\t}\n\n\tcontroller = new AgentTraceUploadController(sessionManager, options);\n\ttraceUploadControllers.set(sessionManager, controller);\n\tsessionManager.onPersist(controller.schedule);\n}\n"]}