@bolt-foundry/gambit 0.8.1 → 0.8.5-rc.10

package/esm/src/server_types.d.ts

@@ -0,0 +1,110 @@
+import type { SavedState, TraceEvent } from "@bolt-foundry/gambit-core";
+export type AvailableTestDeck = {
+    id: string;
+    label: string;
+    description?: string;
+    path: string;
+};
+export type AvailableGraderDeck = {
+    id: string;
+    label: string;
+    description?: string;
+    path: string;
+};
+export type NormalizedSchema = {
+    kind: "string" | "number" | "boolean" | "enum" | "object" | "array" | "unknown";
+    optional: boolean;
+    description?: string;
+    example?: unknown;
+    defaultValue?: unknown;
+    enumValues?: Array<unknown>;
+    fields?: Record<string, NormalizedSchema>;
+    items?: NormalizedSchema;
+};
+export type DeckToolDescription = {
+    name: string;
+    label?: string;
+    description?: string;
+    path?: string;
+};
+export type SchemaDescription = {
+    schema?: NormalizedSchema;
+    defaults?: unknown;
+    error?: string;
+    tools?: Array<DeckToolDescription>;
+};
+export type GradingRunRecord = {
+    id: string;
+    workspaceId?: string;
+    gradingRunId?: string;
+    graderId: string;
+    graderPath: string;
+    graderLabel?: string;
+    status: "running" | "completed" | "error";
+    runAt?: string;
+    referenceSample?: {
+        score: number;
+        reason: string;
+        evidence?: Array<string>;
+        artifactRevisionId?: string;
+        workspaceId?: string;
+        gradingRunId?: string;
+    };
+    input?: unknown;
+    result?: unknown;
+    error?: string;
+};
+export type GradingFlag = {
+    id: string;
+    refId: string;
+    runId?: string;
+    turnIndex?: number;
+    reason?: string;
+    createdAt: string;
+};
+export type SessionMeta = {
+    id: string;
+    deck?: string;
+    deckSlug?: string;
+    testBotName?: string;
+    createdAt?: string;
+    gradingRuns?: Array<GradingRunRecord>;
+    sessionDir?: string;
+    statePath?: string;
+};
+export type OutgoingMessage = {
+    type: "ready";
+    deck: string;
+    port: number;
+    schema?: NormalizedSchema;
+    defaults?: unknown;
+    schemaError?: string;
+} | {
+    type: "pong";
+} | {
+    type: "stream";
+    chunk: string;
+    runId?: string;
+} | {
+    type: "result";
+    result: unknown;
+    runId?: string;
+    streamed: boolean;
+} | {
+    type: "trace";
+    event: TraceEvent;
+} | {
+    type: "state";
+    state: SavedState;
+    newMessages?: Array<{
+        index: number;
+        role: string;
+        messageRefId?: string;
+        content?: unknown;
+    }>;
+} | {
+    type: "error";
+    message: string;
+    runId?: string;
+};
+//# sourceMappingURL=server_types.d.ts.map

package/esm/src/server_types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server_types.d.ts","sourceRoot":"","sources":["../../src/src/server_types.ts"],"names":[],"mappings":"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"}

package/esm/src/server_types.js

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

package/esm/src/server_ui_routes.d.ts

