@phnx-labs/agents-cli 1.20.15 → 1.20.16

package/dist/lib/plugin-marketplace.d.ts

@@ -98,6 +98,21 @@ export declare function knownMarketplacesPath(agent: AgentId, versionHome: strin
  * Internal symlinks (target stays inside the plugin root) are preserved.
  */
 export declare function copyPluginToMarketplace(plugin: DiscoveredPlugin, spec: MarketplaceSpec | string, agent: AgentId, versionHome: string): string;
+/**
+ * Claude Code's plugin-manifest schema requires the resource path fields to be
+ * relative paths starting with "./" — `skills`/`commands`/`agents` are
+ * `union([startsWith("./"), array(startsWith("./"))])` (verified against the
+ * Claude Code binary). Bare names like "loop" fail validation and Claude rejects
+ * the ENTIRE plugin at load time, surfacing only in its `/plugin` > Errors tab.
+ *
+ * agents-cli copies plugin.json verbatim into the marketplace, so a malformed
+ * manifest ships looking fully installed while loading nothing. This catches the
+ * unambiguous type violation (non-"./" string entries) and returns one warning
+ * per offending field so the caller can surface it loudly. `hooks`/`mcpServers`
+ * are intentionally skipped — they legitimately accept inline objects, so a path
+ * check would false-positive.
+ */
+export declare function validateClaudePluginManifest(manifest: unknown): string[];
 /**
  * Re-synthesize <marketplace>/.claude-plugin/marketplace.json from the plugins
  * already installed under <marketplace>/plugins/. Always run after add or remove

package/dist/lib/plugin-marketplace.js

@@ -185,6 +185,47 @@ export function copyPluginToMarketplace(plugin, spec, agent, versionHome) {
     }
     return dest;
 }
+// ─── Manifest validation ─────────────────────────────────────────────────────
+/**
+ * Claude Code's plugin-manifest schema requires the resource path fields to be
+ * relative paths starting with "./" — `skills`/`commands`/`agents` are
+ * `union([startsWith("./"), array(startsWith("./"))])` (verified against the
+ * Claude Code binary). Bare names like "loop" fail validation and Claude rejects
+ * the ENTIRE plugin at load time, surfacing only in its `/plugin` > Errors tab.
+ *
+ * agents-cli copies plugin.json verbatim into the marketplace, so a malformed
+ * manifest ships looking fully installed while loading nothing. This catches the
+ * unambiguous type violation (non-"./" string entries) and returns one warning
+ * per offending field so the caller can surface it loudly. `hooks`/`mcpServers`
+ * are intentionally skipped — they legitimately accept inline objects, so a path
+ * check would false-positive.
+ */
+export function validateClaudePluginManifest(manifest) {
+    const warnings = [];
+    if (!manifest || typeof manifest !== 'object')
+        return warnings;
+    const m = manifest;
+    for (const field of ['skills', 'commands', 'agents']) {
+        const value = m[field];
+        if (value === undefined || value === null)
+            continue;
+        const entries = Array.isArray(value) ? value : [value];
+        for (const entry of entries) {
+            if (typeof entry !== 'string') {
+                warnings.push(`plugin.json field "${field}" must contain relative paths starting with "./" ` +
+                    `(e.g. "./${field}/<name>"); found a non-string value. Claude Code will reject the whole plugin.`);
+                break;
+            }
+            if (!entry.startsWith('./')) {
+                warnings.push(`plugin.json field "${field}" entry "${entry}" must be a relative path starting with "./" ` +
+                    `(e.g. "./${field}/${entry}"). Claude Code rejects the entire plugin otherwise — ` +
+                    `remove the field to auto-discover from ${field}/, or use relative paths.`);
+                break;
+            }
+        }
+    }
+    return warnings;
+}
 // ─── Catalog synthesis ──────────────────────────────────────────────────────
 /**
  * Re-synthesize <marketplace>/.claude-plugin/marketplace.json from the plugins
@@ -226,6 +267,9 @@ export function syncMarketplaceManifest(spec, agent, versionHome) {
         catch {
             continue;
         }
+        for (const warning of validateClaudePluginManifest(manifest)) {
+            process.stderr.write(`agents-cli: plugin '${manifest.name ?? entry.name}': ${warning}\n`);
+        }
         entries.push({
             name: manifest.name,
             source: `./plugins/${manifest.name}`,

package/dist/lib/secrets/index.js

@@ -236,6 +236,26 @@ export function setKeychainToken(item, value) {
         linuxBackend.set(item, value);
         return;
     }
+    // Bare (non-`agents-cli.`) items are written WITHOUT the biometry ACL so
+    // they round-trip with the no-prompt read path in getKeychainToken (which
+    // also uses /usr/bin/security for non-our items). This is what lets a
+    // SessionStart hook read e.g. `linear-api-key` silently on every launch.
+    // Routing these through the helper would attach a Touch ID ACL that the
+    // /usr/bin/security read can't satisfy without popping the legacy password
+    // sheet. -U upserts so repeated sets overwrite in place.
+    if (!isOurItem(item)) {
+        const sec = spawnSync('/usr/bin/security', [
+            'add-generic-password', '-U',
+            '-a', os.userInfo().username,
+            '-s', item,
+            '-w', value,
+        ], { stdio: ['ignore', 'pipe', 'pipe'] });
+        if (sec.status !== 0) {
+            const msg = sec.stderr?.toString().trim();
+            throw new Error(msg || `Failed to write keychain item '${item}'.`);
+        }
+        return;
+    }
     const bin = getKeychainHelperPath();
     const result = spawnSync(bin, ['set', item, os.userInfo().username], {
         input: value,

package/dist/lib/session/parse.d.ts

@@ -49,3 +49,5 @@ export declare function parseOpenCode(filePath: string): SessionEvent[];
 export declare function parseRush(filePath: string): SessionEvent[];
 /** Parse a Hermes session JSON file into normalized events. */
 export declare function parseHermes(filePath: string): SessionEvent[];
+/** Parse a Kimi session state.json file by reading its agents/main/wire.jsonl. */
+export declare function parseKimi(filePath: string): SessionEvent[];

package/dist/lib/session/parse.js

@@ -6,6 +6,7 @@
  * objects suitable for rendering, filtering, and summarization.
  */
 import * as fs from 'fs';
+import * as path from 'path';
 import { execFileSync } from 'child_process';
 /**
  * Largest session file we will load into memory. Above this we throw a clean
@@ -106,8 +107,8 @@ export function parseSession(filePath, agent) {
             events = parseHermes(filePath);
             break;
         case 'kimi':
-            events = [];
-            break; // Kimi event parsing not implemented yet — discover.ts builds metadata only
+            events = parseKimi(filePath);
+            break;
     }
     // Chokepoint: every string field that originated in an untrusted session
     // file gets stripped of terminal escapes here, so renderers downstream can
@@ -130,6 +131,8 @@ export function detectAgent(filePath) {
         return 'rush';
     if (filePath.includes('/.hermes/') || filePath.includes('\\.hermes\\'))
         return 'hermes';
+    if (filePath.includes('/.kimi-code/') || filePath.includes('\\.kimi-code\\'))
+        return 'kimi';
     // Cloud convention: cloud-sessions/<id>/session.<format>.jsonl
     const cloudMatch = filePath.match(/session\.(claude|codex|rush)\.jsonl(?:$|[?#])/);
     if (cloudMatch)
@@ -958,3 +961,166 @@ function hermesContentToText(content) {
         .join('\n')
         .trim();
 }
+// ---------------------------------------------------------------------------
+// Kimi parser
+//
+// Kimi stores session metadata in state.json and the conversation transcript
+// in agents/main/wire.jsonl under ~/.kimi-code/sessions/<workdir>/session_<uuid>/.
+// wire.jsonl uses a role-based schema:
+//   - "context.append_message" with role=user/assistant -> messages
+//   - "context.append_loop_event" with content.part type=text/think -> message/thinking
+//   - "context.append_loop_event" with event.type=tool.call -> tool_use
+//   - "context.append_loop_event" with event.type=tool.result -> tool_result
+//   - "usage.record" -> usage
+// ---------------------------------------------------------------------------
+/** Parse a Kimi session state.json file by reading its agents/main/wire.jsonl. */
+export function parseKimi(filePath) {
+    const sessionDir = path.dirname(filePath);
+    const wirePath = path.join(sessionDir, 'agents', 'main', 'wire.jsonl');
+    if (!fs.existsSync(wirePath)) {
+        return [];
+    }
+    const content = safeReadSessionFile(wirePath);
+    const lines = content.split('\n').filter(l => l.trim());
+    const events = [];
+    // Map tool.call uuid -> tool name so tool.result can carry the tool name.
+    const toolCallMap = new Map();
+    function extractMessageText(rawContent) {
+        if (typeof rawContent === 'string')
+            return rawContent.trim();
+        if (Array.isArray(rawContent)) {
+            return rawContent
+                .map((part) => (typeof part?.text === 'string' ? part.text : ''))
+                .join('')
+                .trim();
+        }
+        return '';
+    }
+    function timestampFrom(raw) {
+        const t = raw?.time;
+        if (typeof t === 'number' && t > 0) {
+            return new Date(t).toISOString();
+        }
+        return new Date().toISOString();
+    }
+    for (const line of lines) {
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const type = raw?.type;
+        const timestamp = timestampFrom(raw);
+        if (type === 'context.append_message') {
+            const message = raw.message || {};
+            const role = message.role === 'user' ? 'user' : 'assistant';
+            const text = extractMessageText(message.content);
+            if (!text)
+                continue;
+            events.push({
+                type: 'message',
+                agent: 'kimi',
+                timestamp,
+                role,
+                content: text,
+            });
+        }
+        else if (type === 'context.append_loop_event') {
+            const event = raw.event || {};
+            const eventType = event.type;
+            if (eventType === 'content.part') {
+                const part = event.part || {};
+                const partType = part.type;
+                if (partType === 'text') {
+                    const text = typeof part.text === 'string' ? part.text.trim() : '';
+                    if (text) {
+                        events.push({
+                            type: 'message',
+                            agent: 'kimi',
+                            timestamp,
+                            role: 'assistant',
+                            content: text,
+                        });
+                    }
+                }
+                else if (partType === 'think') {
+                    const think = typeof part.think === 'string' ? part.think.trim() : '';
+                    if (think) {
+                        events.push({
+                            type: 'thinking',
+                            agent: 'kimi',
+                            timestamp,
+                            content: think,
+                        });
+                    }
+                }
+            }
+            else if (eventType === 'tool.call') {
+                const fn = event.function || {};
+                const toolName = typeof event.name === 'string' ? event.name : (fn.name || 'unknown');
+                let args = {};
+                if (typeof fn.arguments === 'string') {
+                    try {
+                        args = JSON.parse(fn.arguments);
+                    }
+                    catch {
+                        args = { _raw: fn.arguments };
+                    }
+                }
+                else if (fn.arguments && typeof fn.arguments === 'object') {
+                    args = fn.arguments;
+                }
+                const callId = event.toolCallId || event.uuid;
+                if (callId) {
+                    toolCallMap.set(callId, toolName);
+                }
+                events.push({
+                    type: 'tool_use',
+                    agent: 'kimi',
+                    timestamp,
+                    tool: toolName,
+                    args,
+                    path: args.path || args.file_path || undefined,
+                    command: toolName === 'Bash' ? args.command : undefined,
+                });
+            }
+            else if (eventType === 'tool.result') {
+                const callId = event.toolCallId || event.parentUuid;
+                const toolName = (callId && toolCallMap.get(callId)) || 'unknown';
+                const result = event.result || {};
+                const output = typeof result.output === 'string' ? result.output : '';
+                const isError = result.isError === true || (output && output.startsWith('Error:'));
+                events.push({
+                    type: isError ? 'error' : 'tool_result',
+                    agent: 'kimi',
+                    timestamp,
+                    tool: toolName,
+                    success: !isError,
+                    output: output.length > 500 ? output.slice(0, 497) + '...' : output,
+                });
+                if (callId) {
+                    toolCallMap.delete(callId);
+                }
+            }
+        }
+        else if (type === 'usage.record') {
+            const usage = raw.usage || {};
+            const inputTokens = usage.inputOther ?? usage.input_tokens;
+            const outputTokens = usage.output ?? usage.output_tokens;
+            if ((typeof inputTokens === 'number' && inputTokens >= 0) ||
+                (typeof outputTokens === 'number' && outputTokens >= 0)) {
+                events.push({
+                    type: 'usage',
+                    agent: 'kimi',
+                    timestamp,
+                    model: raw.model || usage.model,
+                    inputTokens: typeof inputTokens === 'number' ? inputTokens : undefined,
+                    outputTokens: typeof outputTokens === 'number' ? outputTokens : undefined,
+                });
+            }
+        }
+    }
+    return events;
+}

package/dist/lib/session/sync/agents.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Per-agent adapter for sync. Each supported agent declares where its
+ * transcripts live and how to derive a session id and storage-relative key
+ * from a file path. The merge (crdt.ts) and transport (r2.ts) are fully
+ * agent-agnostic — adding a new agent is just another entry in SYNC_AGENTS.
+ *
+ * Mirror layout: synced-in transcripts land under
+ *   ~/.agents/.history/backups/<agent>/<machine>/<subdir>/<relKey>
+ * which is already a scan root (getAgentSessionDirs scans backups/<agent>/<ts>),
+ * so the existing incremental scanner indexes them with no changes. Because the
+ * scanner dedups by session id with the live home scanned first, a session that
+ * also exists locally always wins — the mirror only ever fills in sessions
+ * originated on other machines.
+ */
+export interface LocalTranscript {
+    /** Absolute path on this machine. */
+    absPath: string;
+    /** Globally-unique session id (the grouping key across machines). */
+    sessionId: string;
+    /** Path relative to the agent's subdir root — preserved in the mirror layout. */
+    relKey: string;
+}
+export interface SyncAgentSpec {
+    id: string;
+    /** Config subdir under the agent home that holds transcripts. */
+    subdir: string;
+    /** Derive the session id from a storage-relative key. */
+    sessionIdFromRelKey(relKey: string): string;
+}
+export declare const SYNC_AGENTS: SyncAgentSpec[];
+/**
+ * List this machine's own transcript files for an agent, EXCLUDING the sync
+ * mirror (we never re-upload another machine's files under our prefix). Dedups
+ * by session id so a session present in multiple version homes is uploaded once.
+ */
+export declare function listLocalTranscripts(spec: SyncAgentSpec): LocalTranscript[];
+/** Session ids this machine holds locally (live home), used to skip mirror writes. */
+export declare function localSessionIds(spec: SyncAgentSpec): Set<string>;
+/** Absolute mirror path for a remote machine's transcript — lands in a scan root. */
+export declare function mirrorPath(spec: SyncAgentSpec, machine: string, relKey: string): string;
+/** R2 object key for a transcript: sessions/<machine>/<agent>/<sessionId>.jsonl */
+export declare function objectKey(machine: string, agentId: string, sessionId: string): string;
+/** R2 object key for a machine's manifest. */
+export declare function manifestKey(machine: string): string;
+/** Prefix under which all machine manifests live (for discovery). */
+export declare const SESSIONS_PREFIX = "sessions/";

package/dist/lib/session/sync/agents.js

@@ -0,0 +1,94 @@
+/**
+ * Per-agent adapter for sync. Each supported agent declares where its
+ * transcripts live and how to derive a session id and storage-relative key
+ * from a file path. The merge (crdt.ts) and transport (r2.ts) are fully
+ * agent-agnostic — adding a new agent is just another entry in SYNC_AGENTS.
+ *
+ * Mirror layout: synced-in transcripts land under
+ *   ~/.agents/.history/backups/<agent>/<machine>/<subdir>/<relKey>
+ * which is already a scan root (getAgentSessionDirs scans backups/<agent>/<ts>),
+ * so the existing incremental scanner indexes them with no changes. Because the
+ * scanner dedups by session id with the live home scanned first, a session that
+ * also exists locally always wins — the mirror only ever fills in sessions
+ * originated on other machines.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getHistoryDir } from '../../state.js';
+import { getAgentSessionDirs } from '../discover.js';
+import { walkForFiles } from '../../fs-walk.js';
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+export const SYNC_AGENTS = [
+    {
+        id: 'claude',
+        subdir: 'projects',
+        // Claude transcripts are <projectDir>/<sessionId>.jsonl.
+        sessionIdFromRelKey: rel => path.basename(rel).replace(/\.jsonl$/, ''),
+    },
+    {
+        id: 'codex',
+        subdir: 'sessions',
+        // Codex transcripts are rollout-<ts>-<uuid>.jsonl under date dirs; the uuid
+        // is the session id (matches session_meta.payload.id).
+        sessionIdFromRelKey: rel => path.basename(rel).match(UUID_RE)?.[0] ?? rel,
+    },
+];
+let cachedMirrorRoot = null;
+function mirrorRootReal() {
+    if (cachedMirrorRoot)
+        return cachedMirrorRoot;
+    const root = path.join(getHistoryDir(), 'backups');
+    cachedMirrorRoot = safeReal(root);
+    return cachedMirrorRoot;
+}
+function safeReal(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/**
+ * List this machine's own transcript files for an agent, EXCLUDING the sync
+ * mirror (we never re-upload another machine's files under our prefix). Dedups
+ * by session id so a session present in multiple version homes is uploaded once.
+ */
+export function listLocalTranscripts(spec) {
+    const mirror = mirrorRootReal();
+    const out = [];
+    const seen = new Set();
+    for (const dir of getAgentSessionDirs(spec.id, spec.subdir)) {
+        if (safeReal(dir).startsWith(mirror))
+            continue; // skip synced-in mirror dirs
+        for (const abs of walkForFiles(dir, '.jsonl', 100_000)) {
+            const relKey = path.relative(dir, abs);
+            if (!relKey || relKey.startsWith('..'))
+                continue;
+            const sessionId = spec.sessionIdFromRelKey(relKey);
+            if (seen.has(sessionId))
+                continue;
+            seen.add(sessionId);
+            out.push({ absPath: abs, sessionId, relKey });
+        }
+    }
+    return out;
+}
+/** Session ids this machine holds locally (live home), used to skip mirror writes. */
+export function localSessionIds(spec) {
+    return new Set(listLocalTranscripts(spec).map(t => t.sessionId));
+}
+/** Absolute mirror path for a remote machine's transcript — lands in a scan root. */
+export function mirrorPath(spec, machine, relKey) {
+    return path.join(getHistoryDir(), 'backups', spec.id, machine, spec.subdir, relKey);
+}
+/** R2 object key for a transcript: sessions/<machine>/<agent>/<sessionId>.jsonl */
+export function objectKey(machine, agentId, sessionId) {
+    return `sessions/${machine}/${agentId}/${sessionId}.jsonl`;
+}
+/** R2 object key for a machine's manifest. */
+export function manifestKey(machine) {
+    return `sessions/${machine}/manifest.json`;
+}
+/** Prefix under which all machine manifests live (for discovery). */
+export const SESSIONS_PREFIX = 'sessions/';

package/dist/lib/session/sync/config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Configuration for cross-machine session sync: R2 credentials and this
+ * machine's stable identity. Credentials come from the `r2.backups` secrets
+ * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
+ */
+/** Secrets bundle holding the R2 credentials. */
+export declare const SYNC_BUNDLE = "r2.backups";
+export interface R2Config {
+    accountId: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** S3-compatible endpoint for the account (no bucket, no trailing slash). */
+    endpoint: string;
+}
+/**
+ * Resolve R2 credentials from the `r2.backups` bundle. Throws a clear,
+ * actionable error if the bundle or any key is missing — sync cannot proceed
+ * without real credentials (no silent fallback).
+ */
+export declare function loadR2Config(): R2Config;
+/** True when the sync bundle exists and looks resolvable, without throwing. */
+export declare function isSyncConfigured(): boolean;
+/**
+ * This machine's stable, human-readable id, used as its R2 prefix and mirror
+ * directory name. Tailnet hostnames (zion, yosemite-s0, mac-mini) are already
+ * unique and readable; we lowercase and strip any domain suffix. Overridable
+ * via AGENTS_SYNC_MACHINE_ID for tests and unusual setups.
+ */
+export declare function machineId(): string;

package/dist/lib/session/sync/config.js

@@ -0,0 +1,58 @@
+/**
+ * Configuration for cross-machine session sync: R2 credentials and this
+ * machine's stable identity. Credentials come from the `r2.backups` secrets
+ * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
+ */
+import * as os from 'os';
+import { readAndResolveBundleEnv } from '../../secrets/bundles.js';
+/** Secrets bundle holding the R2 credentials. */
+export const SYNC_BUNDLE = 'r2.backups';
+/**
+ * Resolve R2 credentials from the `r2.backups` bundle. Throws a clear,
+ * actionable error if the bundle or any key is missing — sync cannot proceed
+ * without real credentials (no silent fallback).
+ */
+export function loadR2Config() {
+    const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'sessions-sync' });
+    const accountId = env.R2_ACCOUNT_ID?.trim();
+    const bucket = env.R2_BUCKET_NAME?.trim();
+    const accessKeyId = env.R2_ACCESS_KEY_ID?.trim();
+    const secretAccessKey = env.R2_SECRET_ACCESS_KEY?.trim();
+    const missing = [
+        !accountId && 'R2_ACCOUNT_ID',
+        !bucket && 'R2_BUCKET_NAME',
+        !accessKeyId && 'R2_ACCESS_KEY_ID',
+        !secretAccessKey && 'R2_SECRET_ACCESS_KEY',
+    ].filter(Boolean);
+    if (missing.length > 0) {
+        throw new Error(`Sessions sync: bundle '${SYNC_BUNDLE}' is missing ${missing.join(', ')}. ` +
+            `Add them with: agents secrets add ${SYNC_BUNDLE} <KEY>`);
+    }
+    return {
+        accountId: accountId,
+        bucket: bucket,
+        accessKeyId: accessKeyId,
+        secretAccessKey: secretAccessKey,
+        endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
+    };
+}
+/** True when the sync bundle exists and looks resolvable, without throwing. */
+export function isSyncConfigured() {
+    try {
+        loadR2Config();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * This machine's stable, human-readable id, used as its R2 prefix and mirror
+ * directory name. Tailnet hostnames (zion, yosemite-s0, mac-mini) are already
+ * unique and readable; we lowercase and strip any domain suffix. Overridable
+ * via AGENTS_SYNC_MACHINE_ID for tests and unusual setups.
+ */
+export function machineId() {
+    const raw = process.env.AGENTS_SYNC_MACHINE_ID || os.hostname();
+    return raw.split('.')[0].trim().toLowerCase().replace(/[^a-z0-9_-]/g, '-') || 'unknown';
+}

package/dist/lib/session/sync/crdt.d.ts

@@ -0,0 +1,44 @@
+/**
+ * CRDT merge for agent transcripts.
+ *
+ * A transcript (Claude JSONL, Codex JSONL, …) is an append-only log of
+ * immutable events: each line is written once and never rewritten, and Claude
+ * already tolerates branches within one file (parentUuid fan-out). That makes a
+ * transcript a grow-only set (G-Set) of events, and merging two copies of the
+ * same session is a set union — associative, commutative, idempotent. Two
+ * machines that each appended to the same session therefore converge to the
+ * exact same merged file regardless of sync order or timing, with zero conflict
+ * resolution and zero data loss.
+ *
+ * Events are identified by the SHA-256 of their raw line bytes. We deliberately
+ * do NOT key on a per-event `uuid`: Codex lines carry no id, and because an
+ * event is written exactly once and then copied verbatim across machines, the
+ * raw bytes are a stable, agent-agnostic identity. Multiplicity is preserved
+ * (some transcripts contain legitimately identical lines, e.g. paired
+ * `queue-operation` entries) by taking the per-hash max count across sources.
+ */
+export interface ParsedEvent {
+    /** Original line bytes, exactly as stored (no trailing newline). */
+    raw: string;
+    /** SHA-256 of `raw` — the event's identity. */
+    hash: string;
+    /** Top-level ISO `timestamp`, or '' when absent/unparseable. */
+    ts: string;
+}
+/** Parse a transcript's raw text into events, skipping blank lines. */
+export declare function parseTranscript(content: string): ParsedEvent[];
+/**
+ * Merge copies of the same session into one transcript via G-Set union.
+ *
+ * Returns a source VERBATIM (no reordering, byte-identical) for the common
+ * cases — one source, all sources identical, or one source a superset of the
+ * rest — so the steady state never rewrites unchanged files. Only a true fork
+ * (each side holds events the other lacks) produces a reordered union, sorted
+ * by (timestamp, hash) so every machine derives identical bytes.
+ */
+export declare function mergeTranscripts(contents: string[]): string;
+/** Count distinct + total events across copies (for logging / manifest stats). */
+export declare function transcriptStats(content: string): {
+    events: number;
+    lastTs: string;
+};