@tangle-network/traces 0.18.0 → 0.19.1

package/README.md

@@ -566,6 +566,23 @@ Do not pass `--llm`; the command is model-backed by definition.
 
 ## Session facts
 
+The SDK also accepts verified retained captures through
+`parseRetainedSession({ harness, nativeSessionId, files, signal? })`.
+Pass files as `{ path, content }` with their original relative layout.
+Runtime or the caller owns custody, digest verification and capture completeness.
+The reader uses existing adapters and selects a file only when native records
+establish the supplied session identity.
+It does not inspect the host session catalog or infer identity from filenames.
+Directory-only stores and formats without a recorded native identity remain unavailable.
+The returned source files, duplicate snapshots and unselected files explain the selection.
+Identical or append-only copies count once; divergent histories remain unavailable.
+Parsing is bounded to 1024 text files, 16 MiB per file, and 64 MiB total.
+No model calls occur.
+Call `buildSessionFactsReport(selection.spans, { includeContent: false })` to
+withhold native bodies from the resulting facts.
+The reader itself returns spans containing native content, for local trusted consumers only.
+
+
 The same facts sheet includes observed tool outcomes, captured input/output byte
 volumes, call-to-result intervals, compaction boundaries and available context
 sizes, spawn intervals, and existing skill invocation/document-read evidence.

package/dist/{chunk-TCTZ7DUY.js → chunk-YVCHWHCA.js}

@@ -1488,6 +1488,7 @@ var AmpAdapter = class {
     const spans = [
       span({ traceId, spanId: rootId, parentSpanId: null, name: "session", kind: "AGENT", startTime: start, service: SERVICE, agent: SERVICE })
     ];
+    if (thread.id) spans[0].attributes["tangle.sessionId"] = thread.id;
     const toolByUseId = /* @__PURE__ */ new Map();
     let step = 0;
     for (const m of messages) {
@@ -2212,6 +2213,7 @@ function normalizeClaudeIds(spans) {
     const sourceTraceId = item.trace_id;
     const sourceSpanId = item.span_id;
     const sourceParentSpanId = item.parent_span_id;
+    item.attributes["tangle.sessionId"] = sourceTraceId;
     item.attributes[CLAUDE_SOURCE_TRACE_ID] = sourceTraceId;
     item.attributes[CLAUDE_SOURCE_SPAN_ID] = sourceSpanId;
     if (sourceParentSpanId !== null) {
@@ -5130,6 +5132,7 @@ var CodexExecAdapter = class {
           service: SERVICE4,
           agent: SERVICE4,
           extra: {
+            "tangle.sessionId": threadId,
             "traces.codex.stream_format": "exec-jsonl",
             "traces.session.role": "operator"
           }
@@ -5594,6 +5597,7 @@ var FactoryAdapter = class {
         "session.output_tokens": settings.tokenUsage.outputTokens ?? 0
       } : void 0
     });
+    if (sessionLine?.id) root.attributes["tangle.sessionId"] = sessionLine.id;
     return [root, ...spans];
   }
 };
@@ -5653,6 +5657,7 @@ var ForgeAdapter = class {
     const spans = [
       span({ traceId, spanId: rootId, parentSpanId: null, name: "session", kind: "AGENT", startTime: (/* @__PURE__ */ new Date(0)).toISOString(), service: SERVICE7, agent: SERVICE7 })
     ];
+    if (ctx.conversation_id) spans[0].attributes["tangle.sessionId"] = ctx.conversation_id;
     const toolByCallId = /* @__PURE__ */ new Map();
     let step = 0;
     let lastLlm = rootId;
@@ -5833,6 +5838,7 @@ var GeminiFamilyAdapter = class {
         agent: this.service
       })
     ];
+    if (session.sessionId) spans[0].attributes["tangle.sessionId"] = session.sessionId;
     let step = 0;
     for (const m of messages) {
       const mid = m.id ?? `m${step}`;
@@ -6418,6 +6424,7 @@ var PiAdapter = class {
       agent: SERVICE9,
       extra: { "traces.pi.stop_reason": terminal.stopReason }
     });
+    if (sessionLine?.id) root.attributes["tangle.sessionId"] = sessionLine.id;
     return [root, ...spans];
   }
 };

package/dist/cli.js

@@ -83,7 +83,7 @@ import {
   writeSessionIndexFile,
   writeTraceEvidenceExportFile,
   writeTraceQuestionsArtifacts
-} from "./chunk-TCTZ7DUY.js";
+} from "./chunk-YVCHWHCA.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";

package/dist/index.d.ts

