@codebolt/narrative 1.11.0

package/dist/api/command.api.d.ts

@@ -0,0 +1,12 @@
+import { NarrativeTransport } from '../transport';
+import { ExecuteCommandParams, ExecuteCommandResult, PtyWriteParams, PtyWriteResult, PtyResizeParams, PtyResizeResult, PtyCloseParams, PtyCloseResult, PtySignalParams, PtySignalResult, ListSessionsResult } from '../types/command';
+export declare class CommandApi {
+    private readonly transport;
+    constructor(transport: NarrativeTransport);
+    execute(params: ExecuteCommandParams): Promise<ExecuteCommandResult>;
+    ptyWrite(params: PtyWriteParams): Promise<PtyWriteResult>;
+    ptyResize(params: PtyResizeParams): Promise<PtyResizeResult>;
+    ptyClose(params: PtyCloseParams): Promise<PtyCloseResult>;
+    ptySignal(params: PtySignalParams): Promise<PtySignalResult>;
+    listSessions(): Promise<ListSessionsResult>;
+}

package/dist/api/command.api.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandApi = void 0;
+class CommandApi {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async execute(params) {
+        return this.transport.request('execute_command', params);
+    }
+    async ptyWrite(params) {
+        return this.transport.request('pty_write', params);
+    }
+    async ptyResize(params) {
+        return this.transport.request('pty_resize', params);
+    }
+    async ptyClose(params) {
+        return this.transport.request('pty_close', params);
+    }
+    async ptySignal(params) {
+        return this.transport.request('pty_signal', params);
+    }
+    async listSessions() {
+        return this.transport.request('list_sessions', {});
+    }
+}
+exports.CommandApi = CommandApi;

package/dist/api/fs.api.d.ts

@@ -0,0 +1,13 @@
+import { NarrativeTransport } from '../transport';
+import { FsReadParams, FsReadResult, FsWriteParams, FsWriteResult, FsDeleteParams, FsDeleteResult, FsApplyPatchParams, FsApplyPatchResult, FsExistsParams, FsExistsResult, FsListDirParams, FsListDirResult, FsMkdirParams, FsMkdirResult } from '../types/fs';
+export declare class FsApi {
+    private readonly transport;
+    constructor(transport: NarrativeTransport);
+    read(params: FsReadParams): Promise<FsReadResult>;
+    write(params: FsWriteParams): Promise<FsWriteResult>;
+    delete(params: FsDeleteParams): Promise<FsDeleteResult>;
+    applyPatch(params: FsApplyPatchParams): Promise<FsApplyPatchResult>;
+    exists(params: FsExistsParams): Promise<FsExistsResult>;
+    listDir(params: FsListDirParams): Promise<FsListDirResult>;
+    mkdir(params: FsMkdirParams): Promise<FsMkdirResult>;
+}

package/dist/api/fs.api.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FsApi = void 0;
+class FsApi {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async read(params) {
+        return this.transport.request('fs_read', params);
+    }
+    async write(params) {
+        return this.transport.request('fs_write', params);
+    }
+    async delete(params) {
+        return this.transport.request('fs_delete', params);
+    }
+    async applyPatch(params) {
+        return this.transport.request('fs_apply_patch', params);
+    }
+    async exists(params) {
+        return this.transport.request('fs_exists', params);
+    }
+    async listDir(params) {
+        return this.transport.request('fs_list_dir', params);
+    }
+    async mkdir(params) {
+        return this.transport.request('fs_mkdir', params);
+    }
+}
+exports.FsApi = FsApi;

package/dist/api/index.d.ts

@@ -0,0 +1,7 @@
+export { FsApi } from './fs.api';
+export { CommandApi } from './command.api';
+export { QueueApi } from './queue.api';
+export { TimelineApi } from './timeline.api';
+export { NarrativeApi } from './narrative.api';
+export { SnapshotApi } from './snapshot.api';
+export { TraceApi } from './trace.api';

