@aiwg/cli 2026.9.19 → 2026.9.21

package/dist/src/sessions/adapters/grok-build.js

@@ -0,0 +1,187 @@
+import { basename, extname } from 'node:path';
+import { SessionContractError, } from '../contracts.js';
+import { readBoundedText } from '../readers.js';
+export const GROK_BUILD_ADAPTER_VERSION = '1.0.0';
+export const GROK_BUILD_CLI_EXPORT_SCHEMA_VERSION = '1.0.0';
+export const GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS = 'grok-build-cli-markdown-export';
+/**
+ * Imports the documented `grok export <session-id> <file>` surface.
+ *
+ * The public export contract is intentionally lossy. Direct reads from
+ * $GROK_HOME/sessions are prohibited until a released native schema has been
+ * qualified independently.
+ */
+export class GrokBuildSessionAdapter {
+    limits;
+    provider = 'grok-build';
+    adapterVersion = GROK_BUILD_ADAPTER_VERSION;
+    disposition = 'implemented';
+    supportedOperations = ['inspect', 'stream'];
+    acquisitionModes = ['manual-export'];
+    constructor(limits) {
+        this.limits = limits;
+    }
+    async *discover(_scope) {
+        throw new SessionContractError('UNSUPPORTED_OPERATION', 'Grok Build native-store discovery is disabled. Run `grok sessions list`, then '
+            + '`grok export <session-id> <session-id>.md` and import that authorized export.');
+    }
+    async inspect(source) {
+        await this.readSource(source);
+        return {
+            sourceSchemaVersion: GROK_BUILD_CLI_EXPORT_SCHEMA_VERSION,
+            consistency: 'complete',
+            operationalState: 'available',
+        };
+    }
+    async *stream(source, cursor) {
+        const parsed = await this.readSource(source);
+        const start = parseCursor(cursor?.value);
+        for (const [sequence, block] of parsed.blocks.entries()) {
+            if (sequence < start)
+                continue;
+            if (block.heading === 'Tools') {
+                for (const tool of parseTools(block.text, sequence))
+                    yield {
+                        nativeSessionId: parsed.sessionId,
+                        nativeEventId: undefined,
+                        sequence: tool.sequence,
+                        kind: 'tool-call',
+                        role: 'tool',
+                        toolName: tool.name,
+                        occurredAt: undefined,
+                        text: tool.text,
+                        rawReference: { locatorClass: source.locatorClass, sequence },
+                        extensions: provenance(source, parsed.sessionId, 'Tools'),
+                    };
+                continue;
+            }
+            yield {
+                nativeSessionId: parsed.sessionId,
+                nativeEventId: undefined,
+                sequence: sequence * 1_000,
+                kind: 'message',
+                role: block.heading === 'User' ? 'user' : 'assistant',
+                occurredAt: undefined,
+                text: block.text,
+                rawReference: { locatorClass: source.locatorClass, sequence },
+                extensions: provenance(source, parsed.sessionId, block.heading),
+            };
+        }
+    }
+    async readSource(source) {
+        if (source.locatorClass !== GROK_BUILD_CLI_EXPORT_LOCATOR_CLASS) {
+            throw new SessionContractError('UNSUPPORTED_OPERATION', 'Grok Build accepts only a documented `grok export` Markdown transcript; '
+                + 'native session files, Grok Bot exports, and Cursor stores are not supported.');
+        }
+        const filename = basename(source.locator, extname(source.locator));
+        if (extname(source.locator).toLowerCase() !== '.md' || !UUID.test(filename)) {
+            throw new SessionContractError('MALFORMED_SOURCE', 'Grok Build export filename must be <session-id>.md so the documented CLI session ID is preserved.');
+        }
+        const { value } = await readBoundedText({
+            selectedPath: source.locator,
+            allowedRoots: source.authorizedScope.allowedRoots,
+        }, this.limits);
+        const blocks = validateGrokBuildMarkdown(value);
+        return { sessionId: filename.toLowerCase(), blocks };
+    }
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function validateGrokBuildMarkdown(value) {
+    const blocks = parseBlocks(value);
+    for (const [sequence, block] of blocks.entries()) {
+        if (block.heading === 'Tools')
+            parseTools(block.text, sequence);
+    }
+    if (blocks.length === 0 || !blocks.some((block) => block.heading === 'User')) {
+        throw new SessionContractError('MALFORMED_SOURCE', 'Unrecognized Grok Build CLI export; expected exact `## User`, `## Assistant`, or `## Tools` headings.');
+    }
+    return blocks;
+}
+function parseBlocks(value) {
+    const blocks = [];
+    let current;
+    const flush = () => {
+        if (!current)
+            return;
+        const text = current.lines.join('\n').trim();
+        if (!text && current.heading === 'Tools') {
+            throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build tools block is empty');
+        }
+        if (text)
+            blocks.push({ heading: current.heading, text });
+    };
+    for (const line of value.replace(/\r\n/g, '\n').split('\n')) {
+        const match = /^## (User|Assistant|Tools)$/.exec(line);
+        if (match) {
+            flush();
+            current = { heading: match[1], lines: [] };
+        }
+        else if (/^##\s+/.test(line)) {
+            throw new SessionContractError('SCHEMA_DRIFT', `unknown Grok Build CLI export heading: ${line}`);
+        }
+        else if (current) {
+            current.lines.push(line);
+        }
+        else if (line.trim()) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'unexpected content before the first Grok Build CLI export heading');
+        }
+    }
+    flush();
+    return blocks;
+}
+function parseTools(text, blockSequence) {
+    const lines = text.split('\n').filter((line) => line.trim());
+    if (lines.length === 0 || lines.length > 1_000) {
+        throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build tools block has no summaries or exceeds 1,000 summaries');
+    }
+    return lines.map((line, index) => {
+        const match = /^- (.+)$/.exec(line);
+        if (!match) {
+            throw new SessionContractError('SCHEMA_DRIFT', `unrecognized Grok Build tool summary: ${line}`);
+        }
+        const summary = match[1];
+        const name = summary.split(/:| \(/, 1)[0]?.trim();
+        if (!name) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'empty Grok Build tool summary');
+        }
+        return { sequence: blockSequence * 1_000 + index, name, text: summary };
+    });
+}
+function provenance(source, sessionId, heading) {
+    return {
+        lifecycle: 'unknown-at-import',
+        provenance: {
+            product: 'grok-build',
+            acquisition: 'grok-cli-export-markdown',
+            exportCommand: `grok export ${sessionId} ${sessionId}.md`,
+            sourceSchema: GROK_BUILD_CLI_EXPORT_SCHEMA_VERSION,
+            heading,
+            nativeStoreInspected: false,
+            originalFilename: basename(source.locator),
+        },
+        identity: {
+            nativeSessionIdKnown: true,
+            nativeEventIdKnown: false,
+        },
+        lossReport: {
+            lossless: false,
+            unavailableInCliExport: [
+                'timestamps', 'model', 'grokVersion', 'workingDirectory', 'toolResults',
+                'attachments', 'fileSnapshots', 'compaction', 'lineage', 'subagents',
+            ],
+        },
+    };
+}
+function parseCursor(value) {
+    if (!value)
+        return 0;
+    if (!/^\d+$/.test(value)) {
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Grok Build export cursor');
+    }
+    const cursor = Number(value);
+    if (!Number.isSafeInteger(cursor)) {
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Grok Build export cursor');
+    }
+    return cursor;
+}
+//# sourceMappingURL=grok-build.js.map

