@tangle-network/harness-sessions 0.1.7 → 0.2.1

package/README.md

@@ -15,7 +15,7 @@ npm install @tangle-network/harness-sessions
 - The sidecar's harness session contract (agent-container `packages/cli-agent-registry`) imports `STORES` and `SessionFormatId` from here; it keeps no second copy of where a harness writes.
 - The capture path reads captures through `listCapture` / `readCapture`.
 - Discovery's trace gate, agent-eval, agent-record and the blog read sessions only through this package.
-- Its only dependencies are `@tangle-network/agent-trace-contract` and Node built-ins (`node:sqlite` for OpenCode).
+- Its dependencies are `@tangle-network/agent-core`, `@tangle-network/agent-trace-contract` and Node built-ins (`node:sqlite` for OpenCode).
 
 ## Formats
 
@@ -25,6 +25,8 @@ npm install @tangle-network/harness-sessions
 | `codex` | `codex.rollout-jsonl` | `rollout-*-{id}.jsonl` under `sessions/` and `archived_sessions/` of every Codex home (below) | turn context (the configured model) | per response (`last_token_usage`); session total from `total_token_usage` |
 | `opencode` | `opencode.sqlite` | `.local/share/opencode/opencode.db` (shared by every session) | session record (`providerID/modelID`) | per step (`step-finish`) |
 | `pi` | `pi.session-jsonl` | `.pi/agent/sessions/**/*_{id}.jsonl` | session record (`provider/model`) | per assistant message |
+| `kimi-code` | `kimi.session-dir` | `.kimi/sessions/*/{id}/wire.jsonl`, child wires at `*/{id}/subagents/*/wire.jsonl` | none in the wire | per step, excluding wrapped child events |
+| `factory-droids` | `factory.session-jsonl` | `.factory/sessions/*/{id}.jsonl` plus settings | configured model in settings (`turn-context`) | session total in settings |
 
 A HOME can hold several Codex homes, and `codexReader.locate` reads all of them (`codexHomes(home)` lists them):
 
@@ -35,7 +37,15 @@ A HOME can hold several Codex homes, and `codexReader.locate` reads all of them
 
 Homes that resolve to one directory count once. A session copied into several homes (`acct move`) is one ref, its largest copy. A lookup by id takes the rollout whose name ends in the id; when no name does, it reads the `session_meta` of each rollout modified since the id's UUIDv7 time.
 
-Readers for Kimi, Factory, Gemini, Amp, Qwen, Copilot, Forge, Hermes, Prime and OpenClaw are added with the same real-data proof.
+`listReaders()` and the exported catalog own the complete installed format inventory.
+
+## Child execution evidence
+
+Kimi records a child `agent_id` and `parent_tool_call_id` on each wrapped `SubagentEvent`, and writes the child's own wire under the parent's `subagents/<agent_id>/` directory. `kimiReader.locate(home, { nativeSessionId: parentId })` returns the parent and these child refs. A child-ID lookup selects that child. The reader keeps wrapped child events out of the parent's messages and usage; read each returned child ref for its own recorded work. `kimiRefForFile` preserves the same parent binding when a child wire is read directly. A missing child wire remains missing execution evidence, even when its ID appears in the parent.
+
+Pi's session-header `parentSession` is fork/clone/handoff lineage; it does not prove a delegated subagent. The native reader does not turn it or conversation-entry `parentId` into subagent execution. Extension workflow execution remains a separate recorded source. Factory Droid also needs an explicit producer-recorded parent/child binding before this reader can expose delegated children. Neither reader guesses relationships from a tool name, working directory, timing, or current project.
+
+A bounded local capture inspection on 2026-10-25 found explicit Kimi child events and separate child wires. Its Pi and Factory Droid samples contained no explicit subagent binding: the latest 20 files per harness held 7,724 and 245 records respectively; an additional size-stratified selection read seven Pi files (8,229 records) and 20 Factory files (252 records). These are sample limits, not a claim that every producer version lacks the metadata. The remaining Pi/Factory child coverage is unknown. Closing it requires a retained parent/child capture with an explicit source binding, followed by a reader-to-OTLP integration proof; the graph-corpus integrating owner owns that follow-up.
 
 ## Use
 