@@ -0,0 +1,33 @@
+type HandleUiRoutesDeps = {
+    url: URL;
+    req: Request;
+    workspaceRouteBase: string;
+    activeWorkspaceId: string | null;
+    activeWorkspaceOnboarding: boolean;
+    resolvedDeckPath: string;
+    deckLabel?: string;
+    getWorkspaceIdFromQuery: (url: URL) => string | undefined;
+    activateWorkspaceDeck: (workspaceId?: string) => Promise<void>;
+    schemaPromise: Promise<unknown>;
+    deckLoadPromise: Promise<unknown>;
+    canServeReactBundle: () => Promise<boolean>;
+    simulatorReactHtml: (deckPath: string, deckLabel?: string, opts?: {
+        workspaceId?: string | null;
+        onboarding?: boolean;
+    }) => string;
+    toDeckLabel: (deckPath: string) => string;
+    readReactBundle: () => Promise<Uint8Array | null>;
+    shouldAdvertiseSourceMap: () => boolean;
+    readReactBundleSourceMap: () => Promise<Uint8Array | null>;
+    listSessions: () => unknown;
+    createWorkspaceSession: () => Promise<{
+        id: string;
+        rootDeckPath: string;
+        rootDir: string;
+        createdAt: string;
+    }>;
+    workspaceStateSchemaVersion: string;
+};
+export declare const handleUiRoutes: (deps: HandleUiRoutesDeps) => Promise<Response | null>;
+export {};
+//# sourceMappingURL=server_ui_routes.d.ts.map

package/esm/src/server_ui_routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server_ui_routes.d.ts","sourceRoot":"","sources":["../../src/src/server_ui_routes.ts"],"names":[],"mappings":"AAMA,KAAK,kBAAkB,GAAG;IACxB,GAAG,EAAE,GAAG,CAAC;IACT,GAAG,EAAE,OAAO,CAAC;IACb,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,yBAAyB,EAAE,OAAO,CAAC;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uBAAuB,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,GAAG,SAAS,CAAC;IAC1D,qBAAqB,EAAE,CAAC,WAAW,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,aAAa,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,eAAe,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,mBAAmB,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,KACzD,MAAM,CAAC;IACZ,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1C,eAAe,EAAE,MAAM,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAClD,wBAAwB,EAAE,MAAM,OAAO,CAAC;IACxC,wBAAwB,EAAE,MAAM,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC3D,YAAY,EAAE,MAAM,OAAO,CAAC;IAC5B,sBAAsB,EAAE,MAAM,OAAO,CAAC;QACpC,EAAE,EAAE,MAAM,CAAC;QACX,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;IACH,2BAA2B,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,eAAO,MAAM,cAAc,GACzB,MAAM,kBAAkB,KACvB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAwMzB,CAAC"}

package/esm/src/server_ui_routes.js