package/dist/src/sessions/adapters/muse.js

@@ -0,0 +1,412 @@
+/**
+ * Muse Code session adapter — manual export only, trajectory-first.
+ *
+ * Muse Code journals model calls, tool runs, and approvals to an append-only
+ * session log and projects it into a self-contained JSON document via
+ * `muse export` (also surfaced as `/export trajectory`). The adapter ingests
+ * ONLY those explicit operator-supplied export documents, gated on the
+ * document's `export_schema_version` major (currently `1`); unknown majors
+ * fail closed with `UNKNOWN_SCHEMA_MAJOR`, as with peer native-export
+ * adapters.
+ *
+ * Auto-discovery is unsupported and must never scrape home directories or
+ * invent session roots. The documented candidate native root
+ * (`$XDG_DATA_HOME/muse/sessions/YYYY/MM/DD/<session-id>/session.jsonl`,
+ * default `~/.local/share/muse/sessions`) is NOT authorized or implemented
+ * here; a future evidence-gated `--muse-root` discover path remains the
+ * route to native discovery (#222 PR B).
+ *
+ * Trajectory shape follows the documented export format at
+ * https://dev.meta.ai/docs/cookbook/audit-agent-sessions: top-level
+ * `export_schema_version`, `redaction`, `exporter_version`, `session_build`,
+ * `session_terminated_abnormally`, per-stream `sessions` summaries, ordered
+ * `events` elements with `envelope`/`payload`, and `diagnostics` counters.
+ * Approval, tool, and model-lifecycle facts are preserved with provenance
+ * under `extensions['native.muse']`.
+ *
+ * Live-evidence notes (real `muse export`, Muse Code 1.3.0, build
+ * `3c572bc734`, 2026-09-24): the document carries exactly one `sessions[]`
+ * summary per exported parent session; subagents appear only inside
+ * `sessions[0].accepted_spawns[]` as spawn handles, never as extra summaries.
+ * Every merged record event carries its own `envelope.stream.id` (always the
+ * parent here), so attribution reads the envelope per event. Subagent tool
+ * runs are NOT merged — they live in `subagent/<child_session_id>/session.jsonl`
+ * under their own stream id; only `subagent.control.*` records (26 in the
+ * probe) are merged, linked via `child_session_bound.child_session_id` /
+ * `start_attested.subagent_session_id`. CRITICAL: `subagent_id` (spawn handle)
+ * and `child_session_id` (child session/dir identity) are distinct values and
+ * must never be conflated. Gap markers carry `"envelope": null` and are
+ * skipped, never fabricated into records.
+ *
+ * @see docs/providers/muse-sessions.md
+ * @issue #232
+ */
+import { z } from 'zod';
+import { SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
+import { readBoundedJson } from '../readers.js';
+export const MUSE_ADAPTER_VERSION = '1.0.0';
+export const MUSE_EXPORT_SCHEMA_VERSION = '1.0.0';
+export const MUSE_EXPORT_SCHEMA_MAJOR = 1;
+export const MUSE_LOCATOR_CLASS = 'manual-export';
+const Rfc3339Schema = z.string().refine((value) => /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value)
+    && !Number.isNaN(Date.parse(value)), 'timestamp must be RFC 3339 with an explicit UTC offset');
+/**
+ * One log line projected by `muse export`. Per the documented format, each
+ * record element is an envelope `{sequence, recorded_at, record_type,
+ * durability, payload_type, payload}`; the interesting content is
+ * `payload.event.kind` (a task-lifecycle or runtime event) or `payload_type`
+ * (a stream fact). Live exports (Muse Code 1.3.0) also carry `id`,
+ * `causation_id`, `schema_version`, `payload_schema_version`, and a
+ * `stream: {kind, id}` block on every record envelope; gap markers carry
+ * `"envelope": null` instead.
+ */
+const MuseStreamSchema = z.object({
+    kind: z.string().optional(),
+    id: z.string().optional(),
+}).passthrough();
+const MuseEnvelopeSchema = z.object({
+    sequence: z.number().int().nonnegative(),
+    id: z.string().optional(),
+    causation_id: z.string().nullish(),
+    schema_version: z.union([z.number(), z.string()]).optional(),
+    payload_schema_version: z.union([z.number(), z.string()]).optional(),
+    stream: MuseStreamSchema.optional(),
+    // Muse Code 1.4.0 exports epoch microseconds; RFC 3339 strings stay valid.
+    recorded_at: z.union([z.string(), z.number().int().nonnegative()]).optional(),
+    record_type: z.string().optional(),
+    durability: z.string().optional(),
+    payload_type: z.string().optional(),
+    payload: z.object({
+        event: z.object({ kind: z.string().min(1) }).passthrough().optional(),
+    }).passthrough().optional(),
+}).passthrough();
+/**
+ * Record events carry a record envelope, validated strictly. Every other
+ * event kind is an audit marker: `gap` carries `"envelope": null`, and
+ * `retained_frame` (Muse Code 1.4.0) carries a transaction frame
+ * (`children`, `transaction_id`, `content_sha256`) instead of a record.
+ * Markers are never fabricated into provider records.
+ */
+const MuseRecordEventSchema = z.object({
+    kind: z.literal('record'),
+    envelope: MuseEnvelopeSchema,
+}).passthrough();
+const MuseMarkerEventSchema = z.object({
+    kind: z.string().min(1).refine((kind) => kind !== 'record'),
+    envelope: z.record(z.string(), z.unknown()).nullish(),
+}).passthrough();
+const MuseExportEventSchema = z.union([MuseRecordEventSchema, MuseMarkerEventSchema]);
+const MuseAcceptedSpawnSchema = z.object({
+    subagent_id: z.string().optional(),
+    agent_path: z.string().optional(),
+    role: z.string().optional(),
+    parent_session_id: z.string().optional(),
+}).passthrough();
+const MuseSessionSummarySchema = z.object({
+    session_id: z.string().min(1),
+    turn_count: z.number().int().nonnegative().optional(),
+    step_count: z.number().int().nonnegative().optional(),
+    // Live evidence: one summary per exported parent session; subagents appear
+    // only here, as spawn handles (subagent_id), never as extra summaries.
+    accepted_spawns: z.array(MuseAcceptedSpawnSchema).optional(),
+    session_end: z.object({
+        exit_reason: z.string().optional(),
+        uptime_ms: z.number().nonnegative().optional(),
+    }).passthrough().optional(),
+}).passthrough();
+const MuseDiagnosticsSchema = z.object({
+    unparseable_lines: z.number().int().nonnegative().optional(),
+    unknown_payload_kinds: z.number().int().nonnegative().optional(),
+    gaps: z.number().int().nonnegative().optional(),
+    omitted_live_only: z.number().int().nonnegative().optional(),
+    duplicate_records: z.number().int().nonnegative().optional(),
+}).passthrough();
+const MuseTrajectorySchema = z.object({
+    export_schema_version: z.number().int().nonnegative(),
+    redaction: z.string().optional(),
+    exporter_version: z.object({ display: z.string() }).passthrough().optional(),
+    session_build: z.object({ display: z.string() }).passthrough().optional(),
+    session_terminated_abnormally: z.boolean().optional(),
+    sessions: z.array(MuseSessionSummarySchema).min(1),
+    events: z.array(MuseExportEventSchema),
+    diagnostics: MuseDiagnosticsSchema.optional(),
+}).passthrough();
+function isRecordEvent(event) {
+    return event.kind === 'record';
+}
+export class MuseSessionAdapter {
+    limits;
+    provider = 'muse';
+    adapterVersion = MUSE_ADAPTER_VERSION;
+    disposition = 'manual-only';
+    supportedOperations = ['inspect', 'stream'];
+    acquisitionModes = ['manual-export'];
+    constructor(limits) {
+        this.limits = limits;
+    }
+    async *discover(_scope) {
+        throw new SessionContractError('UNSUPPORTED_OPERATION', 'Muse Code session auto-discover is unsupported: the native log under '
+            + '$XDG_DATA_HOME/muse/sessions uses an internal format. Run `muse export --session '
+            + '<id-or-session.jsonl>` and select that trajectory file. AIWG does not scrape home '
+            + 'directories for this provider.');
+    }
+    async inspect(source) {
+        this.assertManualExport(source);
+        const { trajectory } = await this.readTrajectory(source);
+        for (const event of trajectory.events)
+            this.parseEvent(event);
+        return {
+            sourceSchemaVersion: MUSE_EXPORT_SCHEMA_VERSION,
+            consistency: trajectory.session_terminated_abnormally === false ? 'complete' : 'provisional',
+            operationalState: 'available',
+        };
+    }
+    async *stream(source, cursor) {
+        this.assertManualExport(source);
+        const { trajectory, bytesRead } = await this.readTrajectory(source);
+        const start = parseEventCursor(cursor?.value);
+        const spawns = acceptedSpawnsById(trajectory);
+        let index = 0;
+        for (const event of trajectory.events) {
+            // Cursor positions are raw event positions so resume stays aligned
+            // even when gap markers are skipped.
+            const position = index;
+            index += 1;
+            if (position < start)
+                continue;
+            // Gap/retained-frame markers carry no record payload: skip them, never
+            // fabricate a ProviderRecord for one.
+            if (!isRecordEvent(event))
+                continue;
+            yield this.toProviderRecord(trajectory, bytesRead, event.envelope, spawns, event, position);
+        }
+    }
+    async readTrajectory(source) {
+        let value;
+        let bytesRead;
+        try {
+            ({ value, bytesRead } = await readBoundedJson({ selectedPath: source.locator, allowedRoots: source.authorizedScope.allowedRoots }, this.limits));
+        }
+        catch (error) {
+            if (error instanceof SessionContractError && error.code === 'SCHEMA_DRIFT') {
+                throw new SessionContractError('MALFORMED_SOURCE', 'muse export document is not valid JSON');
+            }
+            throw error;
+        }
+        const parsed = MuseTrajectorySchema.safeParse(value);
+        if (!parsed.success) {
+            throw new SessionContractError('MALFORMED_SOURCE', 'input is not a declared muse export trajectory document');
+        }
+        assertSupportedSchemaMajor(`${parsed.data.export_schema_version}.0.0`, MUSE_EXPORT_SCHEMA_MAJOR);
+        return { trajectory: parsed.data, bytesRead };
+    }
+    parseEvent(event) {
+        eventKindOf(event);
+    }
+    toProviderRecord(trajectory, bytesRead, envelope, spawns, event, index) {
+        // Attribute by the event's own stream id; fall back to the document's
+        // first session summary only when the stream block is absent. Live
+        // evidence (Muse Code 1.3.0) shows merged events always carry the parent
+        // id here, so never assume sessions[0] without reading the envelope.
+        const nativeSessionId = streamSessionIdOf(envelope) ?? trajectory.sessions[0].session_id;
+        const payload = envelope.payload ?? {};
+        const payloadRecord = payload;
+        const eventKind = eventKindOf(event);
+        const toolName = toolNameOf(payloadRecord);
+        const policyDecision = stringField(payloadRecord, 'policy_decision');
+        const operation = stringField(payloadRecord, 'operation');
+        const decision = stringField(payloadRecord, 'decision');
+        const approvalOutcome = stringField(payloadRecord, 'outcome');
+        const decisionSource = objectField(payloadRecord, 'decision_source');
+        const linkage = subagentLinkageOf(payloadRecord);
+        const spawnContext = spawnContextOf(spawns, envelope.payload_type, linkage.subagentId);
+        return {
+            nativeSessionId,
+            nativeEventId: `muse-seq-${envelope.sequence}`,
+            sequence: index,
+            kind: eventKind,
+            role: undefined,
+            participant: undefined,
+            toolName: toolName ?? undefined,
+            toolCallId: undefined,
+            model: undefined,
+            entities: [],
+            occurredAt: occurredAtOf(envelope.recorded_at) ?? undefined,
+            text: describeEvent(eventKind, envelope.sequence, {
+                operation, policyDecision, decision, approvalOutcome, decisionSource,
+            }),
+            rawReference: { locatorClass: MUSE_LOCATOR_CLASS, sequence: index },
+            sourceCursor: String(index + 1),
+            sourceBytes: bytesRead,
+            extensions: {
+                'native.muse': compactObject({
+                    eventKind,
+                    recordType: event.kind,
+                    payloadType: envelope.payload_type,
+                    durability: envelope.durability,
+                    streamKind: envelope.stream?.kind,
+                    streamId: streamSessionIdOf(envelope),
+                    envelopeSequence: envelope.sequence,
+                    envelopeId: envelope.id,
+                    causationId: envelope.causation_id,
+                    exportSchemaVersion: trajectory.export_schema_version,
+                    redaction: trajectory.redaction,
+                    exporterVersion: trajectory.exporter_version?.display,
+                    sessionBuild: trajectory.session_build?.display,
+                    terminatedAbnormally: trajectory.session_terminated_abnormally,
+                    operation,
+                    policyDecision,
+                    decision,
+                    decisionSource,
+                    approvalOutcome,
+                    ...linkage,
+                    ...spawnContext,
+                    diagnostics: trajectory.diagnostics,
+                }),
+            },
+        };
+    }
+    assertManualExport(source) {
+        if (source.locatorClass !== MUSE_LOCATOR_CLASS) {
+            throw new SessionContractError('UNSUPPORTED_OPERATION', `Muse Code supports only locatorClass "${MUSE_LOCATOR_CLASS}" because its native log format is internal `
+                + `(got "${source.locatorClass}"). Select an explicit \`muse export\` trajectory file.`);
+        }
+    }
+}
+/**
+ * Effective event kind per the documented jq projection:
+ * `payload.event.kind`, falling back to `payload_type` (a stream fact such
+ * as `approval_wait.effect.started`). Gap/retained-frame markers have no
+ * envelope, so fall back to the marker kind (e.g. `gap`).
+ */
+function eventKindOf(event) {
+    if (!isRecordEvent(event))
+        return event.kind;
+    const envelope = event.envelope;
+    const payload = envelope.payload;
+    const eventKind = payload?.event?.kind;
+    if (typeof eventKind === 'string' && eventKind.length > 0)
+        return eventKind;
+    const payloadType = envelope.payload_type;
+    if (typeof payloadType === 'string' && payloadType.length > 0)
+        return payloadType;
+    return event.kind;
+}
+/**
+ * Per-event stream session id from the envelope. Live evidence (Muse Code
+ * 1.3.0) shows this is always the exported parent session id for merged
+ * record events; subagent tool runs are not merged at all.
+ */
+function streamSessionIdOf(envelope) {
+    const streamId = envelope.stream?.id;
+    return typeof streamId === 'string' && streamId.length > 0 ? streamId : null;
+}
+/**
+ * Spawn handles from `sessions[0].accepted_spawns[]`, keyed by subagent_id.
+ * These are the spawn-side keys for joining merged control-plane records to
+ * child sessions; they are NOT child session ids.
+ */
+function acceptedSpawnsById(trajectory) {
+    const spawns = new Map();
+    for (const spawn of trajectory.sessions[0].accepted_spawns ?? []) {
+        if (typeof spawn.subagent_id === 'string' && spawn.subagent_id.length > 0) {
+            spawns.set(spawn.subagent_id, { agentPath: spawn.agent_path, role: spawn.role });
+        }
+    }
+    return spawns;
+}
+/**
+ * Subagent spawn/child linkage from control-plane payloads. CRITICAL: live
+ * evidence (Muse Code 1.3.0) shows `subagent_id` is the spawn handle while
+ * `child_session_id` (from `child_session_bound`) and `subagent_session_id`
+ * (from `start_attested`) are the child session identity — distinct values,
+ * also naming the `subagent/<child-id>/session.jsonl` directories. Never
+ * conflate the two.
+ */
+function subagentLinkageOf(payload) {
+    const record = objectField(payload, 'record');
+    const event = objectField(payload, 'event');
+    return compactObject({
+        subagentId: record ? stringField(record, 'subagent_id') ?? undefined : undefined,
+        childSessionId: record ? stringField(record, 'child_session_id') ?? undefined : undefined,
+        subagentSessionId: record ? stringField(record, 'subagent_session_id') ?? undefined : undefined,
+        eventChildSessionId: event ? stringField(event, 'child_session_id') ?? undefined : undefined,
+        sourceSessionId: stringField(payload, 'source_session_id') ?? undefined,
+    });
+}
+/**
+ * Human context for a merged subagent control-plane record, joined against
+ * the document's accepted spawns. The join key is the spawn handle
+ * (subagent_id); the child session id stays separate.
+ */
+function spawnContextOf(spawns, payloadType, subagentId) {
+    if (payloadType == null || !payloadType.startsWith('subagent.control.'))
+        return {};
+    if (subagentId == null)
+        return {};
+    const spawn = spawns.get(subagentId);
+    if (!spawn)
+        return {};
+    return compactObject({ spawnAgentPath: spawn.agentPath, spawnRole: spawn.role });
+}
+/**
+ * `side_effect_intent` carries `operation: tool:<name>` (documented as
+ * `operation: tool:bash`); extract the tool name only from that documented
+ * shape.
+ */
+function toolNameOf(payload) {
+    const operation = stringField(payload, 'operation');
+    if (!operation)
+        return null;
+    const match = /^tool:(.+)$/.exec(operation);
+    return match ? match[1] : null;
+}
+function stringField(payload, key) {
+    const value = payload[key];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function objectField(payload, key) {
+    const value = payload[key];
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function occurredAtOf(recordedAt) {
+    if (typeof recordedAt === 'number') {
+        // Epoch microseconds (Muse Code 1.4.0 export and native log).
+        const date = new Date(Math.floor(recordedAt / 1000));
+        return Number.isNaN(date.getTime()) ? null : date.toISOString();
+    }
+    if (!recordedAt)
+        return null;
+    return Rfc3339Schema.safeParse(recordedAt).success ? recordedAt : null;
+}
+function describeEvent(eventKind, sequence, provenance) {
+    const parts = [`muse export trajectory event ${eventKind} (sequence ${sequence})`];
+    if (provenance.operation)
+        parts.push(`operation=${provenance.operation}`);
+    if (provenance.policyDecision)
+        parts.push(`policy_decision=${provenance.policyDecision}`);
+    if (provenance.decision)
+        parts.push(`decision=${provenance.decision}`);
+    if (provenance.decisionSource) {
+        const sourceKind = provenance.decisionSource.kind;
+        if (typeof sourceKind === 'string' && sourceKind.length > 0) {
+            parts.push(`decision_source=${sourceKind}`);
+        }
+    }
+    if (provenance.approvalOutcome)
+        parts.push(`outcome=${provenance.approvalOutcome}`);
+    return parts.join(' ');
+}
+function compactObject(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined && entry !== null));
+}
+function parseEventCursor(value) {
+    if (value === undefined || value === '')
+        return 0;
+    if (!/^\d+$/.test(value))
+        throw new SessionContractError('SCHEMA_DRIFT', 'muse event cursor is invalid');
+    return Number(value);
+}
+//# sourceMappingURL=muse.js.map

package/dist/src/sessions/contracts.js

@@ -3,7 +3,7 @@ import { z } from 'zod';
 export const SESSION_CONTRACT_VERSION = '1.0.0';
 export const SESSION_PROVIDER_IDS = [
     'claude', 'codex', 'copilot', 'cursor', 'factory', 'hermes',
-    'opencode', 'openclaw', 'openhuman', 'grokbot', 'pi', 'omp', 'deepseek-harness', 'warp', 'devin-desktop', 'generic',
+    'opencode', 'openclaw', 'openhuman', 'grokbot', 'grok-build', 'pi', 'omp', 'deepseek-harness', 'warp', 'devin-desktop', 'muse', 'generic',
 ];
 export const SessionProviderIdSchema = z.enum(SESSION_PROVIDER_IDS);
 export const SESSION_PROVIDER_ALIASES = Object.freeze({