package/dist/api/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceApi = exports.SnapshotApi = exports.NarrativeApi = exports.TimelineApi = exports.QueueApi = exports.CommandApi = exports.FsApi = void 0;
+var fs_api_1 = require("./fs.api");
+Object.defineProperty(exports, "FsApi", { enumerable: true, get: function () { return fs_api_1.FsApi; } });
+var command_api_1 = require("./command.api");
+Object.defineProperty(exports, "CommandApi", { enumerable: true, get: function () { return command_api_1.CommandApi; } });
+var queue_api_1 = require("./queue.api");
+Object.defineProperty(exports, "QueueApi", { enumerable: true, get: function () { return queue_api_1.QueueApi; } });
+var timeline_api_1 = require("./timeline.api");
+Object.defineProperty(exports, "TimelineApi", { enumerable: true, get: function () { return timeline_api_1.TimelineApi; } });
+var narrative_api_1 = require("./narrative.api");
+Object.defineProperty(exports, "NarrativeApi", { enumerable: true, get: function () { return narrative_api_1.NarrativeApi; } });
+var snapshot_api_1 = require("./snapshot.api");
+Object.defineProperty(exports, "SnapshotApi", { enumerable: true, get: function () { return snapshot_api_1.SnapshotApi; } });
+var trace_api_1 = require("./trace.api");
+Object.defineProperty(exports, "TraceApi", { enumerable: true, get: function () { return trace_api_1.TraceApi; } });

package/dist/api/narrative.api.d.ts

@@ -0,0 +1,11 @@
+import { NarrativeTransport } from '../transport';
+import { CreateObjectiveParams, CreateObjectiveResult, GetObjectiveParams, GetObjectiveResult, CreateThreadParams, CreateThreadResult, CreateAgentRunParams, CreateAgentRunResult, CompleteAgentRunParams, CompleteAgentRunResult } from '../types/narrative';
+export declare class NarrativeApi {
+    private readonly transport;
+    constructor(transport: NarrativeTransport);
+    createObjective(params: CreateObjectiveParams): Promise<CreateObjectiveResult>;
+    getObjective(params: GetObjectiveParams): Promise<GetObjectiveResult>;
+    createThread(params: CreateThreadParams): Promise<CreateThreadResult>;
+    createAgentRun(params: CreateAgentRunParams): Promise<CreateAgentRunResult>;
+    completeAgentRun(params: CompleteAgentRunParams): Promise<CompleteAgentRunResult>;
+}

package/dist/api/narrative.api.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NarrativeApi = void 0;
+class NarrativeApi {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async createObjective(params) {
+        return this.transport.request('create_objective', params);
+    }
+    async getObjective(params) {
+        return this.transport.request('get_objective', params);
+    }
+    async createThread(params) {
+        return this.transport.request('create_thread', params);
+    }
+    async createAgentRun(params) {
+        return this.transport.request('create_agent_run', params);
+    }
+    async completeAgentRun(params) {
+        return this.transport.request('complete_agent_run', params);
+    }
+}
+exports.NarrativeApi = NarrativeApi;

package/dist/api/queue.api.d.ts

@@ -0,0 +1,9 @@
+import { NarrativeTransport } from '../transport';
+import { QueueStatusResult, ForceReleaseParams, ForceReleaseResult, CancelTaskParams, CancelTaskResult } from '../types/queue';
+export declare class QueueApi {
+    private readonly transport;
+    constructor(transport: NarrativeTransport);
+    getStatus(): Promise<QueueStatusResult>;
+    forceRelease(params?: ForceReleaseParams): Promise<ForceReleaseResult>;
+    cancelTask(params: CancelTaskParams): Promise<CancelTaskResult>;
+}

package/dist/api/queue.api.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueueApi = void 0;
+class QueueApi {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async getStatus() {
+        return this.transport.request('get_queue_status', {});
+    }
+    async forceRelease(params = {}) {
+        return this.transport.request('force_release_window', params);
+    }
+    async cancelTask(params) {
+        return this.transport.request('cancel_task', params);
+    }
+}
+exports.QueueApi = QueueApi;