@@ -0,0 +1,136 @@
+import * as dntShim from "../_dnt.shims.js";
+import { WORKSPACE_API_BASE, WORKSPACES_API_BASE, } from "./workspace_contract.js";
+export const handleUiRoutes = async (deps) => {
+    const { url, req, workspaceRouteBase, activeWorkspaceId, activeWorkspaceOnboarding, resolvedDeckPath, deckLabel, getWorkspaceIdFromQuery, activateWorkspaceDeck, schemaPromise, deckLoadPromise, canServeReactBundle, simulatorReactHtml, toDeckLabel, readReactBundle, shouldAdvertiseSourceMap, readReactBundleSourceMap, listSessions, createWorkspaceSession, workspaceStateSchemaVersion, } = deps;
+    if (url.pathname === "/" ||
+        url.pathname === workspaceRouteBase ||
+        url.pathname.startsWith(`${workspaceRouteBase}/`) ||
+        url.pathname.startsWith("/simulate") ||
+        url.pathname.startsWith("/debug") ||
+        url.pathname.startsWith("/build") ||
+        url.pathname.startsWith("/editor") ||
+        url.pathname.startsWith("/docs")) {
+        const hasBundle = await canServeReactBundle();
+        if (!hasBundle) {
+            return new Response("Simulator UI bundle missing. Run `deno task bundle:sim` (or start with `--bundle`).", { status: 500 });
+        }
+        await deckLoadPromise.catch(() => null);
+        const resolvedLabel = deckLabel ?? toDeckLabel(resolvedDeckPath);
+        return new Response(simulatorReactHtml(resolvedDeckPath, resolvedLabel, {
+            workspaceId: activeWorkspaceId ?? null,
+            onboarding: activeWorkspaceOnboarding,
+        }), {
+            headers: { "content-type": "text/html; charset=utf-8" },
+        });
+    }
+    if (url.pathname === "/schema") {
+        const sessionId = getWorkspaceIdFromQuery(url);
+        if (sessionId) {
+            await activateWorkspaceDeck(sessionId);
+        }
+        const descRaw = await schemaPromise;
+        const desc = descRaw && typeof descRaw === "object"
+            ? descRaw
+            : {};
+        const deck = await deckLoadPromise.catch(() => null);
+        const modelParams = deck && typeof deck === "object"
+            ? deck.modelParams
+            : undefined;
+        const startMode = deck &&
+            (deck.startMode === "assistant" || deck.startMode === "user")
+            ? deck.startMode
+            : "assistant";
+        return new Response(JSON.stringify({
+            deck: resolvedDeckPath,
+            startMode,
+            modelParams,
+            ...desc,
+        }), {
+            headers: { "content-type": "application/json; charset=utf-8" },
+        });
+    }
+    if (url.pathname === "/api/deck-source") {
+        if (req.method !== "GET") {
+            return new Response("Method not allowed", { status: 405 });
+        }
+        try {
+            const content = await dntShim.Deno.readTextFile(resolvedDeckPath);
+            return new Response(JSON.stringify({
+                path: resolvedDeckPath,
+                content,
+            }), { headers: { "content-type": "application/json; charset=utf-8" } });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return new Response(JSON.stringify({
+                path: resolvedDeckPath,
+                error: message,
+            }), {
+                status: 500,
+                headers: { "content-type": "application/json; charset=utf-8" },
+            });
+        }
+    }
+    if (url.pathname === "/ui/bundle.js") {
+        const data = await readReactBundle();
+        if (!data) {
+            return new Response("Bundle missing. Run `deno task bundle:sim` (or start with `--bundle`).", { status: 404 });
+        }
+        try {
+            const headers = new Headers({
+                "content-type": "application/javascript; charset=utf-8",
+            });
+            if (shouldAdvertiseSourceMap()) {
+                headers.set("SourceMap", "/ui/bundle.js.map");
+            }
+            return new Response(data, { headers });
+        }
+        catch (err) {
+            return new Response(`Failed to read bundle: ${err instanceof Error ? err.message : String(err)}`, { status: 500 });
+        }
+    }
+    if (url.pathname === "/ui/bundle.js.map") {
+        const data = await readReactBundleSourceMap();
+        if (!data) {
+            return new Response("Source map missing. Run `deno task bundle:sim:sourcemap` (or start with `--bundle --sourcemap`).", { status: 404 });
+        }
+        try {
+            return new Response(data, {
+                headers: {
+                    "content-type": "application/json; charset=utf-8",
+                },
+            });
+        }
+        catch (err) {
+            return new Response(`Failed to read source map: ${err instanceof Error ? err.message : String(err)}`, { status: 500 });
+        }
+    }
+    if (url.pathname === WORKSPACES_API_BASE) {
+        const workspaces = listSessions();
+        return new Response(JSON.stringify({ workspaces }), {
+            headers: { "content-type": "application/json; charset=utf-8" },
+        });
+    }
+    if (url.pathname === `${WORKSPACE_API_BASE}/new`) {
+        if (req.method !== "POST") {
+            return new Response("Method not allowed", { status: 405 });
+        }
+        try {
+            const workspace = await createWorkspaceSession();
+            await activateWorkspaceDeck(workspace.id);
+            return new Response(JSON.stringify({
+                workspaceId: workspace.id,
+                deckPath: workspace.rootDeckPath,
+                workspaceDir: workspace.rootDir,
+                createdAt: workspace.createdAt,
+                workspaceSchemaVersion: workspaceStateSchemaVersion,
+            }), { headers: { "content-type": "application/json" } });
+        }
+        catch (err) {
+            return new Response(JSON.stringify({
+                error: err instanceof Error ? err.message : String(err),
+            }), { status: 500, headers: { "content-type": "application/json" } });
+        }
+    }
+    return null;
+};