@@ -4940,4 +4940,37 @@ interface ExecuteOptions {
 /** Send the final, new outbound items (or write their dry-run OTLP). */
 declare function executeUpload(plan: UploadPlan, opts?: ExecuteOptions): Promise<UploadResult>;
 
-export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalysisEngineFromEnvOptions, type AnalyzeOptions, type AnalyzeResult, type AnswerSchema, type AssembleSessionBundleOptions, BLOBS_DIR, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CHANGED_FILE_LIST_CAP, CITATION_NORMALIZATION_VERSION, CONTENT_CAP, COORDINATION_LOG_FILE, CORRECTIVE_REACTIONS, type ChangedFileFact, type ChatTrajectory, type ChatTrajectoryMessage, type ChatTrajectoryOptions, ClaudeAdapter, type CodeTraceBenchFileRef, type CodeTraceBenchImportOptions, type CodeTraceBenchImportReceipt, type CodeTraceBenchImportResult, type CodeTraceBenchImportedTrace, type CodeTraceBenchStep, CodexAdapter, CodexExecAdapter, CodexExecStreamError, CodexTaskScopeError, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, type CollectSessionSelectionOptions, type CollectSessionWorkflowOptions, type CompactionMeasurement, type ConformanceRenderOptions, type ContentFootprint, type CoordinationLog, type CoordinationQuestion, type CoordinationSteer, CopilotAdapter, type CorruptionMode, type CoveredMeasurement, DEFAULT_ANALYST_MODEL, DEFAULT_ASK_CONCURRENCY, DEFAULT_HARNESS, DEFAULT_SANDBOX_BASE_URL, EMPTY_SPAN_RUN_SNAPSHOT, EXPORT_RULE, EmptySessionError, type EvidenceOnlyVerdict, type ExcludedTurnFact, type ExecuteOptions, type ExportRule, type ExternalAnalysisKind, type ExternalAnalysisPayload, type ExternalAnalysisResult, type ExternalAnalyzer, type ExternalAnalyzerOptions, type ExternalDiscoveryCandidate, FACT_LIST_CAP, FACT_TEXT_CAP, FactoryAdapter, type FailureFollowUp, type FailureFollowUpReport, type FileRunContextReaderOptions, type FinalMessageFact, type FindSessionTextLeaksOptions, type FindingRejectionCounts, type FindingRejectionReasons, type FindingRejectionTally, type FindingsFileOutcome, type FollowUpKind, ForgeAdapter, GeminiAdapter, type HaloAnalyzerOptions, type HaloReasoningEffort, type HarnessTraceAdapter, type HodoscopeAnalyzerOptions, type HodoscopeInput, type HodoscopeMessage, type HodoscopeSourceMapEntry, type HodoscopeTrajectory, INGEST_SOURCE_CLI, INHERITED_SOURCE_ATTR, INHERITED_SPANS_OMITTED_ATTR, INHERITED_SPAN_ATTR, INHERITED_SPAN_COUNT_ATTR, type InheritedSpanSource, type InspectSessionIndexOptions, JsonSourceError, type JsonlCorruptionReceipt, JsonlParseError, type JsonlReadOptions, type LiveBatchOptions, type LocateOptions, type LoopConvergence, type LoopConvergenceReport, type LoopIteration, type LoopTrend, type LoopTrendBasis, MAX_SHELL_DEPTH, MAX_TRACE_QUESTION_CHARS, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpIngestIssue, type OtlpIngestIssueKind, type OtlpInput, type OtlpInputFile, type OtlpRowConversion, type OtlpSpan, type OtlpSpanKind, type OtlpSpanLink, type OtlpStatusCode, POLICY_EVIDENCE_NOTE, PREPARED_CONTEXT_BYTE_CEILING, type ParentTaskResolution, type ParseOptions, PartialUploadError, PiAdapter, type PiAdapterOptions, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, type PrimeAnalyzerOptions, type PrimeTransport, type PrimeTransportRequest, type PrimeTransportResponse, type ProjectSessionBundleOptions, type ProjectSessionBundleResult, type PullRequestFact, type PullRequestFacts, type PullRequestReading, QwenAdapter, REACTIONS, RESULT_FILE, RULE, type Reaction, type ReactionReport, type ReactionSessionReport, type RedactSpansOptions, type Redactor, type RefusedSession, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type ResolvedOtlpInput, type RunContextJournal, type RunContextNode, type RunContextResult, type RunContextSnapshot, type RunDiffOptions, type RunDiffReport, type RunDiffSide, type RunResult, type RunWatchSnapshot, type RunWatchTarget, type RuntimeTrace, SESSION_FACTS_MEASUREMENT_VERSION, SESSION_FACTS_VERSION_SUFFIX, SESSION_TOKEN_TOTAL_ATTR, SOURCE_ATTRIBUTE_PREFIX, SPAN_SYNTHESIZED_ATTR, SPAWN_JOURNAL_FILE, STATUS_MARK, SYNTHESIZED_SOURCE_ATTR, SYNTHESIZED_SPAN_ATTR, type SandboxReplayBackendOptions, type ScanOptions, type ScannedSession, type SessionBatch, type SessionBundleAbsence, type SessionBundleCarriedSignatures, type SessionBundleExclusion, type SessionBundleExclusionRule, type SessionBundleFile, type SessionBundleIssue, type SessionBundleIssueKind, type SessionBundleLeakCheck, type SessionBundleLedgerSlice, type SessionBundleManifest, type SessionBundleProjection, type SessionBundleResult, type SessionBundleSliceRule, type SessionBundleVerification, type SessionBundleView, type SessionCorruptionReceipt, type SessionEnvironment, type SessionFact, type SessionFacts, type SessionFactsOptions, type SessionFactsReport, type SessionIdentityConflict, type SessionIdentityIndex, type SessionIntegrity, type SessionMeasurements, type SessionRef, type SessionRelationship, type SessionRole, type SessionSeedGroup, type SessionSelection, type SessionSelectionRow, type SessionSourceFile, type SessionTextLeak, type SessionTextLeakReport, type SessionTurnFact, type SessionWorkflow, SessionWorkflowError, type SessionWorkflowErrorCode, type SessionWorkflowIssue, type SessionWorkflowSession, type SessionWorkflowSummary, type SkippedAnalysis, type SkippedInputFile, type SourceRecordReference, type SpanInput, type SpanNodeStatus, type SpanRedaction, type SpanRunNode, type SpanRunSnapshot, type SpanStructure, type SpawnedChildResolution, type SpendRoll, type SteeringChainReport, type SteeringEdge, type SubagentSpawnFact, TRACE_QUESTION_PREVIEW_HEAD_CHARS, type ToolMeasurement, type TraceAgenticRoute, type TraceAgenticRouteReason, type TraceAgenticRouteReasonCode, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, type TraceExecutionOptions, type TraceFindingPacket, type TraceImprovementArtifacts, type TraceImprovementOptions, type TraceImprovementResult, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceInvestigationOptions, type TraceInvestigationResult, type TraceLiveAction, type TraceLiveActionKind, type TraceLiveAnalysisContext, type TraceLiveAnalyst, type TraceLiveBatch, type TraceLiveEvidence, type TraceLiveFinding, type TraceLiveLoop, type TraceLiveSeverity, type TraceQuestion, type TraceQuestionAnswer, type TraceQuestionCitation, type TraceQuestionFailureKind, type TraceQuestionTrace, type TraceQuestionsArtifacts, type TraceQuestionsOptions, type TraceQuestionsResult, type TraceQuestionsTotals, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TraceStreamEvent, type TraceStreamOptions, type TraceStreamReplayOptions, type TraceStreamSession, type TracesConfig, type TriggerPair, type TurnActorCount, type UnavailableCapabilities, type UploadBackend, type UploadIdentity, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, type VerifySafeOptions, type VerifySafeResult, type WatchRunTargetOptions, ZERO_ROLL, type ZaiChatCallerOptions, addSpend, alreadyUploaded, analysisEngineFromEnv, analyzeAdoption, analyzeLiveBatch, analyzeLoopConvergence, analyzeReactions, analyzeSpans, analyzeSteeringChain, answerSchemaErrors, applyRedactor, assembleSessionBundle, assertAnswerSchema, assertSandboxReachable, assessSpans, buildPolicyEvidenceRecord, buildSessionFactsReport, buildSessionIndex, buildSessionIndexFromRows, buildSpanRunTree, buildTraceFindingPacket, capText, chatTrajectoryToSpans, classifyEvidenceOnlyPath, classifyFailureFollowUps, classifyLiveActions, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessionSelection, collectSessionWorkflow, collectSessions, commandAnalyzer, commandRedactor, commandTextFromInput, computeAdoption, computeSessionFacts, conformanceOfSpans, connectors, countSkillRunsJsonl, createBundleSourceReader, createFindingRejectionTally, cwdMatchesSelection, cwdMatchesSelectionResolved, defaultTraceLiveAnalysts, describeSessionRelationship, diffRuns, engineCallReservationFloorUsd, environmentAttributes, environmentFromSpanAttributes, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, externalFailureMessage, fileRunContextSupervisorRunReader, fileSha256, findContextRoot, findSessionTextLeaks, findSpanSourceFiles, findingRejection, findingRejectionDetail, forEachTreeNode, formatFindingRejections, formatVerdict, haloAnalyzer, hashSessionBundleFiles, hodoscopeAnalyzer, httpJsonTransport, importCodeTraceBench, incompleteInputsNote, indexSessionIdsByTrace, inferRole, inferSpanKind, inspectSessionIndex, int, isBridgeMismatchError, isChatTrajectory, isChatTrajectoryMessage, isFileRunContextDir, isInheritedSpan, isSynthesizedSpan, iterSerializedSpans, knownHarnesses, listAdapters, listSessionBundleFiles, loadState, loadTraceQuestionsFile, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeRolls, mergeTracesConfig, ms, normalizeAnalystCitations, normalizeRemote, normalizeTraceQuestions, otlpRowToSpan, outboundHash, parseIsoToEpochMs, parseJsonAnswer, parseSession, parseSince, planTraceAgenticRoute, planUpload, primeAnalyzer, projectSessionBundle, readCoordinationLog, readFileRunContext, readJsonFile, readJsonl, readOtlpInput, readPullRequests, readRunContextJournal, readRunContextSnapshot, readRunSide, readRunWatchSnapshot, readSessionBundleManifest, readSessionIndexFile, readSpanRunSnapshot, recordSessionCorruption, redactSpans, renderConformance, renderInspectionReport, renderRunContextSnapshot, renderRunDiff, renderRunWatchSnapshot, renderSessionFacts, renderSessionFactsContext, renderSpanRunSnapshot, renderTraceQuestionInstructions, renderTraceQuestionPrompt, renderTraceQuestionsReport, renderValidation, resolveAdapter, resolveOtlpInputFiles, resolveRepoAttrs, resolveRunContextDir, resolveRunWatchTarget, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTotals, runTraceImprovement, runTraceInvestigation, runTraceQuestions, runTraceStoreInvestigation, sandboxReplayBackend, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionFactsContext, sessionHash, sessionIdFromAttributes, sessionIntegrityAttributes, sessionTextSignatures, shellCommands, skippedAnalyses, span, spanRunTotals, stampEnvironmentAttrs, stampRepoAttrs, stampSessionIdentity, stampSessionIntegrity, stampSpanWorkdirRepoAttrs, streamSessions, summarizeOtlpExecution, summarizeSpanExecution, summarizeSpanStructure, takeJsonl, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, tokens, totalAgenticFailureMessage, totalFindingRejections, traceAgenticKinds, traceCitationsInText, traceStreamEventsFromSpans, unavailableCapabilities, uploadKey, usd, userPromptSpan, validateOtlpSpans, validationExitCode, verdictExitCode, verifyFindingsInSandbox, verifySafe, verifySessionBundle, watchRunTarget, watchSessions, withSessionFactsContext, wrap, writeHodoscopeInput, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionBundleManifest, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts, writeTraceQuestionsArtifacts, zaiChatCaller, zeroPricedCost };
+declare const RETAINED_SESSION_READER_VERSION = "2";
+interface RetainedSessionFile {
+    readonly path: string;
+    readonly content: string;
+}
+interface RetainedSessionSelection {
+    readonly status: 'selected' | 'unavailable';
+    readonly reason: string | null;
+    readonly sessionId: string | null;
+    readonly sourceFiles: readonly {
+        readonly path: string;
+        readonly sha256: string;
+    }[];
+    readonly duplicateFiles: readonly string[];
+    readonly unselectedFiles: readonly {
+        readonly path: string;
+        readonly reason: string;
+    }[];
+    readonly spans: readonly OtlpSpan[];
+}
+/**
+ * Parse an explicitly retained capture without consulting the host's session catalog.
+ * Native identity must come from the adapter's records. A path, caller supplied
+ * fallback ID, or worker name never establishes identity. Runtime owns custody,
+ * hash verification, capture completeness, and the binding to its node.
+ */
+declare function parseRetainedSession(input: {
+    readonly harness: string;
+    readonly nativeSessionId: string | null;
+    readonly files: readonly RetainedSessionFile[];
+    readonly signal?: AbortSignal;
+}): Promise<RetainedSessionSelection>;
+
+export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalysisEngineFromEnvOptions, type AnalyzeOptions, type AnalyzeResult, type AnswerSchema, type AssembleSessionBundleOptions, BLOBS_DIR, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CHANGED_FILE_LIST_CAP, CITATION_NORMALIZATION_VERSION, CONTENT_CAP, COORDINATION_LOG_FILE, CORRECTIVE_REACTIONS, type ChangedFileFact, type ChatTrajectory, type ChatTrajectoryMessage, type ChatTrajectoryOptions, ClaudeAdapter, type CodeTraceBenchFileRef, type CodeTraceBenchImportOptions, type CodeTraceBenchImportReceipt, type CodeTraceBenchImportResult, type CodeTraceBenchImportedTrace, type CodeTraceBenchStep, CodexAdapter, CodexExecAdapter, CodexExecStreamError, CodexTaskScopeError, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, type CollectSessionSelectionOptions, type CollectSessionWorkflowOptions, type CompactionMeasurement, type ConformanceRenderOptions, type ContentFootprint, type CoordinationLog, type CoordinationQuestion, type CoordinationSteer, CopilotAdapter, type CorruptionMode, type CoveredMeasurement, DEFAULT_ANALYST_MODEL, DEFAULT_ASK_CONCURRENCY, DEFAULT_HARNESS, DEFAULT_SANDBOX_BASE_URL, EMPTY_SPAN_RUN_SNAPSHOT, EXPORT_RULE, EmptySessionError, type EvidenceOnlyVerdict, type ExcludedTurnFact, type ExecuteOptions, type ExportRule, type ExternalAnalysisKind, type ExternalAnalysisPayload, type ExternalAnalysisResult, type ExternalAnalyzer, type ExternalAnalyzerOptions, type ExternalDiscoveryCandidate, FACT_LIST_CAP, FACT_TEXT_CAP, FactoryAdapter, type FailureFollowUp, type FailureFollowUpReport, type FileRunContextReaderOptions, type FinalMessageFact, type FindSessionTextLeaksOptions, type FindingRejectionCounts, type FindingRejectionReasons, type FindingRejectionTally, type FindingsFileOutcome, type FollowUpKind, ForgeAdapter, GeminiAdapter, type HaloAnalyzerOptions, type HaloReasoningEffort, type HarnessTraceAdapter, type HodoscopeAnalyzerOptions, type HodoscopeInput, type HodoscopeMessage, type HodoscopeSourceMapEntry, type HodoscopeTrajectory, INGEST_SOURCE_CLI, INHERITED_SOURCE_ATTR, INHERITED_SPANS_OMITTED_ATTR, INHERITED_SPAN_ATTR, INHERITED_SPAN_COUNT_ATTR, type InheritedSpanSource, type InspectSessionIndexOptions, JsonSourceError, type JsonlCorruptionReceipt, JsonlParseError, type JsonlReadOptions, type LiveBatchOptions, type LocateOptions, type LoopConvergence, type LoopConvergenceReport, type LoopIteration, type LoopTrend, type LoopTrendBasis, MAX_SHELL_DEPTH, MAX_TRACE_QUESTION_CHARS, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpIngestIssue, type OtlpIngestIssueKind, type OtlpInput, type OtlpInputFile, type OtlpRowConversion, type OtlpSpan, type OtlpSpanKind, type OtlpSpanLink, type OtlpStatusCode, POLICY_EVIDENCE_NOTE, PREPARED_CONTEXT_BYTE_CEILING, type ParentTaskResolution, type ParseOptions, PartialUploadError, PiAdapter, type PiAdapterOptions, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, type PrimeAnalyzerOptions, type PrimeTransport, type PrimeTransportRequest, type PrimeTransportResponse, type ProjectSessionBundleOptions, type ProjectSessionBundleResult, type PullRequestFact, type PullRequestFacts, type PullRequestReading, QwenAdapter, REACTIONS, RESULT_FILE, RETAINED_SESSION_READER_VERSION, RULE, type Reaction, type ReactionReport, type ReactionSessionReport, type RedactSpansOptions, type Redactor, type RefusedSession, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type ResolvedOtlpInput, type RetainedSessionFile, type RetainedSessionSelection, type RunContextJournal, type RunContextNode, type RunContextResult, type RunContextSnapshot, type RunDiffOptions, type RunDiffReport, type RunDiffSide, type RunResult, type RunWatchSnapshot, type RunWatchTarget, type RuntimeTrace, SESSION_FACTS_MEASUREMENT_VERSION, SESSION_FACTS_VERSION_SUFFIX, SESSION_TOKEN_TOTAL_ATTR, SOURCE_ATTRIBUTE_PREFIX, SPAN_SYNTHESIZED_ATTR, SPAWN_JOURNAL_FILE, STATUS_MARK, SYNTHESIZED_SOURCE_ATTR, SYNTHESIZED_SPAN_ATTR, type SandboxReplayBackendOptions, type ScanOptions, type ScannedSession, type SessionBatch, type SessionBundleAbsence, type SessionBundleCarriedSignatures, type SessionBundleExclusion, type SessionBundleExclusionRule, type SessionBundleFile, type SessionBundleIssue, type SessionBundleIssueKind, type SessionBundleLeakCheck, type SessionBundleLedgerSlice, type SessionBundleManifest, type SessionBundleProjection, type SessionBundleResult, type SessionBundleSliceRule, type SessionBundleVerification, type SessionBundleView, type SessionCorruptionReceipt, type SessionEnvironment, type SessionFact, type SessionFacts, type SessionFactsOptions, type SessionFactsReport, type SessionIdentityConflict, type SessionIdentityIndex, type SessionIntegrity, type SessionMeasurements, type SessionRef, type SessionRelationship, type SessionRole, type SessionSeedGroup, type SessionSelection, type SessionSelectionRow, type SessionSourceFile, type SessionTextLeak, type SessionTextLeakReport, type SessionTurnFact, type SessionWorkflow, SessionWorkflowError, type SessionWorkflowErrorCode, type SessionWorkflowIssue, type SessionWorkflowSession, type SessionWorkflowSummary, type SkippedAnalysis, type SkippedInputFile, type SourceRecordReference, type SpanInput, type SpanNodeStatus, type SpanRedaction, type SpanRunNode, type SpanRunSnapshot, type SpanStructure, type SpawnedChildResolution, type SpendRoll, type SteeringChainReport, type SteeringEdge, type SubagentSpawnFact, TRACE_QUESTION_PREVIEW_HEAD_CHARS, type ToolMeasurement, type TraceAgenticRoute, type TraceAgenticRouteReason, type TraceAgenticRouteReasonCode, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, type TraceExecutionOptions, type TraceFindingPacket, type TraceImprovementArtifacts, type TraceImprovementOptions, type TraceImprovementResult, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceInvestigationOptions, type TraceInvestigationResult, type TraceLiveAction, type TraceLiveActionKind, type TraceLiveAnalysisContext, type TraceLiveAnalyst, type TraceLiveBatch, type TraceLiveEvidence, type TraceLiveFinding, type TraceLiveLoop, type TraceLiveSeverity, type TraceQuestion, type TraceQuestionAnswer, type TraceQuestionCitation, type TraceQuestionFailureKind, type TraceQuestionTrace, type TraceQuestionsArtifacts, type TraceQuestionsOptions, type TraceQuestionsResult, type TraceQuestionsTotals, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TraceStreamEvent, type TraceStreamOptions, type TraceStreamReplayOptions, type TraceStreamSession, type TracesConfig, type TriggerPair, type TurnActorCount, type UnavailableCapabilities, type UploadBackend, type UploadIdentity, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, type VerifySafeOptions, type VerifySafeResult, type WatchRunTargetOptions, ZERO_ROLL, type ZaiChatCallerOptions, addSpend, alreadyUploaded, analysisEngineFromEnv, analyzeAdoption, analyzeLiveBatch, analyzeLoopConvergence, analyzeReactions, analyzeSpans, analyzeSteeringChain, answerSchemaErrors, applyRedactor, assembleSessionBundle, assertAnswerSchema, assertSandboxReachable, assessSpans, buildPolicyEvidenceRecord, buildSessionFactsReport, buildSessionIndex, buildSessionIndexFromRows, buildSpanRunTree, buildTraceFindingPacket, capText, chatTrajectoryToSpans, classifyEvidenceOnlyPath, classifyFailureFollowUps, classifyLiveActions, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessionSelection, collectSessionWorkflow, collectSessions, commandAnalyzer, commandRedactor, commandTextFromInput, computeAdoption, computeSessionFacts, conformanceOfSpans, connectors, countSkillRunsJsonl, createBundleSourceReader, createFindingRejectionTally, cwdMatchesSelection, cwdMatchesSelectionResolved, defaultTraceLiveAnalysts, describeSessionRelationship, diffRuns, engineCallReservationFloorUsd, environmentAttributes, environmentFromSpanAttributes, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, externalFailureMessage, fileRunContextSupervisorRunReader, fileSha256, findContextRoot, findSessionTextLeaks, findSpanSourceFiles, findingRejection, findingRejectionDetail, forEachTreeNode, formatFindingRejections, formatVerdict, haloAnalyzer, hashSessionBundleFiles, hodoscopeAnalyzer, httpJsonTransport, importCodeTraceBench, incompleteInputsNote, indexSessionIdsByTrace, inferRole, inferSpanKind, inspectSessionIndex, int, isBridgeMismatchError, isChatTrajectory, isChatTrajectoryMessage, isFileRunContextDir, isInheritedSpan, isSynthesizedSpan, iterSerializedSpans, knownHarnesses, listAdapters, listSessionBundleFiles, loadState, loadTraceQuestionsFile, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeRolls, mergeTracesConfig, ms, normalizeAnalystCitations, normalizeRemote, normalizeTraceQuestions, otlpRowToSpan, outboundHash, parseIsoToEpochMs, parseJsonAnswer, parseRetainedSession, parseSession, parseSince, planTraceAgenticRoute, planUpload, primeAnalyzer, projectSessionBundle, readCoordinationLog, readFileRunContext, readJsonFile, readJsonl, readOtlpInput, readPullRequests, readRunContextJournal, readRunContextSnapshot, readRunSide, readRunWatchSnapshot, readSessionBundleManifest, readSessionIndexFile, readSpanRunSnapshot, recordSessionCorruption, redactSpans, renderConformance, renderInspectionReport, renderRunContextSnapshot, renderRunDiff, renderRunWatchSnapshot, renderSessionFacts, renderSessionFactsContext, renderSpanRunSnapshot, renderTraceQuestionInstructions, renderTraceQuestionPrompt, renderTraceQuestionsReport, renderValidation, resolveAdapter, resolveOtlpInputFiles, resolveRepoAttrs, resolveRunContextDir, resolveRunWatchTarget, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTotals, runTraceImprovement, runTraceInvestigation, runTraceQuestions, runTraceStoreInvestigation, sandboxReplayBackend, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionFactsContext, sessionHash, sessionIdFromAttributes, sessionIntegrityAttributes, sessionTextSignatures, shellCommands, skippedAnalyses, span, spanRunTotals, stampEnvironmentAttrs, stampRepoAttrs, stampSessionIdentity, stampSessionIntegrity, stampSpanWorkdirRepoAttrs, streamSessions, summarizeOtlpExecution, summarizeSpanExecution, summarizeSpanStructure, takeJsonl, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, tokens, totalAgenticFailureMessage, totalFindingRejections, traceAgenticKinds, traceCitationsInText, traceStreamEventsFromSpans, unavailableCapabilities, uploadKey, usd, userPromptSpan, validateOtlpSpans, validationExitCode, verdictExitCode, verifyFindingsInSandbox, verifySafe, verifySessionBundle, watchRunTarget, watchSessions, withSessionFactsContext, wrap, writeHodoscopeInput, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionBundleManifest, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts, writeTraceQuestionsArtifacts, zaiChatCaller, zeroPricedCost };