package/dist/api/snapshot.api.d.ts

@@ -0,0 +1,18 @@
+import { NarrativeTransport } from '../transport';
+import { CreateSnapshotParams, CreateSnapshotResult, SnapshotIdParam, CreateArchiveResult, ImportArchiveParams, ImportArchiveResult, ExportBundleParams, ExportBundleResult, AddBundleParams, AddBundleResult, BrowseSnapshotParams, BrowseResult, MergeSnapshotParams, MergeSnapshotResult, AddCommitParams, AddCommitResult, CheckRecoveryParams, RecoveryCheck, CheckoutSnapshotParams, CheckoutResult, DeleteResult, PruneSnapshotsParams, PruneResult } from '../types/snapshot';
+export declare class SnapshotApi {
+    private readonly transport;
+    constructor(transport: NarrativeTransport);
+    createSnapshot(params: CreateSnapshotParams): Promise<CreateSnapshotResult>;
+    createSnapshotArchive(params: SnapshotIdParam): Promise<CreateArchiveResult>;
+    importSnapshotArchive(params: ImportArchiveParams): Promise<ImportArchiveResult>;
+    exportSnapshotBundle(params: ExportBundleParams): Promise<ExportBundleResult>;
+    addSnapshotBundle(params: AddBundleParams): Promise<AddBundleResult>;
+    browseSnapshot(params: BrowseSnapshotParams): Promise<BrowseResult>;
+    mergeSnapshot(params: MergeSnapshotParams): Promise<MergeSnapshotResult>;
+    addCommit(params: AddCommitParams): Promise<AddCommitResult>;
+    checkSnapshotRecovery(params: CheckRecoveryParams): Promise<RecoveryCheck>;
+    checkoutSnapshot(params: CheckoutSnapshotParams): Promise<CheckoutResult>;
+    deleteSnapshot(params: SnapshotIdParam): Promise<DeleteResult>;
+    pruneSnapshots(params?: PruneSnapshotsParams): Promise<PruneResult>;
+}

package/dist/api/snapshot.api.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnapshotApi = void 0;
+class SnapshotApi {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async createSnapshot(params) {
+        return this.transport.request('createSnapshot', params);
+    }
+    async createSnapshotArchive(params) {
+        return this.transport.request('createSnapshotArchive', params);
+    }
+    async importSnapshotArchive(params) {
+        return this.transport.request('importSnapshotArchive', params);
+    }
+    async exportSnapshotBundle(params) {
+        return this.transport.request('exportSnapshotBundle', params);
+    }
+    async addSnapshotBundle(params) {
+        return this.transport.request('addSnapshotBundle', params);
+    }
+    async browseSnapshot(params) {
+        return this.transport.request('browseSnapshot', params);
+    }
+    async mergeSnapshot(params) {
+        return this.transport.request('mergeSnapshot', params);
+    }
+    async addCommit(params) {
+        return this.transport.request('addCommit', params);
+    }
+    async checkSnapshotRecovery(params) {
+        return this.transport.request('checkSnapshotRecovery', params);
+    }
+    async checkoutSnapshot(params) {
+        return this.transport.request('checkoutSnapshot', params);
+    }
+    async deleteSnapshot(params) {
+        return this.transport.request('deleteSnapshot', params);
+    }
+    async pruneSnapshots(params = {}) {
+        return this.transport.request('pruneSnapshots', params);
+    }
+}
+exports.SnapshotApi = SnapshotApi;

package/dist/api/timeline.api.d.ts