package/esm/src/session_artifacts.d.ts

@@ -0,0 +1,22 @@
+import type { SavedState, TraceEvent } from "@bolt-foundry/gambit-core";
+export type SessionArtifactsConfig = {
+    rootDir: string;
+    sessionId?: string;
+    continueSession?: boolean;
+    resumeState?: boolean;
+};
+export type SessionArtifactsRun = {
+    state?: SavedState;
+    trace: (event: TraceEvent) => void;
+    onStateUpdate: (state: SavedState) => void;
+    finalize: () => void;
+    sessionId: string;
+    sessionDir: string;
+};
+export declare function withSessionArtifacts(args: {
+    config: SessionArtifactsConfig;
+    trace?: (event: TraceEvent) => void;
+    onStateUpdate?: (state: SavedState) => void;
+    state?: SavedState;
+}): SessionArtifactsRun;
+//# sourceMappingURL=session_artifacts.d.ts.map

package/esm/src/session_artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_artifacts.d.ts","sourceRoot":"","sources":["../../src/src/session_artifacts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAExE,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;IAI1B,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACnC,aAAa,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC3C,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AA4KF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,MAAM,EAAE,sBAAsB,CAAC;IAC/B,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACpC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC5C,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB,GAAG,mBAAmB,CA8ItB"}

package/esm/src/session_artifacts.js