@@ -77,5 +87,5 @@ harness-sessions read <file|home|capture> [--harness h] [--session id] [--summar
 
 ## Tests
 
-The fixtures are sessions that the real harness CLIs wrote while talking to the trace-proof scripted model; the tests assert that script.
+The baseline fixtures are sessions that the real harness CLIs wrote while talking to the trace-proof scripted model; the tests assert that script. The Kimi child fixture retains complete existing parent and child wire records with all content removed, IDs pseudonymized, and source hashes, record counts, redaction version and token counters recorded in `test/fixtures/kimi/provenance.json`. Its integration test exercises discovery, full/summary reads, in-memory input and contract-span projection, preserving parent and child usage separately.
 The proof against the readers this package replaces is a comparison over stored sessions, recorded with each release.

package/dist/builder.d.ts

@@ -3,7 +3,6 @@ import type { SourceStats } from './source.js';
 export type BuildMode = 'full' | 'summary';
 /** An ISO-8601 instant from an ISO string, epoch milliseconds or epoch seconds; null otherwise. */
 export declare function isoTime(value: unknown): string | null;
-export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
 export declare const str: (value: unknown) => string | null;
 export declare function count(value: unknown): number | null;
 /** Parse tool arguments recorded as text; keep the text when it is not JSON. */

package/dist/builder.js

@@ -1,3 +1,4 @@
+import { isRecord } from '@tangle-network/agent-core';
 import { HARNESS_SESSION_SCHEMA } from './schema.js';
 /** An ISO-8601 instant from an ISO string, epoch milliseconds or epoch seconds; null otherwise. */
 export function isoTime(value) {
@@ -11,7 +12,6 @@ export function isoTime(value) {
     }
     return null;
 }
-export const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 export const str = (value) => (typeof value === 'string' ? value : null);
 export function count(value) {
     return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;

package/dist/capture.js

@@ -1,3 +1,4 @@
+import { isRecord } from '@tangle-network/agent-core';
 /**
  * Reading the native sessions in a capture.
  *
@@ -11,7 +12,7 @@
  */
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { isRecord, str } from './builder.js';
+import { str } from './builder.js';
 import { opencodeSessionsInStore } from './formats/opencode.js';
 import { maybeReaderFor, readerFor, readerForFormat } from './registry.js';
 import { isMissing } from './source.js';

package/dist/formats/claude-code.js

@@ -1,3 +1,4 @@
+import { isRecord } from '@tangle-network/agent-core';
 /**
  * Claude Code: `~/.claude/projects/<cwd slug>/<session id>.jsonl`, one JSON record per line, and
  * each subagent's own transcript at `<session id>/subagents/agent-<agent id>.jsonl`.
@@ -9,7 +10,7 @@
  * the API answered with.
  */
 import { basename, join } from 'node:path';
-import { SessionBuilder, count, isRecord, sessionError, str, textOf, usageOrNull } from '../builder.js';
+import { SessionBuilder, count, sessionError, str, textOf, usageOrNull } from '../builder.js';
 import { fileRecords } from '../source.js';
 import { runFold } from './fold.js';
 import { EVIDENCE, LOCATE_READS, STORES, mapLimit, mtimeMs, storeGlob, walkFiles, withinPath } from '../stores.js';

package/dist/formats/codex.js

@@ -1,3 +1,4 @@
+import { isRecord } from '@tangle-network/agent-core';
 /**
  * Codex: `~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<thread id>.jsonl`, one
  * `{timestamp, type, payload}` record per line.
@@ -10,7 +11,7 @@
  * (`total_token_usage`); the cumulative counter is the session total.
  */
 import { basename } from 'node:path';
-import { SessionBuilder, argumentsOf, count, isRecord, sessionError, str, textOf, usageOrNull, } from '../builder.js';
+import { SessionBuilder, argumentsOf, count, sessionError, str, textOf, usageOrNull, } from '../builder.js';
 import { fileRecords, isMissing } from '../source.js';
 import { runFold } from './fold.js';
 import { CODEX_HOME_RULE, EVIDENCE, LOCATE_READS, STORES, codexHomes, mapLimit, storeGlob, walkFiles, withinPath } from '../stores.js';

package/dist/formats/factory.js

@@ -1,3 +1,4 @@
+import { isRecord } from '@tangle-network/agent-core';
 /**
  * Factory Droid: `~/.factory/sessions/<encoded cwd>/<session id>.jsonl` plus a
  * `<session id>.settings.json` beside it.
@@ -10,7 +11,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
-import { SessionBuilder, count, isRecord, str, textOf, usageOrNull } from '../builder.js';
+import { SessionBuilder, count, str, textOf, usageOrNull } from '../builder.js';
 import { fileRecords, isMissing } from '../source.js';
 import { EVIDENCE, STORES, mtimeMs, storeGlob, walkFiles, withinPath } from '../stores.js';
 import { runFold } from './fold.js';

package/dist/formats/kimi.js

@@ -1,3 +1,4 @@
+import { isRecord } from '@tangle-network/agent-core';
 /**
  * Kimi Code: one directory per session, `~/.kimi/sessions/<workdir hash>/<session id>/`, holding
  * `wire.jsonl` (the event stream this reader folds) and `context.jsonl` (the model context).
@@ -11,7 +12,7 @@
  * subagent's events arrive wrapped in `SubagentEvent`. The wire records no model.
  */
 import { basename, dirname, join } from 'node:path';
-import { SessionBuilder, count, isRecord, sessionError, str, textOf, usageOrNull } from '../builder.js';
+import { SessionBuilder, count, sessionError, str, textOf, usageOrNull } from '../builder.js';
 import { fileRecords } from '../source.js';
 import { EVIDENCE, STORES, mtimeMs, storeGlob, walkFiles } from '../stores.js';
 import { runFold } from './fold.js';
@@ -20,6 +21,13 @@ const STORE = STORES[FORMAT];
 const HARNESS = 'kimi-code';
 /** The event stream this reader folds; the store also holds context.jsonl and state.json. */
 const WIRE = '*/{id}/wire.jsonl';
+const CHILD_WIRE = '*/*/subagents/{id}/wire.jsonl';
+/** Kimi's producer places each agent's wire under its owning session's subagents directory. */
+function sessionIdentity(path) {
+    const directory = dirname(path);
+    const container = dirname(directory);
+    return { id: basename(directory), parent: basename(container) === 'subagents' ? basename(dirname(container)) : null };
+}
 function usageOf(value) {
     if (!isRecord(value))
         return null;
@@ -141,7 +149,7 @@ export function createFold(ref, mode, stats) {
                 subagentEvents += 1;
                 const agent = str(payload.agent_id);
                 if (agent)
-                    builder.child(agent, str(payload.parent_tool_call_id));
+                    builder.child(agent, str(payload.parent_tool_call_id) ?? str(payload.task_tool_call_id));
                 break;
             }
             default:
@@ -154,7 +162,7 @@ export function createFold(ref, mode, stats) {
         if (compactions > 0)
             builder.gap(`${compactions} compactions replaced earlier context`);
         if (subagentEvents > 0)
-            builder.gap(`${subagentEvents} subagent events are logged in this session; each subagent is its own session`);
+            builder.gap(`${subagentEvents} wrapped subagent events were excluded from this session's own messages and usage; separate child wires must be read for child execution`);
         builder.inferEnding(aborted ? { at: aborted.at, error: null } : undefined);
         return builder;
     };
@@ -165,10 +173,15 @@ export async function fold(ref, mode, options, source = fileRecords(ref.path, {
 }
 async function locate(home, opts) {
     const root = join(home, STORE.root);
-    const pattern = storeGlob(WIRE, opts.nativeSessionId);
+    const pattern = storeGlob(WIRE);
+    const children = storeGlob(CHILD_WIRE);
     const refs = [];
     for (const rel of await walkFiles(root)) {
-        if (!pattern.test(rel))
+        if (!pattern.test(rel) && !children.test(rel))
+            continue;
+        const { id, parent } = sessionIdentity(rel);
+        // A parent lookup includes its recorded child wires; a child lookup selects that agent.
+        if (opts.nativeSessionId && id !== opts.nativeSessionId && parent !== opts.nativeSessionId)
             continue;
         const path = join(root, rel);
         const mtime = await mtimeMs(path);
@@ -177,10 +190,9 @@ async function locate(home, opts) {
         // Kimi keys the session directory by a hash of its working directory and records no cwd.
         if (opts.cwd)
             continue;
-        const id = basename(dirname(path));
         const context = join(dirname(path), 'context.jsonl');
         const files = (await mtimeMs(context)) > 0 ? [path, context] : [path];
-        refs.push({ harness: HARNESS, format: FORMAT, nativeSessionId: id, path, files, home, cwd: null, mtimeMs: mtime, parentNativeSessionId: null });
+        refs.push({ harness: HARNESS, format: FORMAT, nativeSessionId: id, path, files, home, cwd: null, mtimeMs: mtime, parentNativeSessionId: parent });
     }
     return refs.sort((a, b) => b.mtimeMs - a.mtimeMs);
 }
@@ -189,7 +201,7 @@ export const kimiReader = {
     aliases: ['kimi', 'kimi-cli'],
     formats: [FORMAT],
     stores: [STORE],
-    globs: { session: WIRE },
+    globs: { session: WIRE, children: CHILD_WIRE },
     evidence: EVIDENCE[FORMAT],
     locate: (home, opts = {}) => locate(home, opts),
     async read(ref, opts = {}) {
@@ -201,5 +213,6 @@ export const kimiReader = {
 };
 /** A session read from its `wire.jsonl` outside a HOME layout. */
 export function kimiRefForFile(path) {
-    return { harness: HARNESS, format: FORMAT, nativeSessionId: basename(dirname(path)), path, files: [path], home: null, cwd: null, mtimeMs: 0, parentNativeSessionId: null };
+    const { id, parent } = sessionIdentity(path);
+    return { harness: HARNESS, format: FORMAT, nativeSessionId: id, path, files: [path], home: null, cwd: null, mtimeMs: 0, parentNativeSessionId: parent };
 }

package/dist/formats/opencode.js

@@ -1,3 +1,4 @@
+import { isRecord } from '@tangle-network/agent-core';
 /**
  * OpenCode 1.x: one SQLite store for every session in the HOME,
  * `~/.local/share/opencode/opencode.db` (with `-wal` and `-shm` siblings while it is open).
@@ -12,7 +13,7 @@
  */
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
-import { SessionBuilder, count, isRecord, isoTime, sessionError, str, usageOrNull } from '../builder.js';
+import { SessionBuilder, count, isoTime, sessionError, str, usageOrNull } from '../builder.js';
 import { isMissing, withSqlite } from '../source.js';
 import { EVIDENCE, STORES, mtimeMs, withinPath } from '../stores.js';
 const FORMAT = 'opencode.sqlite';

package/dist/formats/pi.js

@@ -1,3 +1,4 @@
+import { isRecord } from '@tangle-network/agent-core';
 /**
  * Pi: `~/.pi/agent/sessions/<encoded cwd>/<timestamp>_<session id>.jsonl`, one entry per line.
  *
@@ -9,7 +10,7 @@
  * `toolCallId`. Entries form a tree through `parentId`; branches share one file.
  */
 import { basename, join } from 'node:path';
-import { SessionBuilder, count, isRecord, sessionError, str, textOf, usageOrNull } from '../builder.js';
+import { SessionBuilder, count, sessionError, str, textOf, usageOrNull } from '../builder.js';
 import { fileRecords } from '../source.js';
 import { runFold } from './fold.js';
 import { EVIDENCE, STORES, mtimeMs, storeGlob, walkFiles, withinPath } from '../stores.js';

package/dist/projections/turns.js

@@ -1,4 +1,4 @@
-import { isRecord } from '../builder.js';
+import { isRecord } from '@tangle-network/agent-core';
 export function summarizeText(text, n) {
     const t = text.replace(/\s+/gu, ' ').trim();
     return t.length <= n ? t : `${t.slice(0, n - 1)}…`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/harness-sessions",
-  "version": "0.1.7",
+  "version": "0.2.1",
   "description": "One reader for every coding-agent harness's native session (Claude Code, Codex, OpenCode, Pi): store layouts, a normalized session with messages, tool calls, served models, usage and ending errors, and projections to chat messages, OTLP spans and turns",
   "type": "module",
   "sideEffects": false,
@@ -40,6 +40,7 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@tangle-network/agent-core": "^0.13.0",
     "@tangle-network/agent-trace-contract": "^2.0.0"
   },
   "devDependencies": {