@@ -0,0 +1,11 @@
+import { NarrativeTransport } from '../transport';
+import { GetTimelineParams, GetTimelineResult, RestoreSnapshotParams, RestoreSnapshotResult, GetSnapshotParams, GetSnapshotResult, DiffSnapshotsParams, SnapshotDiff, GetFileAtSnapshotParams, GetFileAtSnapshotResult } from '../types/timeline';
+export declare class TimelineApi {
+    private readonly transport;
+    constructor(transport: NarrativeTransport);
+    getTimeline(params?: GetTimelineParams): Promise<GetTimelineResult>;
+    restoreSnapshot(params: RestoreSnapshotParams): Promise<RestoreSnapshotResult>;
+    getSnapshot(params: GetSnapshotParams): Promise<GetSnapshotResult>;
+    diffSnapshots(params: DiffSnapshotsParams): Promise<SnapshotDiff>;
+    getFileAtSnapshot(params: GetFileAtSnapshotParams): Promise<GetFileAtSnapshotResult>;
+}

package/dist/api/timeline.api.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimelineApi = void 0;
+class TimelineApi {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async getTimeline(params = {}) {
+        return this.transport.request('get_timeline', params);
+    }
+    async restoreSnapshot(params) {
+        return this.transport.request('restore_snapshot', params);
+    }
+    async getSnapshot(params) {
+        return this.transport.request('get_snapshot', params);
+    }
+    async diffSnapshots(params) {
+        return this.transport.request('diff_snapshots', params);
+    }
+    async getFileAtSnapshot(params) {
+        return this.transport.request('get_file_at_snapshot', params);
+    }
+}
+exports.TimelineApi = TimelineApi;

package/dist/api/trace.api.d.ts

@@ -0,0 +1,12 @@
+import { NarrativeTransport } from '../transport';
+import { IngestTraceParams, IngestTraceResult, GetExecutionTraceParams, ExecutionTraceResult, GetThreadTraceParams, TraceSummaryResult, GetFileTraceParams, FileChangeResult, GetRecentTracesParams, IngestionSummaryResult } from '../types/trace';
+export declare class TraceApi {
+    private readonly transport;
+    constructor(transport: NarrativeTransport);
+    ingestTrace(params: IngestTraceParams): Promise<IngestTraceResult>;
+    getExecutionTrace(params: GetExecutionTraceParams): Promise<ExecutionTraceResult>;
+    getThreadTrace(params: GetThreadTraceParams): Promise<TraceSummaryResult[]>;
+    getFileTrace(params: GetFileTraceParams): Promise<FileChangeResult[]>;
+    getRecentTraces(params?: GetRecentTracesParams): Promise<TraceSummaryResult[]>;
+    getPendingIngestions(): Promise<IngestionSummaryResult[]>;
+}

package/dist/api/trace.api.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceApi = void 0;
+class TraceApi {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async ingestTrace(params) {
+        return this.transport.request('ingest_remote_execution_trace', params);
+    }
+    async getExecutionTrace(params) {
+        return this.transport.request('get_execution_trace', params);
+    }
+    async getThreadTrace(params) {
+        return this.transport.request('get_thread_trace', params);
+    }
+    async getFileTrace(params) {
+        return this.transport.request('get_file_trace', params);
+    }
+    async getRecentTraces(params = {}) {
+        return this.transport.request('get_recent_traces', params);
+    }
+    async getPendingIngestions() {
+        return this.transport.request('get_pending_ingestions', {});
+    }
+}
+exports.TraceApi = TraceApi;

package/dist/binary.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Resolve the path to the codebolt-narrative binary.
+ *
+ * Resolution order:
+ * 1. Explicit path passed as argument
+ * 2. CODEBOLT_NARRATIVE_BINARY env var
+ * 3. Platform-specific npm package (@codebolt/narrative-{os}-{arch})
+ * 4. PATH lookup via `which`
+ */
+export declare function resolveBinary(explicitPath?: string): string;