@@ -0,0 +1,243 @@
+import * as dntShim from "../_dnt.shims.js";
+import * as path from "../deps/jsr.io/@std/path/1.1.4/mod.js";
+import { existsSync } from "../deps/jsr.io/@std/fs/1.0.23/mod.js";
+function canonicalSessionEventType(type) {
+    if (type.startsWith("response.") || type.startsWith("gambit.")) {
+        return type;
+    }
+    return `gambit.${type}`;
+}
+function randomId(prefix) {
+    const suffix = crypto.randomUUID().replace(/-/g, "").slice(0, 24);
+    return `${prefix}-${suffix}`;
+}
+function parseFiniteInteger(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return undefined;
+    if (!Number.isInteger(value))
+        return undefined;
+    return value;
+}
+function normalizeConfig(config) {
+    const rootDir = path.resolve(config.rootDir);
+    const sessionId = config.sessionId?.trim() || randomId("session");
+    const continueSession = Boolean(config.continueSession);
+    const resumeState = config.resumeState ?? true;
+    if (!rootDir) {
+        throw new Error("sessionArtifacts.rootDir is required.");
+    }
+    if (config.continueSession && !config.sessionId?.trim()) {
+        throw new Error("sessionArtifacts.sessionId is required when continueSession is true.");
+    }
+    return { rootDir, sessionId, continueSession, resumeState };
+}
+function prepare(configInput) {
+    const config = normalizeConfig(configInput);
+    const sessionDir = path.join(config.rootDir, config.sessionId);
+    const statePath = path.join(sessionDir, "state.json");
+    const eventsPath = path.join(sessionDir, "events.jsonl");
+    const lockPath = path.join(sessionDir, ".lock");
+    return { config, sessionDir, statePath, eventsPath, lockPath };
+}
+function ensureMonotonicOffsets(records, eventsPath) {
+    let expected = 0;
+    let highest = -1;
+    for (const record of records) {
+        if (record.offset !== expected) {
+            throw new Error(`Non-monotonic offset in ${eventsPath}: expected ${expected}, got ${record.offset}`);
+        }
+        highest = record.offset;
+        expected += 1;
+    }
+    return highest;
+}
+function readEvents(eventsPath) {
+    if (!existsSync(eventsPath)) {
+        return { records: [], highestOffset: -1 };
+    }
+    const text = dntShim.Deno.readTextFileSync(eventsPath);
+    const records = [];
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        const parsed = JSON.parse(line);
+        const offset = parseFiniteInteger(parsed.offset);
+        const createdAt = typeof parsed.createdAt === "string"
+            ? parsed.createdAt
+            : null;
+        const type = parsed.type;
+        if (offset === undefined ||
+            createdAt === null ||
+            typeof type !== "string" ||
+            type.trim().length === 0) {
+            throw new Error(`Invalid event record in ${eventsPath}`);
+        }
+        records.push({
+            offset,
+            createdAt,
+            type,
+            _gambit: parsed._gambit &&
+                typeof parsed._gambit === "object" &&
+                !Array.isArray(parsed._gambit)
+                ? parsed._gambit
+                : undefined,
+        });
+    }
+    const highestOffset = records.length
+        ? ensureMonotonicOffsets(records, eventsPath)
+        : -1;
+    return { records, highestOffset };
+}
+function writeJsonAtomic(filePath, payload) {
+    const dir = path.dirname(filePath);
+    dntShim.Deno.mkdirSync(dir, { recursive: true });
+    const tmpPath = path.join(dir, `.tmp-${path.basename(filePath)}-${randomId("tmp")}`);
+    dntShim.Deno.writeTextFileSync(tmpPath, JSON.stringify(payload, null, 2));
+    dntShim.Deno.renameSync(tmpPath, filePath);
+}
+function appendJsonl(filePath, payload) {
+    dntShim.Deno.mkdirSync(path.dirname(filePath), { recursive: true });
+    const line = JSON.stringify(payload);
+    dntShim.Deno.writeTextFileSync(filePath, `${line}\n`, { append: true });
+}
+function archiveOrphanedEvents(eventsPath) {
+    const dir = path.dirname(eventsPath);
+    const stamp = new Date().toISOString().replaceAll(":", "-");
+    const archivedPath = path.join(dir, `events.orphaned.${stamp}.jsonl`);
+    dntShim.Deno.renameSync(eventsPath, archivedPath);
+    return archivedPath;
+}
+function writeStateSnapshot(args) {
+    const nextMeta = {
+        ...(args.state.meta ?? {}),
+        sessionId: args.sessionId,
+        sessionDir: args.sessionDir,
+        sessionStatePath: args.statePath,
+        sessionEventsPath: args.eventsPath,
+        lastAppliedOffset: args.offset,
+        lastAppliedEventSeq: args.offset,
+    };
+    const snapshot = {
+        ...args.state,
+        meta: nextMeta,
+    };
+    writeJsonAtomic(args.statePath, snapshot);
+}
+export function withSessionArtifacts(args) {
+    const prepared = prepare(args.config);
+    const { config, sessionDir, statePath, eventsPath, lockPath, } = prepared;
+    dntShim.Deno.mkdirSync(sessionDir, { recursive: true });
+    if (!config.continueSession && (existsSync(statePath) || existsSync(eventsPath))) {
+        throw new Error(`Session artifact directory already exists at ${sessionDir}. Pass continueSession: true with the same sessionId to continue.`);
+    }
+    try {
+        dntShim.Deno.writeTextFileSync(lockPath, JSON.stringify({
+            pid: dntShim.Deno.pid,
+            acquiredAt: new Date().toISOString(),
+        }), { createNew: true });
+    }
+    catch (err) {
+        if (err instanceof dntShim.Deno.errors.AlreadyExists) {
+            throw new Error(`Session artifact directory is already active: ${sessionDir}`);
+        }
+        throw err;
+    }
+    let latestState = args.state;
+    let highestOffset = -1;
+    let lastStateOffset = -1;
+    try {
+        const loaded = readEvents(eventsPath);
+        highestOffset = loaded.highestOffset;
+        if (!latestState &&
+            config.continueSession &&
+            config.resumeState &&
+            existsSync(statePath)) {
+            const parsed = JSON.parse(dntShim.Deno.readTextFileSync(statePath));
+            latestState = parsed;
+        }
+        if (!latestState &&
+            config.continueSession &&
+            config.resumeState &&
+            highestOffset >= 0) {
+            // Recovery path: preserve prior trace-only history, then start a fresh
+            // append-only log so retries can continue without corrupting snapshot
+            // boundaries.
+            archiveOrphanedEvents(eventsPath);
+            highestOffset = -1;
+        }
+        const meta = latestState?.meta;
+        lastStateOffset = parseFiniteInteger(meta?.lastAppliedOffset) ??
+            parseFiniteInteger(meta?.lastAppliedEventSeq) ??
+            -1;
+    }
+    catch (err) {
+        try {
+            dntShim.Deno.removeSync(lockPath);
+        }
+        catch {
+            // no-op
+        }
+        throw err;
+    }
+    const persistLatest = () => {
+        if (!latestState)
+            return;
+        writeStateSnapshot({
+            statePath,
+            state: latestState,
+            offset: lastStateOffset,
+            sessionId: config.sessionId,
+            sessionDir,
+            eventsPath,
+        });
+    };
+    const trace = (event) => {
+        highestOffset += 1;
+        const createdAt = new Date().toISOString();
+        const sourceType = typeof event?.type === "string" &&
+            event.type.trim().length > 0
+            ? event.type.trim()
+            : "gambit.session.event";
+        const payloadType = canonicalSessionEventType(sourceType);
+        const rawMeta = event?._gambit;
+        const meta = rawMeta && typeof rawMeta === "object" && !Array.isArray(rawMeta)
+            ? rawMeta
+            : {};
+        const record = {
+            ...event,
+            type: payloadType,
+            offset: highestOffset,
+            createdAt,
+            _gambit: {
+                ...meta,
+                ...(payloadType !== sourceType ? { source_type: sourceType } : {}),
+                domain: "session",
+                offset: highestOffset,
+            },
+        };
+        appendJsonl(eventsPath, record);
+        args.trace?.(event);
+    };
+    const onStateUpdate = (state) => {
+        latestState = state;
+        lastStateOffset = highestOffset;
+        persistLatest();
+        args.onStateUpdate?.(state);
+    };
+    const finalize = () => {
+        try {
+            dntShim.Deno.removeSync(lockPath);
+        }
+        catch {
+            // no-op
+        }
+    };
+    return {
+        state: latestState,
+        trace,
+        onStateUpdate,
+        finalize,
+        sessionId: config.sessionId,
+        sessionDir,
+    };
+}

