@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/runtime/tasks/types.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Task manager types — public interfaces for creating, updating, and
+ * managing RuntimeTask lifecycle through the UnifiedTaskManager.
+ */
+import type { TaskKind, TaskLifecycleState, TaskRetryPolicy, RuntimeTask } from '../store/domains/tasks.js';
+/**
+ * Parameters accepted by `TaskManager.createTask()` to create a new task.
+ *
+ * Required fields: `kind`, `title`, `owner`.
+ * All other fields are optional and have sensible defaults.
+ */
+export interface TaskCreateParams {
+    /** Task kind from the runtime task taxonomy. */
+    kind: TaskKind;
+    /** Human-readable title for display in the task monitor. */
+    title: string;
+    /** Subsystem or agent ID that owns this task. */
+    owner: string;
+    /** Optional detailed description. */
+    description?: string;
+    /** Parent task ID if this is a subtask. */
+    parentTaskId?: string;
+    /** Whether this task can be cancelled by the user. Defaults to `true`. */
+    cancellable?: boolean;
+    /** Retry policy (undefined = no retries). */
+    retryPolicy?: TaskRetryPolicy;
+    /** Correlation ID for distributed tracing. */
+    correlationId?: string;
+    /** Turn ID this task was spawned within. */
+    turnId?: string;
+}
+/**
+ * Parameters accepted by `TaskManager.updateTask()` to patch mutable
+ * fields on an existing task without triggering a lifecycle transition.
+ *
+ * Status transitions MUST go through the dedicated transition methods
+ * (`startTask`, `completeTask`, `failTask`, etc.) to enforce invariants.
+ */
+export interface TaskUpdateParams {
+    /** Updated human-readable title. */
+    title?: string;
+    /** Updated description. */
+    description?: string;
+    /** Updated exit code (exec tasks). */
+    exitCode?: number;
+    /** Updated result payload. */
+    result?: unknown;
+}
+/**
+ * Parameters accepted by `TaskManager.cancelTask()`.
+ */
+export interface TaskCancelParams {
+    /** Human-readable reason for cancellation. */
+    reason?: string;
+}
+/**
+ * Parameters accepted by `TaskManager.failTask()`.
+ */
+export interface TaskFailParams {
+    /** Error message describing the failure. */
+    error: string;
+    /** Exit code if applicable (exec tasks). */
+    exitCode?: number;
+}
+/**
+ * TaskManager — the public interface for the unified task management system.
+ *
+ * All task lifecycle transitions and mutations go through this interface.
+ * Implementations MUST:
+ * - Enforce lifecycle invariants (reject invalid transitions)
+ * - Emit TaskEvents via RuntimeEventBus at each transition
+ * - Update RuntimeState.tasks domain via store dispatch
+ * - Track parent/child relationships
+ * - Support retry policies (re-queue on failure when policy allows)
+ */
+export interface TaskManager {
+    /**
+     * Creates a new task in the 'queued' state and registers it in the store.
+     *
+     * @param params - Task creation parameters.
+     * @returns The created RuntimeTask.
+     */
+    createTask(params: TaskCreateParams): RuntimeTask;
+    /**
+     * Transitions a task from 'queued' to 'running'.
+     *
+     * @param taskId - The task to start.
+     * @returns The updated RuntimeTask.
+     * @throws If the task does not exist or cannot transition to 'running'.
+     */
+    startTask(taskId: string): RuntimeTask;
+    /**
+     * Transitions a task to 'blocked' (waiting on a dependency or resource).
+     *
+     * @param taskId - The task to block.
+     * @param reason - Human-readable reason for the block.
+     * @returns The updated RuntimeTask.
+     * @throws If the task does not exist or cannot transition to 'blocked'.
+     */
+    blockTask(taskId: string, reason: string): RuntimeTask;
+    /**
+     * Transitions a task to 'completed'.
+     *
+     * @param taskId - The task to complete.
+     * @param result - Optional result payload.
+     * @returns The updated RuntimeTask.
+     * @throws If the task does not exist or cannot transition to 'completed'.
+     */
+    completeTask(taskId: string, result?: unknown): RuntimeTask;
+    /**
+     * Transitions a task to 'failed'. If the task has a retry policy with
+     * remaining attempts, re-queues the task instead.
+     *
+     * @param taskId - The task that failed.
+     * @param params - Failure details.
+     * @returns The updated RuntimeTask (may be back in 'queued' if retried).
+     * @throws If the task does not exist or cannot transition to 'failed'.
+     */
+    failTask(taskId: string, params: TaskFailParams): RuntimeTask;
+    /**
+     * Transitions a task to 'cancelled'.
+     *
+     * @param taskId - The task to cancel.
+     * @param params - Optional cancellation context.
+     * @returns The updated RuntimeTask.
+     * @throws If the task does not exist, is not cancellable, or cannot
+     *   transition to 'cancelled'.
+     */
+    cancelTask(taskId: string, params?: TaskCancelParams): RuntimeTask;
+    /**
+     * Applies a partial update to mutable fields of an existing task.
+     * Does NOT trigger a lifecycle transition or emit a transition event.
+     *
+     * @param taskId - The task to update.
+     * @param params - Fields to update.
+     * @returns The updated RuntimeTask.
+     * @throws If the task does not exist.
+     */
+    updateTask(taskId: string, params: TaskUpdateParams): RuntimeTask;
+    /**
+     * Retrieves a task by ID from the registry.
+     *
+     * @param taskId - The task ID to look up.
+     * @returns The RuntimeTask if found, or `undefined`.
+     */
+    getTask(taskId: string): RuntimeTask | undefined;
+    /**
+     * Returns all tasks of a given kind.
+     *
+     * @param kind - The TaskKind to filter by.
+     */
+    getTasksByKind(kind: TaskKind): RuntimeTask[];
+    /**
+     * Returns all currently running tasks.
+     */
+    getRunningTasks(): RuntimeTask[];
+    /**
+     * Returns the count of running tasks for a given kind.
+     * Used for per-kind concurrency tracking.
+     *
+     * @param kind - The TaskKind to count.
+     */
+    getRunningCount(kind: TaskKind): number;
+    /**
+     * Returns all child tasks of a given parent task.
+     *
+     * @param parentTaskId - The parent task ID.
+     */
+    getChildTasks(parentTaskId: string): RuntimeTask[];
+    /**
+     * Returns the current TaskLifecycleState of a task.
+     *
+     * @param taskId - The task ID to query.
+     * @returns The current status, or `undefined` if the task does not exist.
+     */
+    getTaskStatus(taskId: string): TaskLifecycleState | undefined;
+    /**
+     * Re-queues a failed or cancelled task for execution.
+     *
+     * Transitions the task back to 'queued', clearing terminal-state fields
+     * (error, exitCode, endedAt, startedAt). Only valid from 'failed' or
+     * 'cancelled' states.
+     *
+     * @param taskId - The task to retry.
+     * @returns The updated RuntimeTask in 'queued' state.
+     * @throws If the task does not exist or is not in a retryable state.
+     */
+    retryTask(taskId: string): RuntimeTask;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/_internal/platform/runtime/tasks/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/tasks/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAM5G;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,IAAI,EAAE,QAAQ,CAAC;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,WAAW,CAAC;IAElD;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC;IAEvC;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC;IAEvD;;;;;;;OAOG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IAE5D;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,WAAW,CAAC;IAE9D;;;;;;;;OAQG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,WAAW,CAAC;IAEnE;;;;;;;;OAQG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,WAAW,CAAC;IAElE;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IAEjD;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,WAAW,EAAE,CAAC;IAE9C;;OAEG;IACH,eAAe,IAAI,WAAW,EAAE,CAAC;IAEjC;;;;;OAKG;IACH,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IAExC;;;;OAIG;IACH,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IAEnD;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAC;IAE9D;;;;;;;;;;OAUG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC;CACxC"}

package/dist/_internal/platform/runtime/tasks/types.js

@@ -0,0 +1 @@
+export {};

package/dist/_internal/platform/runtime/telemetry/exporters/console.d.ts

@@ -0,0 +1,41 @@
+/**
+ * ConsoleExporter — development-mode span exporter.
+ *
+ * Writes formatted span summaries to stderr. Intended for local development
+ * and debugging — should not be used in production.
+ */
+import type { ReadableSpan, SpanExporter } from '../types.js';
+/** Verbosity level for console output. */
+export type ConsoleVerbosity = 'minimal' | 'standard' | 'verbose';
+/** Configuration for ConsoleExporter. */
+export interface ConsoleExporterConfig {
+    /**
+     * How much detail to include per span.
+     * - `minimal` — span name + status + duration only.
+     * - `standard` — adds attributes (default).
+     * - `verbose` — adds events and full attribute values.
+     */
+    readonly verbosity?: ConsoleVerbosity;
+}
+/**
+ * ConsoleExporter — prints span data to stderr for development.
+ *
+ * Usage:
+ * ```ts
+ * const exporter = new ConsoleExporter({ verbosity: 'standard' });
+ * ```
+ */
+export declare class ConsoleExporter implements SpanExporter {
+    readonly name = "console";
+    private readonly verbosity;
+    constructor(config?: ConsoleExporterConfig);
+    /** Export spans by printing formatted summaries to stderr. */
+    export(spans: ReadableSpan[]): Promise<void>;
+    /** Flush is a no-op for synchronous stderr writes. */
+    flush(): Promise<void>;
+    /** Shutdown is a no-op. */
+    shutdown(): Promise<void>;
+    /** Format a single span for console output. */
+    private _format;
+}
+//# sourceMappingURL=console.d.ts.map

package/dist/_internal/platform/runtime/telemetry/exporters/console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/telemetry/exporters/console.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG9D,0CAA0C;AAC1C,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAElE,yCAAyC;AACzC,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,qBAAa,eAAgB,YAAW,YAAY;IAClD,QAAQ,CAAC,IAAI,aAAa;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;gBAEjC,MAAM,GAAE,qBAA0B;IAI9C,8DAA8D;IACxD,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlD,sDAAsD;IAChD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,2BAA2B;IACrB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B,+CAA+C;IAC/C,OAAO,CAAC,OAAO;CAoDhB"}

package/dist/_internal/platform/runtime/telemetry/exporters/console.js

@@ -0,0 +1,76 @@
+import { SpanStatusCode } from '../types.js';
+/**
+ * ConsoleExporter — prints span data to stderr for development.
+ *
+ * Usage:
+ * ```ts
+ * const exporter = new ConsoleExporter({ verbosity: 'standard' });
+ * ```
+ */
+export class ConsoleExporter {
+    name = 'console';
+    verbosity;
+    constructor(config = {}) {
+        this.verbosity = config.verbosity ?? 'standard';
+    }
+    /** Export spans by printing formatted summaries to stderr. */
+    async export(spans) {
+        for (const span of spans) {
+            try {
+                process.stderr.write(this._format(span) + '\n');
+            }
+            catch {
+                // Writing to stderr should not throw but swallow any OS-level errors.
+            }
+        }
+    }
+    /** Flush is a no-op for synchronous stderr writes. */
+    async flush() {
+        // Nothing buffered.
+    }
+    /** Shutdown is a no-op. */
+    async shutdown() {
+        // Nothing to tear down.
+    }
+    /** Format a single span for console output. */
+    _format(span) {
+        const status = span.status.code === SpanStatusCode.ERROR
+            ? 'ERROR'
+            : span.status.code === SpanStatusCode.OK
+                ? 'OK'
+                : 'UNSET';
+        const base = `[otel] ${span.name} | ${status} | ${span.durationMs}ms` +
+            ` | trace=${span.spanContext.traceId.slice(0, 8)} span=${span.spanContext.spanId.slice(0, 8)}`;
+        if (this.verbosity === 'minimal') {
+            return base;
+        }
+        const attrEntries = Object.entries(span.attributes);
+        const attrStr = attrEntries.length === 0
+            ? ''
+            : '\n  attrs: ' +
+                attrEntries
+                    .map(([k, v]) => {
+                    const val = this.verbosity === 'verbose'
+                        ? JSON.stringify(v)
+                        : typeof v === 'string' && v.length > 64
+                            ? JSON.stringify(v.slice(0, 64) + '...')
+                            : JSON.stringify(v);
+                    return `${k}=${val}`;
+                })
+                    .join(' ');
+        if (this.verbosity === 'standard') {
+            return base + attrStr;
+        }
+        // verbose — include events
+        const eventsStr = span.events.length === 0
+            ? ''
+            : '\n  events: ' +
+                span.events
+                    .map((e) => `${e.name}@${e.timestamp}`)
+                    .join(', ');
+        if (span.status.message) {
+            return base + attrStr + eventsStr + `\n  message: ${span.status.message}`;
+        }
+        return base + attrStr + eventsStr;
+    }
+}

package/dist/_internal/platform/runtime/telemetry/exporters/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Barrel export for telemetry exporters.
+ */
+export type { LocalLedgerConfig } from './local-ledger.js';
+export { LocalLedgerExporter } from './local-ledger.js';
+export type { ConsoleVerbosity, ConsoleExporterConfig } from './console.js';
+export { ConsoleExporter } from './console.js';
+export type { RetryConfig, ExportQueueConfig, ExportResultCode, ExportResult, OtlpConfig, ExportFn, ExportResultCallback, } from './types.js';
+export { DEFAULT_RETRY_CONFIG, DEFAULT_QUEUE_CONFIG, DEFAULT_OTLP_CONFIG, } from './types.js';
+export { ExportQueue } from './queue.js';
+export { OtlpExporter } from './otlp.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/runtime/telemetry/exporters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/telemetry/exporters/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,YAAY,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC"}

package/dist/_internal/platform/runtime/telemetry/exporters/index.js

@@ -0,0 +1,5 @@
+export { LocalLedgerExporter } from './local-ledger.js';
+export { ConsoleExporter } from './console.js';
+export { DEFAULT_RETRY_CONFIG, DEFAULT_QUEUE_CONFIG, DEFAULT_OTLP_CONFIG, } from './types.js';
+export { ExportQueue } from './queue.js';
+export { OtlpExporter } from './otlp.js';

package/dist/_internal/platform/runtime/telemetry/exporters/local-ledger.d.ts

@@ -0,0 +1,105 @@
+import type { ReadableSpan, SpanExporter } from '../types.js';
+/** Configuration for LocalLedgerExporter. */
+export interface LocalLedgerConfig {
+    /**
+     * Absolute path to the output file (e.g. `/home/user/.goodvibes/telemetry/spans.jsonl`).
+     */
+    readonly filePath: string;
+    /**
+     * Maximum file size in bytes before rotation.
+     * When the file exceeds this size, it is renamed to `<filePath>.1` and a
+     * fresh file is started. Defaults to 10 MB.
+     */
+    readonly maxFileSizeBytes?: number;
+    /**
+     * Optional path for the typed event ledger file.
+     * When provided, `recordEvent()` appends `LedgerEntry` lines here.
+     * Defaults to `<filePath>.ledger.jsonl`.
+     */
+    readonly ledgerFilePath?: string;
+}
+/**
+ * A single typed event entry in the replay ledger.
+ *
+ * Each entry captures the run identifier, a monotonically increasing
+ * revision counter, the event name, payload, and wall-clock timestamp.
+ * The revision counter is used by the deterministic replay engine for
+ * seek and stepwise playback.
+ */
+export interface LedgerEntry {
+    /** Run identifier — groups entries belonging to the same recorded run. */
+    readonly runId: string;
+    /** Monotonically increasing revision counter within the run (starts at 1). */
+    readonly rev: number;
+    /** Event name recorded in the typed runtime ledger. */
+    readonly eventName: string;
+    /** Full event payload, JSON-serialisable. */
+    readonly payload: unknown;
+    /** Wall-clock timestamp (epoch ms) when the event was recorded. */
+    readonly ts: number;
+}
+/**
+ * LocalLedgerExporter — writes spans as JSON lines to a rotating file.
+ *
+ * Usage:
+ * ```ts
+ * const exporter = new LocalLedgerExporter({
+ *   filePath: '/home/user/.goodvibes/telemetry/spans.jsonl',
+ *   maxFileSizeBytes: 5 * 1024 * 1024,
+ * });
+ * ```
+ */
+export declare class LocalLedgerExporter implements SpanExporter {
+    readonly name = "local-ledger";
+    private readonly filePath;
+    private readonly maxFileSizeBytes;
+    private readonly ledgerFilePath;
+    constructor(config: LocalLedgerConfig);
+    /**
+     * Export a batch of spans as JSON lines (fire-and-forget).
+     *
+     * Intentionally not awaited by the tracer — failures are swallowed here
+     * and logged to avoid any runtime impact.
+     */
+    export(spans: ReadableSpan[]): Promise<void>;
+    /**
+     * Record a typed event entry to the ledger file (fire-and-forget).
+     *
+     * Used by the deterministic replay engine to build a per-run event log.
+     * Failures are logged but never thrown.
+     *
+     * @param entry - The ledger entry to append.
+     *
+     * @remarks
+     * This method is used by the event recording integration that
+     * wires typed runtime events to the ledger. The integration subscribes to the
+     * runtime bus at session start and calls `recordEvent()` for each event that should
+     * be included in the replay ledger. See `DeterministicReplayEngine.load()`
+     * for the consumer side of this pipeline.
+     */
+    recordEvent(entry: LedgerEntry): void;
+    /**
+     * Read all ledger entries for a given run.
+     *
+     * Parses the ledger file line-by-line. Malformed lines are skipped.
+     * Returns entries sorted by revision (ascending).
+     *
+     * @param runId - The run to retrieve entries for.
+     * @returns Ordered ledger entries for the run.
+     */
+    readRunEntries(runId: string): LedgerEntry[];
+    /**
+     * List all run IDs recorded in the ledger.
+     */
+    listRunIds(): string[];
+    /** Flush is a no-op for synchronous append-only writes. */
+    flush(): Promise<void>;
+    /** Shutdown is a no-op for file-based exports. */
+    shutdown(): Promise<void>;
+    /**
+     * Rotate the log file if it exceeds the configured maximum size.
+     * Renames the current file to `<filePath>.1` (overwrites any existing `.1`).
+     */
+    private _rotateIfNeeded;
+}
+//# sourceMappingURL=local-ledger.d.ts.map

package/dist/_internal/platform/runtime/telemetry/exporters/local-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-ledger.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/telemetry/exporters/local-ledger.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG9D,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAID;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,YAAW,YAAY;IACtD,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,MAAM,EAAE,iBAAiB;IAMrC;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BlD;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAUrC;;;;;;;;OAQG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE;IA4B5C;;OAEG;IACH,UAAU,IAAI,MAAM,EAAE;IA0BtB,2DAA2D;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,kDAAkD;IAC5C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B;;;OAGG;IACH,OAAO,CAAC,eAAe;CAYxB"}

package/dist/_internal/platform/runtime/telemetry/exporters/local-ledger.js

@@ -0,0 +1,185 @@
+/**
+ * LocalLedgerExporter — append-only JSON lines span exporter.
+ *
+ * Writes completed spans to a rotating JSON Lines (.jsonl) file.
+ * Writes are fire-and-forget (non-blocking). Export failures are
+ * logged but never thrown — they must not block the runtime.
+ *
+ * Also provides typed event ledger recording for deterministic replay.
+ * Call `recordEvent()` to append a `LedgerEntry` to the ledger file.
+ */
+import { appendFileSync, statSync, renameSync, writeFileSync, readFileSync, existsSync } from 'fs';
+import { logger } from '../../../utils/logger.js';
+import { summarizeError } from '../../../utils/error-display.js';
+const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024; // 10 MB
+/**
+ * LocalLedgerExporter — writes spans as JSON lines to a rotating file.
+ *
+ * Usage:
+ * ```ts
+ * const exporter = new LocalLedgerExporter({
+ *   filePath: '/home/user/.goodvibes/telemetry/spans.jsonl',
+ *   maxFileSizeBytes: 5 * 1024 * 1024,
+ * });
+ * ```
+ */
+export class LocalLedgerExporter {
+    name = 'local-ledger';
+    filePath;
+    maxFileSizeBytes;
+    ledgerFilePath;
+    constructor(config) {
+        this.filePath = config.filePath;
+        this.maxFileSizeBytes = config.maxFileSizeBytes ?? DEFAULT_MAX_FILE_SIZE;
+        this.ledgerFilePath = config.ledgerFilePath ?? `${config.filePath}.ledger.jsonl`;
+    }
+    /**
+     * Export a batch of spans as JSON lines (fire-and-forget).
+     *
+     * Intentionally not awaited by the tracer — failures are swallowed here
+     * and logged to avoid any runtime impact.
+     */
+    async export(spans) {
+        if (spans.length === 0)
+            return;
+        // Build the JSON lines payload synchronously (cheap, in-memory).
+        const lines = spans
+            .map((span) => {
+            try {
+                return JSON.stringify(span);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((line) => line !== null)
+            .join('\n') + '\n';
+        // All I/O in a microtask to keep the call non-blocking.
+        await Promise.resolve().then(() => {
+            try {
+                this._rotateIfNeeded();
+                appendFileSync(this.filePath, lines, 'utf8');
+            }
+            catch (err) {
+                logger.debug(`[local-ledger] export failed: ${summarizeError(err)}`);
+            }
+        });
+    }
+    /**
+     * Record a typed event entry to the ledger file (fire-and-forget).
+     *
+     * Used by the deterministic replay engine to build a per-run event log.
+     * Failures are logged but never thrown.
+     *
+     * @param entry - The ledger entry to append.
+     *
+     * @remarks
+     * This method is used by the event recording integration that
+     * wires typed runtime events to the ledger. The integration subscribes to the
+     * runtime bus at session start and calls `recordEvent()` for each event that should
+     * be included in the replay ledger. See `DeterministicReplayEngine.load()`
+     * for the consumer side of this pipeline.
+     */
+    recordEvent(entry) {
+        try {
+            const line = JSON.stringify(entry) + '\n';
+            appendFileSync(this.ledgerFilePath, line, 'utf8');
+        }
+        catch (err) {
+            // Non-fatal — ledger recording must not block the runtime.
+            logger.debug(`[local-ledger] ledger write failed: ${summarizeError(err)}`);
+        }
+    }
+    /**
+     * Read all ledger entries for a given run.
+     *
+     * Parses the ledger file line-by-line. Malformed lines are skipped.
+     * Returns entries sorted by revision (ascending).
+     *
+     * @param runId - The run to retrieve entries for.
+     * @returns Ordered ledger entries for the run.
+     */
+    readRunEntries(runId) {
+        if (!existsSync(this.ledgerFilePath))
+            return [];
+        const entries = [];
+        let raw;
+        try {
+            raw = readFileSync(this.ledgerFilePath, 'utf8');
+        }
+        catch (err) {
+            logger.debug(`[local-ledger] ledger read failed: ${summarizeError(err)}`);
+            return [];
+        }
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const entry = JSON.parse(line);
+                if (entry.runId === runId) {
+                    entries.push(entry);
+                }
+            }
+            catch {
+                // Skip malformed lines — ledger may have partial writes.
+            }
+        }
+        entries.sort((a, b) => a.rev - b.rev);
+        return entries;
+    }
+    /**
+     * List all run IDs recorded in the ledger.
+     */
+    listRunIds() {
+        if (!existsSync(this.ledgerFilePath))
+            return [];
+        let raw;
+        try {
+            raw = readFileSync(this.ledgerFilePath, 'utf8');
+        }
+        catch (err) {
+            logger.debug(`[local-ledger] ledger read failed: ${summarizeError(err)}`);
+            return [];
+        }
+        const seen = new Set();
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const entry = JSON.parse(line);
+                if (typeof entry.runId === 'string') {
+                    seen.add(entry.runId);
+                }
+            }
+            catch {
+                // Skip malformed lines.
+            }
+        }
+        return [...seen];
+    }
+    /** Flush is a no-op for synchronous append-only writes. */
+    async flush() {
+        // Nothing to flush — writes are synchronous via appendFileSync.
+    }
+    /** Shutdown is a no-op for file-based exports. */
+    async shutdown() {
+        // Nothing to tear down.
+    }
+    /**
+     * Rotate the log file if it exceeds the configured maximum size.
+     * Renames the current file to `<filePath>.1` (overwrites any existing `.1`).
+     */
+    _rotateIfNeeded() {
+        try {
+            const stat = statSync(this.filePath);
+            if (stat.size >= this.maxFileSizeBytes) {
+                renameSync(this.filePath, `${this.filePath}.1`);
+                writeFileSync(this.filePath, '', 'utf8');
+                logger.debug(`[local-ledger] rotated ${this.filePath}`);
+            }
+        }
+        catch {
+            // File may not exist yet — first write will create it via appendFileSync.
+        }
+    }
+}