package/dist/binary.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBinary = resolveBinary;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const BINARY_NAME = process.platform === 'win32' ? 'codebolt-narrative.exe' : 'codebolt-narrative';
+/**
+ * Resolve the path to the codebolt-narrative binary.
+ *
+ * Resolution order:
+ * 1. Explicit path passed as argument
+ * 2. CODEBOLT_NARRATIVE_BINARY env var
+ * 3. Platform-specific npm package (@codebolt/narrative-{os}-{arch})
+ * 4. PATH lookup via `which`
+ */
+function resolveBinary(explicitPath) {
+    // 1. Explicit path
+    if (explicitPath) {
+        if (!(0, fs_1.existsSync)(explicitPath)) {
+            throw new Error(`Binary not found at explicit path: ${explicitPath}`);
+        }
+        return explicitPath;
+    }
+    // 2. Environment variable
+    const envPath = process.env.CODEBOLT_NARRATIVE_BINARY;
+    if (envPath) {
+        if (!(0, fs_1.existsSync)(envPath)) {
+            throw new Error(`CODEBOLT_NARRATIVE_BINARY points to non-existent path: ${envPath}`);
+        }
+        return envPath;
+    }
+    // 3. Platform-specific npm package
+    const platformPath = resolvePlatformPackage();
+    if (platformPath) {
+        return platformPath;
+    }
+    // 4. PATH lookup
+    const pathResult = resolveFromPath();
+    if (pathResult) {
+        return pathResult;
+    }
+    throw new Error(`Could not find ${BINARY_NAME} binary. Either:\n` +
+        `  - Set CODEBOLT_NARRATIVE_BINARY env var to the binary path\n` +
+        `  - Install a platform-specific @codebolt/narrative-* package\n` +
+        `  - Ensure ${BINARY_NAME} is on your PATH`);
+}
+function resolvePlatformPackage() {
+    const platform = process.platform;
+    const arch = process.arch;
+    const packageName = `@codebolt/narrative-${platform}-${arch}`;
+    try {
+        const pkgJson = require.resolve(`${packageName}/package.json`);
+        const pkgDir = (0, path_1.dirname)(pkgJson);
+        let binaryPath = (0, path_1.join)(pkgDir, 'bin', BINARY_NAME);
+        // In Electron production builds the app is packed into an ASAR archive.
+        // Binaries inside an ASAR can't be executed directly, so we rewrite the
+        // path to the unpacked copy that electron-builder extracts automatically
+        // when the file matches an `asarUnpack` glob.
+        if (binaryPath.includes('app.asar')) {
+            binaryPath = binaryPath.replace('app.asar', 'app.asar.unpacked');
+        }
+        if ((0, fs_1.existsSync)(binaryPath)) {
+            return binaryPath;
+        }
+    }
+    catch {
+        // Package not installed
+    }
+    return null;
+}
+function resolveFromPath() {
+    try {
+        const cmd = process.platform === 'win32' ? 'where' : 'which';
+        const result = (0, child_process_1.execFileSync)(cmd, [BINARY_NAME], {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const resolved = result.trim().split('\n')[0];
+        if (resolved && (0, fs_1.existsSync)(resolved)) {
+            return resolved;
+        }
+    }
+    catch {
+        // Not found on PATH
+    }
+    return null;
+}

package/dist/client.d.ts

@@ -0,0 +1,74 @@
+import { NarrativeTransport } from './transport';
+import { FsApi } from './api/fs.api';
+import { CommandApi } from './api/command.api';
+import { QueueApi } from './api/queue.api';
+import { TimelineApi } from './api/timeline.api';
+import { NarrativeApi } from './api/narrative.api';
+import { SnapshotApi } from './api/snapshot.api';
+import { TraceApi } from './api/trace.api';
+import { NarrativeNotificationMap } from './types/notifications';
+export interface NarrativeClientOptions {
+    /** Unique environment identifier (required). */
+    environmentId: string;
+    /** Workspace root directory. */
+    workspace?: string;
+    /** Data directory for storage. */
+    dataDir?: string;
+    /** Max mutation slot hold time in ms. */
+    maxSlotMs?: number;
+    /** Log level for the engine. */
+    logLevel?: string;
+    /** Explicit binary path (overrides env var and PATH lookup). */
+    binaryPath?: string;
+    /** Request timeout in ms. */
+    timeoutMs?: number;
+    /** Run as remote environment (disables FK constraints for imported snapshots). */
+    remote?: boolean;
+}
+/**
+ * High-level client for the Codebolt Narrative Engine.
+ *
+ * Provides typed domain APIs via lazy-init getters and typed notification events.
+ *
+ * ```typescript
+ * const client = new NarrativeClient({
+ *   environmentId: 'env-001',
+ *   workspace: '/path/to/project',
+ * });
+ *
+ * await client.start();
+ *
+ * const { content } = await client.fs.read({ path: 'src/main.ts' });
+ * await client.snapshot.createSnapshot({ thread_id: 'thread-1', description: 'checkpoint' });
+ *
+ * client.on('execution.pty_data', (event) => process.stdout.write(event.data));
+ *
+ * await client.shutdown();
+ * ```
+ */
+export declare class NarrativeClient {
+    private readonly transport;
+    private readonly options;
+    private _fs?;
+    private _command?;
+    private _queue?;
+    private _timeline?;
+    private _narrative?;
+    private _snapshot?;
+    private _trace?;
+    constructor(options: NarrativeClientOptions);
+    start(): Promise<void>;
+    shutdown(): Promise<void>;
+    get isReady(): boolean;
+    get fs(): FsApi;
+    get command(): CommandApi;
+    get queue(): QueueApi;
+    get timeline(): TimelineApi;
+    get narrative(): NarrativeApi;
+    get snapshot(): SnapshotApi;
+    get trace(): TraceApi;
+    on<K extends keyof NarrativeNotificationMap>(event: K, listener: (data: NarrativeNotificationMap[K]) => void): this;
+    off<K extends keyof NarrativeNotificationMap>(event: K, listener: (data: NarrativeNotificationMap[K]) => void): this;
+    getTransport(): NarrativeTransport;
+    private buildArgs;
+}

package/dist/client.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NarrativeClient = void 0;
+const transport_1 = require("./transport");
+const binary_1 = require("./binary");
+const fs_api_1 = require("./api/fs.api");
+const command_api_1 = require("./api/command.api");
+const queue_api_1 = require("./api/queue.api");
+const timeline_api_1 = require("./api/timeline.api");
+const narrative_api_1 = require("./api/narrative.api");
+const snapshot_api_1 = require("./api/snapshot.api");
+const trace_api_1 = require("./api/trace.api");
+/**
+ * High-level client for the Codebolt Narrative Engine.
+ *
+ * Provides typed domain APIs via lazy-init getters and typed notification events.
+ *
+ * ```typescript
+ * const client = new NarrativeClient({
+ *   environmentId: 'env-001',
+ *   workspace: '/path/to/project',
+ * });
+ *
+ * await client.start();
+ *
+ * const { content } = await client.fs.read({ path: 'src/main.ts' });
+ * await client.snapshot.createSnapshot({ thread_id: 'thread-1', description: 'checkpoint' });
+ *
+ * client.on('execution.pty_data', (event) => process.stdout.write(event.data));
+ *
+ * await client.shutdown();
+ * ```
+ */
+class NarrativeClient {
+    constructor(options) {
+        this.options = options;
+        const binaryPath = (0, binary_1.resolveBinary)(options.binaryPath);
+        const args = this.buildArgs();
+        this.transport = new transport_1.NarrativeTransport({
+            binaryPath,
+            args,
+            timeoutMs: options.timeoutMs,
+        });
+    }
+    // --- Lifecycle ---
+    async start() {
+        await this.transport.start();
+    }
+    async shutdown() {
+        await this.transport.shutdown();
+    }
+    get isReady() {
+        return this.transport.isReady;
+    }
+    // --- Domain APIs (lazy-init getters) ---
+    get fs() {
+        if (!this._fs)
+            this._fs = new fs_api_1.FsApi(this.transport);
+        return this._fs;
+    }
+    get command() {
+        if (!this._command)
+            this._command = new command_api_1.CommandApi(this.transport);
+        return this._command;
+    }
+    get queue() {
+        if (!this._queue)
+            this._queue = new queue_api_1.QueueApi(this.transport);
+        return this._queue;
+    }
+    get timeline() {
+        if (!this._timeline)
+            this._timeline = new timeline_api_1.TimelineApi(this.transport);
+        return this._timeline;
+    }
+    get narrative() {
+        if (!this._narrative)
+            this._narrative = new narrative_api_1.NarrativeApi(this.transport);
+        return this._narrative;
+    }
+    get snapshot() {
+        if (!this._snapshot)
+            this._snapshot = new snapshot_api_1.SnapshotApi(this.transport);
+        return this._snapshot;
+    }
+    get trace() {
+        if (!this._trace)
+            this._trace = new trace_api_1.TraceApi(this.transport);
+        return this._trace;
+    }
+    // --- Typed notification events ---
+    on(event, listener) {
+        this.transport.on(event, listener);
+        return this;
+    }
+    off(event, listener) {
+        this.transport.off(event, listener);
+        return this;
+    }
+    // --- Escape hatch ---
+    getTransport() {
+        return this.transport;
+    }
+    // --- Internal ---
+    buildArgs() {
+        const args = [
+            '--environment-id', this.options.environmentId,
+        ];
+        if (this.options.workspace) {
+            args.push('--workspace', this.options.workspace);
+        }
+        if (this.options.dataDir) {
+            args.push('--data-dir', this.options.dataDir);
+        }
+        if (this.options.maxSlotMs !== undefined) {
+            args.push('--max-slot-ms', String(this.options.maxSlotMs));
+        }
+        if (this.options.logLevel) {
+            args.push('--log-level', this.options.logLevel);
+        }
+        if (this.options.remote) {
+            args.push('--remote');
+        }
+        return args;
+    }
+}
+exports.NarrativeClient = NarrativeClient;

package/dist/errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Error codes mapped from Rust NarrativeError::to_rpc_code().
+ */
+export declare const PARSE_ERROR = -32700;
+export declare const INVALID_REQUEST = -32600;
+export declare const METHOD_NOT_FOUND = -32601;
+export declare const IO_ERROR = -32000;
+export declare const GIT_ERROR = -32001;
+export declare const SQLITE_ERROR = -32002;
+export declare const SLOT_UNAVAILABLE = -32010;
+export declare const SLOT_TIMEOUT = -32011;
+export declare const PREEMPTION = -32012;
+export declare const INVALID_CONTEXT = -32020;
+export declare const SNAPSHOT_NOT_FOUND = -32030;
+export declare const PTY_ERROR = -32040;
+export declare const SESSION_NOT_FOUND = -32041;
+export declare const EXECUTION_ERROR = -32042;
+export declare const QUEUE_ERROR = -32050;
+export declare const FILE_NOT_FOUND = -32060;
+export declare const MERGE_CONFLICT = -32070;
+export declare const INVALID_OPERATION = -32600;
+export declare const CONFIG_ERROR = -32603;
+export declare class NarrativeRpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+export declare function isSlotUnavailable(err: unknown): err is NarrativeRpcError;
+export declare function isSlotTimeout(err: unknown): err is NarrativeRpcError;
+export declare function isSnapshotNotFound(err: unknown): err is NarrativeRpcError;
+export declare function isFileNotFound(err: unknown): err is NarrativeRpcError;
+export declare function isSessionNotFound(err: unknown): err is NarrativeRpcError;
+export declare function isMergeConflict(err: unknown): err is NarrativeRpcError;
+export declare function isInvalidContext(err: unknown): err is NarrativeRpcError;
+export declare function isMethodNotFound(err: unknown): err is NarrativeRpcError;