package/esm/src/trace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/src/trace.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAI5D,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAQ7E;AAED,wBAAgB,iBAAiB,IAAI,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAmI/D"}
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/src/trace.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAI5D,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAQ7E;AAED,wBAAgB,iBAAiB,IAAI,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CA+I/D"}

package/esm/src/trace.js

@@ -14,6 +14,9 @@ export function makeConsoleTracer() {
     const started = new Map();
     const now = () => performance.now();
     const fmtMs = (start) => start !== undefined ? ` elapsed_ms=${Math.round(now() - start)}` : "";
+    const fmtPermissions = (permissions) => permissions?.effective !== undefined
+        ? ` permissions=${JSON.stringify(permissions.effective)}`
+        : "";
     return (event) => {
         switch (event.type) {
             case "run.start":
@@ -22,7 +25,7 @@ export function makeConsoleTracer() {
                     ? ` initialUserMessage=${JSON.stringify(event.initialUserMessage)}`
                     : ""}${event.input !== undefined
                     ? ` input=${JSON.stringify(event.input)}`
-                    : ""}`);
+                    : ""}${fmtPermissions(event.permissions)}`);
                 break;
             case "run.end": {
                 const start = started.get(event.runId);
@@ -36,7 +39,7 @@ export function makeConsoleTracer() {
             }
             case "deck.start":
                 started.set(event.actionCallId, now());
-                logger.log(`[trace] deck.start runId=${event.runId} actionCallId=${event.actionCallId} deck=${event.deckPath}`);
+                logger.log(`[trace] deck.start runId=${event.runId} actionCallId=${event.actionCallId} deck=${event.deckPath}${fmtPermissions(event.permissions)}`);
                 break;
             case "deck.end": {
                 const start = started.get(event.actionCallId);
@@ -46,7 +49,7 @@ export function makeConsoleTracer() {
             }
             case "action.start":
                 started.set(event.actionCallId, now());
-                logger.log(`[trace] action.start runId=${event.runId} actionCallId=${event.actionCallId} name=${event.name} path=${event.path}`);
+                logger.log(`[trace] action.start runId=${event.runId} actionCallId=${event.actionCallId} name=${event.name} path=${event.path}${fmtPermissions(event.permissions)}`);
                 break;
             case "action.end": {
                 const start = started.get(event.actionCallId);
@@ -61,10 +64,10 @@ export function makeConsoleTracer() {
                 logger.log(`[trace] tool.result runId=${event.runId} actionCallId=${event.actionCallId} name=${event.name} result=${JSON.stringify(event.result)}`);
                 break;
             case "model.call":
-                logger.log(`[trace] model.call runId=${event.runId} actionCallId=${event.actionCallId} deck=${event.deckPath} model=${event.model ?? "(default)"} messages=${event.messageCount ?? event.messages.length} tools=${event.toolCount ?? event.tools?.length ?? 0} stream=${event.stream ?? false} stateMessages=${event.stateMessages ?? 0}`);
+                logger.log(`[trace] model.call runId=${event.runId} actionCallId=${event.actionCallId} deck=${event.deckPath} model=${event.model ?? "(default)"} messages=${event.messageCount ?? event.messages.length} tools=${event.toolCount ?? event.tools?.length ?? 0} stream=${event.stream ?? false} mode=${event.mode ?? "chat"} stateMessages=${event.stateMessages ?? 0}`);
                 break;
             case "model.result":
-                logger.log(`[trace] model.result runId=${event.runId} actionCallId=${event.actionCallId} deck=${event.deckPath} model=${event.model ?? "(default)"} finish=${event.finishReason} toolCalls=${event.toolCalls?.length ?? 0} stateMessages=${event.stateMessages ?? 0}`);
+                logger.log(`[trace] model.result runId=${event.runId} actionCallId=${event.actionCallId} deck=${event.deckPath} model=${event.model ?? "(default)"} finish=${event.finishReason} toolCalls=${event.toolCalls?.length ?? 0} mode=${event.mode ?? "chat"} stateMessages=${event.stateMessages ?? 0}`);
                 break;
             case "log": {
                 const meta = event.meta !== undefined

package/esm/src/workspace.d.ts

@@ -0,0 +1,19 @@
+export type WorkspaceScaffold = {
+    id: string;
+    rootDir: string;
+    rootDeckPath: string;
+    createdAt: string;
+};
+export type WorkspaceRootScaffold = {
+    rootDir: string;
+    rootDeckPath: string;
+};
+type WorkspaceScaffoldOptions = {
+    baseDir: string;
+    id?: string;
+    now?: Date;
+};
+export declare function createWorkspaceScaffoldAtRoot(rootDir: string): Promise<WorkspaceRootScaffold>;
+export declare function createWorkspaceScaffold(opts: WorkspaceScaffoldOptions): Promise<WorkspaceScaffold>;
+export {};
+//# sourceMappingURL=workspace.d.ts.map

package/esm/src/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/src/workspace.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,CAAC;AAyHF,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,qBAAqB,CAAC,CA4BhC;AAED,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAkC5B"}