package/dist/index.js

@@ -270,7 +270,7 @@ import {
   writeTraceQuestionsArtifacts,
   zaiChatCaller,
   zeroPricedCost
-} from "./chunk-TCTZ7DUY.js";
+} from "./chunk-YVCHWHCA.js";
 
 // src/collect.ts
 async function collectSessions(opts = {}) {
@@ -301,6 +301,116 @@ import {
   redactText,
   shareAllowed
 } from "@tangle-network/agent-eval/traces";
+
+// src/retained-session.ts
+import { createHash } from "crypto";
+import { mkdir, mkdtemp, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { dirname, isAbsolute, join, relative, resolve } from "path";
+var RETAINED_SESSION_READER_VERSION = "2";
+async function parseRetainedSession(input) {
+  input.signal?.throwIfAborted();
+  const unselectedFiles = [];
+  const unavailable = (reason) => ({
+    status: "unavailable",
+    reason,
+    sessionId: input.nativeSessionId,
+    sourceFiles: [],
+    duplicateFiles: [],
+    unselectedFiles,
+    spans: []
+  });
+  if (!input.nativeSessionId) return unavailable("Capture has no recorded native session identity.");
+  const adapter = resolveAdapter(input.harness);
+  if (!adapter) return unavailable(`No native trace adapter for ${input.harness}.`);
+  if (input.files.length > 1024) return unavailable("Retained capture exceeds 1024 text files.");
+  let totalBytes = 0;
+  for (const file of input.files) {
+    const bytes = Buffer.byteLength(file.content);
+    totalBytes += bytes;
+    if (bytes > 16 * 1024 ** 2 || totalBytes > 64 * 1024 ** 2) {
+      return unavailable("Retained capture exceeds the 16 MiB per-file or 64 MiB total text limit.");
+    }
+  }
+  const root = await mkdtemp(join(tmpdir(), "traces-retained-"));
+  try {
+    const files = /* @__PURE__ */ new Map();
+    for (const file of input.files) {
+      input.signal?.throwIfAborted();
+      const path = resolve(root, file.path);
+      const rel = relative(root, path);
+      if (!file.path || isAbsolute(file.path) || file.path.includes("\\") || file.path.includes("\0") || rel === "" || rel === ".." || rel.startsWith("../") || files.has(path)) {
+        throw new Error("Retained source paths must be unique relative files inside the capture.");
+      }
+      files.set(path, file);
+    }
+    for (const [path, file] of files) {
+      await mkdir(dirname(path), { recursive: true, mode: 448 });
+      await writeFile(path, file.content, { mode: 384, flag: "wx" });
+    }
+    const selected = [];
+    for (const [path, file] of files) {
+      input.signal?.throwIfAborted();
+      const fallback = `unattributed:${root}:${file.path}`;
+      const ref = { harness: adapter.harness, sessionId: fallback, path, cwd: null, mtimeMs: 0 };
+      try {
+        const sources = adapter.sourcePaths ? await adapter.sourcePaths(ref, { signal: input.signal }) : [path];
+        if (sources.some((source) => !files.has(resolve(source)))) {
+          throw new Error("Parser requires files outside the supplied retained capture.");
+        }
+        const spans = validateOtlpSpans(await adapter.parse(ref, {
+          corruptionMode: "recover",
+          taskScope: "all",
+          captureSources: false,
+          signal: input.signal
+        }), `${adapter.harness} retained adapter output`);
+        const roots = spans.filter((span2) => span2.parent_span_id === null);
+        const identities = new Set(roots.map((span2) => sessionIdFromAttributes(span2.attributes)));
+        if (identities.size !== 1 || !identities.has(input.nativeSessionId)) {
+          unselectedFiles.push({ path: file.path, reason: "No unambiguous matching native identity in parser output." });
+          continue;
+        }
+        if (computeSessionFacts(spans, { includeContent: false }).every((facts) => facts.recordSpans === 0)) {
+          unselectedFiles.push({ path: file.path, reason: "Native identity was recorded without any session records." });
+          continue;
+        }
+        stampSessionIntegrity(ref, spans);
+        stampSessionIdentity(spans, input.nativeSessionId);
+        for (const span2 of spans) {
+          for (const [key, value] of Object.entries(span2.attributes)) {
+            if (typeof value === "string" && value.includes(root)) {
+              span2.attributes[key] = value.split(root + "/").join("retained://");
+            }
+          }
+        }
+        selected.push({ file, paths: sources, spans });
+      } catch (error) {
+        input.signal?.throwIfAborted();
+        unselectedFiles.push({ path: file.path, reason: `Native parser could not read this file (${error instanceof Error ? error.name : "Error"}).` });
+      }
+    }
+    if (!selected.length) return unavailable("No retained parser entrypoint established the recorded native session identity.");
+    selected.sort((a, b) => b.file.content.length - a.file.content.length || a.file.path.localeCompare(b.file.path));
+    const chosen = selected[0];
+    if (selected.some((candidate) => !chosen.file.content.startsWith(candidate.file.content))) {
+      return unavailable("Retained files contain divergent histories for the same native session.");
+    }
+    return {
+      status: "selected",
+      reason: null,
+      sessionId: input.nativeSessionId,
+      sourceFiles: chosen.paths.map((path) => {
+        const file = files.get(resolve(path));
+        return { path: file.path, sha256: `sha256:${createHash("sha256").update(file.content).digest("hex")}` };
+      }).sort((a, b) => a.path.localeCompare(b.path)),
+      duplicateFiles: selected.slice(1).map((candidate) => candidate.file.path),
+      unselectedFiles,
+      spans: chosen.spans
+    };
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
 export {
   ACTOR_ATTR,
   ATTR,
@@ -347,6 +457,7 @@ export {
   QwenAdapter,
   REACTIONS,
   RESULT_FILE,
+  RETAINED_SESSION_READER_VERSION,
   RULE,
   SESSION_FACTS_MEASUREMENT_VERSION,
   SESSION_FACTS_VERSION_SUFFIX,
@@ -469,6 +580,7 @@ export {
   outboundHash,
   parseIsoToEpochMs,
   parseJsonAnswer,
+  parseRetainedSession,
   parseSession,
   parseSince,
   planTraceAgenticRoute,

package/docs/trace-analysts.md

@@ -425,10 +425,10 @@ What real runs have shown (GLM-5.3 via a coding-plan endpoint, fork at the pinne
   tokens); its first reply gets cut by the endpoint's output limit mid-JSON, and the
   truncation-aware repair turn (re-emit at most 3 findings, terse strings) recovers it — ok:true,
   findings grounded, exit 0.
-- **File, ~794 spans / 2.1 MB artifact:** ~2.2M input tokens of genuine REPL inspection, but the
-  reply never survives the endpoint's output cap even after repair — the run fails honestly
-  (exit 1, raw reply preserved, no findings invented). At that trajectory size, a model with a
-  larger output budget — or a paged finalization — is the next step, not silence about it.
+- **File, ~794 spans / 2.1 MB artifact:** the reply channel alone never survived the endpoint's
+  output cap. The findings.json payload channel finishes it — the analyzer writes the result with
+  its tools before replying — measured live at **8 findings, 0 rejected, exit 0**, 53 model calls,
+  ~3.1M input tokens of REPL inspection.
 
 ## Write one analyst
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.18.0",
-  "description": "Point it at your coding-agent session traces (Claude Code, Codex, OpenCode, Gemini, Pi, …) and get failure-mode + efficiency findings. CLI + SDK over the @tangle-network/agent-eval analyst suite — observe live sessions, run your own analysts, redact, and upload to the Tangle Intelligence Platform.",
+  "version": "0.19.1",
+  "description": "Point it at your coding-agent session traces (Claude Code, Codex, OpenCode, Gemini, Pi, \u2026) and get failure-mode + efficiency findings. CLI + SDK over the @tangle-network/agent-eval analyst suite \u2014 observe live sessions, run your own analysts, redact, and upload to the Tangle Intelligence Platform.",
   "type": "module",
   "license": "MIT",
   "repository": {