@tomsun28/pizza 0.0.9 → 0.1.1

package/dist/core/event-store/sqlite-store.js

@@ -0,0 +1,275 @@
+import { mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+import { v7 as uuidv7 } from "uuid";
+import { deriveWorkspaceId, getEventDatabasePath } from "./workspace.js";
+const require = createRequire(import.meta.url);
+let DatabaseSyncCtor;
+export class SqliteEventStore {
+    constructor(workspaceId, dbPath, runtimeId = "local_runtime") {
+        this.runtimeId = runtimeId;
+        this.subscribers = new Map();
+        this.nextSubId = 0;
+        this.workspace_id = workspaceId;
+        if (dbPath !== ":memory:") {
+            mkdirSync(dirname(dbPath), { recursive: true });
+        }
+        this.db = new (loadDatabaseSync())(dbPath);
+        this._initSchema();
+    }
+    append(partial) {
+        if (partial.idempotency_key) {
+            const existing = this._getByIdempotencyKey(partial.idempotency_key);
+            if (existing)
+                return existing;
+        }
+        const event = this._normalizeEvent(partial);
+        this._insert(event);
+        const inserted = this.get(event.event_id) ?? event;
+        this._notify(inserted);
+        return inserted;
+    }
+    appendBatch(partials) {
+        const events = [];
+        const newEvents = [];
+        let nextSequence = this.head_sequence + 1;
+        for (const partial of partials) {
+            if (partial.idempotency_key) {
+                const existing = this._getByIdempotencyKey(partial.idempotency_key);
+                if (existing) {
+                    events.push(existing);
+                    continue;
+                }
+            }
+            const sequence = partial.sequence ?? nextSequence;
+            nextSequence = Math.max(nextSequence, sequence + 1);
+            const event = this._normalizeEvent({ ...partial, sequence });
+            events.push(event);
+            newEvents.push(event);
+        }
+        this.db.exec("begin");
+        try {
+            for (const event of newEvents) {
+                this._insert(event);
+            }
+            this.db.exec("commit");
+        }
+        catch (error) {
+            this.db.exec("rollback");
+            throw error;
+        }
+        for (const event of newEvents) {
+            this._notify(event);
+        }
+        return events.map((event) => this.get(event.event_id) ?? event);
+    }
+    query(filter) {
+        const clauses = ["workspace_id = ?"];
+        const params = [this.workspace_id];
+        if (filter.after_sequence !== undefined) {
+            clauses.push("sequence > ?");
+            params.push(filter.after_sequence);
+        }
+        if (filter.before_sequence !== undefined) {
+            clauses.push("sequence < ?");
+            params.push(filter.before_sequence);
+        }
+        if (filter.after) {
+            const after = this.get(filter.after);
+            if (after) {
+                clauses.push("sequence > ?");
+                params.push(after.sequence);
+            }
+        }
+        if (filter.before) {
+            const before = this.get(filter.before);
+            if (before) {
+                clauses.push("sequence < ?");
+                params.push(before.sequence);
+            }
+        }
+        if (filter.types?.length) {
+            clauses.push(`type in (${filter.types.map(() => "?").join(", ")})`);
+            params.push(...filter.types);
+        }
+        if (filter.actor_ids?.length) {
+            clauses.push(`actor_id in (${filter.actor_ids.map(() => "?").join(", ")})`);
+            params.push(...filter.actor_ids);
+        }
+        if (filter.thread_id) {
+            clauses.push("thread_id = ?");
+            params.push(filter.thread_id);
+        }
+        if (filter.caused_by) {
+            clauses.push(`event_id in (
+				with recursive descendants(event_id) as (
+					select event_id from events where workspace_id = ? and caused_by = ?
+					union all
+					select e.event_id from events e join descendants d on e.caused_by = d.event_id
+					where e.workspace_id = ?
+				)
+				select event_id from descendants
+			)`);
+            params.push(this.workspace_id, filter.caused_by, this.workspace_id);
+        }
+        let sql = `select * from events where ${clauses.join(" and ")} order by sequence ${filter.reverse ? "desc" : "asc"}`;
+        if (filter.limit && filter.limit > 0) {
+            sql += " limit ?";
+            params.push(filter.limit);
+        }
+        return this.db.prepare(sql).all(...params).map((row) => rowToEvent(row));
+    }
+    get(event_id) {
+        const row = this.db
+            .prepare("select * from events where workspace_id = ? and event_id = ?")
+            .get(this.workspace_id, event_id);
+        return row ? rowToEvent(row) : undefined;
+    }
+    latest(count) {
+        return this.query({ limit: count, reverse: true }).reverse();
+    }
+    getCausalChain(event_id) {
+        const chain = [];
+        let currentId = event_id;
+        while (currentId) {
+            const event = this.get(currentId);
+            if (!event)
+                break;
+            chain.unshift(event);
+            currentId = event.caused_by;
+        }
+        return chain;
+    }
+    subscribe(handler, options) {
+        const subId = this.nextSubId++;
+        this.subscribers.set(subId, { handler, options });
+        return () => this.subscribers.delete(subId);
+    }
+    get size() {
+        const row = this.db
+            .prepare("select count(*) as count from events where workspace_id = ?")
+            .get(this.workspace_id);
+        return row.count;
+    }
+    get head() {
+        const row = this.db
+            .prepare("select event_id from events where workspace_id = ? order by sequence desc limit 1")
+            .get(this.workspace_id);
+        return row?.event_id;
+    }
+    get head_sequence() {
+        const row = this.db
+            .prepare("select coalesce(max(sequence), 0) as sequence from events where workspace_id = ?")
+            .get(this.workspace_id);
+        return row.sequence;
+    }
+    close() {
+        this.db.close();
+    }
+    _initSchema() {
+        this.db.exec(`
+			create table if not exists events (
+				sequence integer not null,
+				event_id text not null unique,
+				workspace_id text not null,
+				runtime_id text not null,
+				actor_id text not null,
+				timestamp integer not null,
+				type text not null,
+				payload_json text not null,
+				caused_by text,
+				correlation_id text,
+				thread_id text,
+				schema_version integer not null default 1,
+				idempotency_key text
+			);
+			create index if not exists idx_events_workspace_sequence on events(workspace_id, sequence);
+			create unique index if not exists uniq_events_workspace_sequence on events(workspace_id, sequence);
+			create index if not exists idx_events_workspace_type_sequence on events(workspace_id, type, sequence);
+			create index if not exists idx_events_caused_by on events(caused_by);
+			create index if not exists idx_events_correlation on events(correlation_id);
+			create unique index if not exists idx_events_workspace_idempotency
+				on events(workspace_id, idempotency_key)
+				where idempotency_key is not null;
+		`);
+        // Migrate legacy column name session_hint → thread_id.
+        // session_hint was always NULL in shipped code (isolation was never active),
+        // so this is a safe rename with no data loss.
+        const columns = this.db.prepare("pragma table_info(events)").all();
+        if (columns.some((c) => c.name === "session_hint") && !columns.some((c) => c.name === "thread_id")) {
+            this.db.exec("alter table events rename column session_hint to thread_id");
+        }
+    }
+    _normalizeEvent(partial) {
+        return {
+            ...partial,
+            sequence: partial.sequence ?? this.head_sequence + 1,
+            event_id: partial.event_id ?? uuidv7(),
+            workspace_id: this.workspace_id,
+            runtime_id: partial.runtime_id ?? this.runtimeId,
+            timestamp: partial.timestamp ?? Date.now(),
+            schema_version: partial.schema_version ?? 1,
+        };
+    }
+    _insert(event) {
+        this.db.prepare(`
+			insert into events (
+				sequence, event_id, workspace_id, runtime_id, actor_id, timestamp, type,
+				payload_json, caused_by, correlation_id, thread_id, schema_version, idempotency_key
+			) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`).run(event.sequence, event.event_id, event.workspace_id, event.runtime_id, event.actor_id, event.timestamp, event.type, JSON.stringify(event.payload), event.caused_by ?? null, event.correlation_id ?? null, event.thread_id ?? null, event.schema_version, event.idempotency_key ?? null);
+    }
+    _getByIdempotencyKey(idempotencyKey) {
+        const row = this.db
+            .prepare("select * from events where workspace_id = ? and idempotency_key = ?")
+            .get(this.workspace_id, idempotencyKey);
+        return row ? rowToEvent(row) : undefined;
+    }
+    _notify(event) {
+        for (const [, sub] of this.subscribers) {
+            if (matchesSubscription(event, sub.options)) {
+                sub.handler(event);
+            }
+        }
+    }
+}
+function rowToEvent(row) {
+    return {
+        sequence: row.sequence,
+        event_id: row.event_id,
+        workspace_id: row.workspace_id,
+        runtime_id: row.runtime_id,
+        actor_id: row.actor_id,
+        timestamp: row.timestamp,
+        type: row.type,
+        payload: JSON.parse(row.payload_json),
+        caused_by: row.caused_by ?? undefined,
+        correlation_id: row.correlation_id ?? undefined,
+        thread_id: row.thread_id ?? undefined,
+        schema_version: row.schema_version,
+        idempotency_key: row.idempotency_key ?? undefined,
+    };
+}
+function matchesSubscription(event, options) {
+    if (!options)
+        return true;
+    if (options.after && event.event_id <= options.after)
+        return false;
+    if (options.after_sequence !== undefined && event.sequence <= options.after_sequence)
+        return false;
+    if (options.types?.length && !options.types.includes(event.type))
+        return false;
+    if (options.actor_ids?.length && !options.actor_ids.includes(event.actor_id))
+        return false;
+    return true;
+}
+function loadDatabaseSync() {
+    if (!DatabaseSyncCtor) {
+        DatabaseSyncCtor = require("node:sqlite").DatabaseSync;
+    }
+    return DatabaseSyncCtor;
+}
+export function createEventStore(cwd, agentDir, runtimeId) {
+    const workspaceId = deriveWorkspaceId(cwd);
+    return new SqliteEventStore(workspaceId, getEventDatabasePath(workspaceId, agentDir), runtimeId);
+}

package/dist/core/event-store/store.d.ts

@@ -0,0 +1,91 @@
+/**
+ * EventStore Interface
+ *
+ * The single source of truth for all events in the event-sourced architecture.
+ * All observable state can be derived from the event log.
+ */
+import type { EventBase, EventType } from "./types.js";
+/** EventStore query filter */
+export interface EventQuery {
+    /** Sequence range, workspace-local and monotonic */
+    after_sequence?: number;
+    before_sequence?: number;
+    /** Time range (by event_id, UUIDv7 is time-ordered) */
+    after?: string;
+    before?: string;
+    /** Filter by event types */
+    types?: EventType[];
+    /** Filter by actor */
+    actor_ids?: string[];
+    /** Filter by causal chain (return all descendants of this event) */
+    caused_by?: string;
+    /** Filter by thread (isolation key) */
+    thread_id?: string;
+    /** Maximum number of events to return */
+    limit?: number;
+    /** Return events in reverse order */
+    reverse?: boolean;
+}
+/** EventStore subscription options */
+export interface SubscribeOptions {
+    /** Start receiving events after this event_id (exclusive) */
+    after?: string;
+    /** Start receiving events after this sequence (exclusive) */
+    after_sequence?: number;
+    /** Filter by event types */
+    types?: EventType[];
+    /** Filter by actor */
+    actor_ids?: string[];
+}
+/**
+ * EventStore - the single source of truth for all events.
+ *
+ * Responsibilities:
+ * - Append-only event storage
+ * - Query by various filters
+ * - Real-time subscription to new events
+ * - Causal chain traversal
+ */
+export interface EventStore {
+    /** Workspace identifier */
+    readonly workspace_id: string;
+    /**
+     * Append a new event.
+     * Returns the complete event with generated event_id and timestamp.
+     */
+    append(event: EventAppendInput): EventBase;
+    /**
+     * Batch append multiple events.
+     * Returns the complete events with generated IDs and timestamps.
+     */
+    appendBatch(events: EventAppendInput[]): EventBase[];
+    /**
+     * Query events by filter.
+     */
+    query(filter: EventQuery): EventBase[];
+    /**
+     * Get a single event by ID.
+     */
+    get(event_id: string): EventBase | undefined;
+    /**
+     * Get the latest N events.
+     */
+    latest(count: number): EventBase[];
+    /**
+     * Get the causal chain from this event to root.
+     * Returns events in order from root to this event.
+     */
+    getCausalChain(event_id: string): EventBase[];
+    /**
+     * Subscribe to real-time events.
+     * Returns an unsubscribe function.
+     */
+    subscribe(handler: (event: EventBase) => void, options?: SubscribeOptions): () => void;
+    /** Current total event count */
+    readonly size: number;
+    /** Latest event_id, or undefined if empty */
+    readonly head: string | undefined;
+    /** Latest workspace-local sequence, or 0 if empty */
+    readonly head_sequence: number;
+}
+export type EventAppendInput = Omit<EventBase, "event_id" | "timestamp" | "workspace_id" | "sequence" | "runtime_id" | "schema_version"> & Partial<Pick<EventBase, "event_id" | "timestamp" | "sequence" | "runtime_id" | "schema_version">>;

package/dist/core/event-store/store.js

@@ -0,0 +1,7 @@
+/**
+ * EventStore Interface
+ *
+ * The single source of truth for all events in the event-sourced architecture.
+ * All observable state can be derived from the event log.
+ */
+export {};

package/dist/core/event-store/thread-scoped-store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ThreadScopedStore
+ *
+ * Wraps an EventStore to automatically tag every appended event with a
+ * `thread_id`. This is the isolation mechanism for single-workspace
+ * multi-thread: all threads share one SQLite event log, but each thread's
+ * events are tagged, and SessionProjection.buildContext() filters by it.
+ *
+ * Read operations (query, get, subscribe, etc.) delegate to the inner store
+ * unchanged — callers add `thread_id` to their own queries when needed.
+ */
+import type { EventBase } from "./types.js";
+import type { EventAppendInput, EventQuery, EventStore, SubscribeOptions } from "./store.js";
+export declare class ThreadScopedStore implements EventStore {
+    private readonly inner;
+    private readonly threadId;
+    constructor(inner: EventStore, threadId: string);
+    get workspace_id(): string;
+    append(event: EventAppendInput): EventBase;
+    appendBatch(events: EventAppendInput[]): EventBase[];
+    query(filter: EventQuery): EventBase[];
+    get(event_id: string): EventBase | undefined;
+    latest(count: number): EventBase[];
+    getCausalChain(event_id: string): EventBase[];
+    subscribe(handler: (event: EventBase) => void, options?: SubscribeOptions): () => void;
+    get size(): number;
+    get head(): string | undefined;
+    get head_sequence(): number;
+}

package/dist/core/event-store/thread-scoped-store.js

@@ -0,0 +1,50 @@
+/**
+ * ThreadScopedStore
+ *
+ * Wraps an EventStore to automatically tag every appended event with a
+ * `thread_id`. This is the isolation mechanism for single-workspace
+ * multi-thread: all threads share one SQLite event log, but each thread's
+ * events are tagged, and SessionProjection.buildContext() filters by it.
+ *
+ * Read operations (query, get, subscribe, etc.) delegate to the inner store
+ * unchanged — callers add `thread_id` to their own queries when needed.
+ */
+export class ThreadScopedStore {
+    constructor(inner, threadId) {
+        this.inner = inner;
+        this.threadId = threadId;
+    }
+    get workspace_id() {
+        return this.inner.workspace_id;
+    }
+    append(event) {
+        return this.inner.append({ ...event, thread_id: this.threadId });
+    }
+    appendBatch(events) {
+        return this.inner.appendBatch(events.map((e) => ({ ...e, thread_id: this.threadId })));
+    }
+    query(filter) {
+        return this.inner.query(filter);
+    }
+    get(event_id) {
+        return this.inner.get(event_id);
+    }
+    latest(count) {
+        return this.inner.latest(count);
+    }
+    getCausalChain(event_id) {
+        return this.inner.getCausalChain(event_id);
+    }
+    subscribe(handler, options) {
+        return this.inner.subscribe(handler, options);
+    }
+    get size() {
+        return this.inner.size;
+    }
+    get head() {
+        return this.inner.head;
+    }
+    get head_sequence() {
+        return this.inner.head_sequence;
+    }
+}

package/dist/core/event-store/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Event-Sourced Runtime Types
+ *
+ * This module defines the core types for the event-sourced architecture.
+ * All events are immutable, append-only, causally linked, and timestamped.
+ */
+/** All event base interface - immutable, append-only, causally linked */
+export interface EventBase {
+    /** Workspace-local monotonic sequence number */
+    sequence: number;
+    /** Global unique event ID (UUIDv7, time-ordered) */
+    event_id: string;
+    /** Workspace identifier (one cwd = one workspace) */
+    workspace_id: string;
+    /** Runtime instance that produced this event */
+    runtime_id: string;
+    /** Actor that produced this event */
+    actor_id: ActorId;
+    /** Unix ms timestamp */
+    timestamp: number;
+    /** Event type */
+    type: EventType;
+    /** Event payload (structure determined by type) */
+    payload: unknown;
+    /** Causal chain: event_id that triggered this event */
+    caused_by?: string;
+    /** Trace identifier for a user turn, scheduled tick, webhook, or goal run */
+    correlation_id?: string;
+    /** Thread this event belongs to (isolation key; one conversation = one thread_id). Events of a thread are visible only to that thread's sessions. */
+    thread_id?: string;
+    /** Event payload schema version */
+    schema_version: number;
+    /** Optional retry-safe deduplication key */
+    idempotency_key?: string;
+}
+/** Actor identifier */
+export type ActorId = "user" | "coder_agent" | "runtime" | "compactor" | string;
+/** All event types */
+export type EventType = "USER_MESSAGE" | "USER_APPROVAL" | "USER_REJECTION" | "USER_INTERRUPT" | "USER_FOLLOWUP_QUEUED" | "USER_CONFIG_CHANGE" | "AGENT_TURN_REQUESTED" | "AGENT_TURN_COMPLETED" | "LLM_CALL_REQUESTED" | "LLM_CALL_FAILED" | "TOOL_RESULTS_AGGREGATED" | "RETRY_SCHEDULED" | "RETRY_ABORTED" | "AGENT_THINKING_START" | "AGENT_THINKING_END" | "AGENT_MESSAGE_START" | "AGENT_MESSAGE_CHUNK" | "AGENT_MESSAGE_END" | "AGENT_TURN_START" | "AGENT_TURN_END" | "AGENT_ERROR" | "INTENT_TOOL_CALL" | "INTENT_FILE_EDIT" | "INTENT_COMMAND_EXEC" | "TOOL_EXECUTION_START" | "TOOL_EXECUTION_UPDATE" | "TOOL_EXECUTION_END" | "FILE_MUTATION_APPLIED" | "BASH_EXECUTION" | "CUSTOM_MESSAGE" | "BRANCH_SUMMARY" | "COMMAND_EXECUTED" | "SESSION_CREATED" | "SESSION_BOUNDARY_INFERRED" | "SESSION_FORKED" | "SESSION_ENTRY_APPENDED" | "COMPACTION_REQUESTED" | "COMPACTION_START" | "COMPACTION_END" | "COMPACTION_ABORTED" | "RUNTIME_STARTED" | "RUNTIME_PAUSED" | "RUNTIME_RESUMED" | "CHECKPOINT_CREATED" | "CHECKPOINT_RESTORED" | "CHECKPOINT_FAILED" | "MODEL_CHANGED" | "THINKING_LEVEL_CHANGED" | "RUNTIME_ERROR" | "GOAL_CREATED" | "GOAL_CLASSIFIED" | "GOAL_PLANNED" | "GOAL_PAUSED" | "GOAL_RESUMED" | "GOAL_COMPLETED" | "GOAL_CANCELLED" | "TASK_CREATED" | "TASK_ASSIGNED" | "TASK_STARTED" | "TASK_PROGRESS" | "TASK_COMPLETED" | "TASK_FAILED" | "TASK_REWORK_REQUESTED" | "TASK_ACCEPTED" | "TASK_CANCELLED";
+/** Content block for messages */
+export interface ContentBlock {
+    type: "text" | "image" | "thinking" | "tool_call";
+    [key: string]: unknown;
+}
+/** Token usage statistics */
+export interface TokenUsage {
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+    total: number;
+    cost: number;
+}
+/** File mutation record */
+export interface FileMutation {
+    path: string;
+    operation: "create" | "modify" | "delete";
+    diff?: string;
+}
+/** Memory node reference */
+export interface MemoryNodeRef {
+    node_id: string;
+    type: string;
+}
+/** Image content */
+export interface ImageContent {
+    type: "image";
+    data: string;
+    mime_type: string;
+}

package/dist/core/event-store/types.js

@@ -0,0 +1,7 @@
+/**
+ * Event-Sourced Runtime Types
+ *
+ * This module defines the core types for the event-sourced architecture.
+ * All events are immutable, append-only, causally linked, and timestamped.
+ */
+export {};

package/dist/core/event-store/workspace.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Workspace Identification and Storage Layout
+ *
+ * Provides deterministic workspace_id derivation from cwd and the
+ * standard storage path structure.
+ *
+ * Storage layout:
+ *   <agentDir>/workspaces/<workspace_id>/
+ *     events.sqlite             # Primary event log
+ *     meta.json
+ *     sessions.json
+ */
+/**
+ * workspace_id = deterministic hash of canonical cwd
+ * Same directory always yields the same workspace_id.
+ */
+export declare function deriveWorkspaceId(cwd: string): string;
+/**
+ * Returns the workspace directory:
+ *   <agentDir>/workspaces/<workspace_id>/
+ */
+export declare function getWorkspaceDir(workspaceId: string, agentDir?: string): string;
+/** Returns the primary SQLite event database path for a workspace. */
+export declare function getEventDatabasePath(workspaceId: string, agentDir?: string): string;
+/** Returns the meta.json path for a workspace. */
+export declare function getWorkspaceMetaPath(workspaceId: string, agentDir?: string): string;
+/** Returns the sessions.json path for a workspace. */
+export declare function getSessionIndexPath(workspaceId: string, agentDir?: string): string;
+/** Workspace metadata. */
+export interface WorkspaceMeta {
+    workspace_id: string;
+    cwd: string;
+    created_at: number;
+    last_accessed_at: number;
+}
+/** Read workspace metadata, creating it if absent. */
+export declare function ensureWorkspaceMeta(workspaceId: string, cwd: string, agentDir?: string): WorkspaceMeta;

package/dist/core/event-store/workspace.js

@@ -0,0 +1,71 @@
+/**
+ * Workspace Identification and Storage Layout
+ *
+ * Provides deterministic workspace_id derivation from cwd and the
+ * standard storage path structure.
+ *
+ * Storage layout:
+ *   <agentDir>/workspaces/<workspace_id>/
+ *     events.sqlite             # Primary event log
+ *     meta.json
+ *     sessions.json
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getAgentDir as getDefaultAgentDir } from "../../config.js";
+/**
+ * workspace_id = deterministic hash of canonical cwd
+ * Same directory always yields the same workspace_id.
+ */
+export function deriveWorkspaceId(cwd) {
+    const canonical = resolve(cwd).replace(/\\/g, "/");
+    return `ws_${createHash("sha256").update(canonical).digest("hex").slice(0, 12)}`;
+}
+/**
+ * Returns the workspace directory:
+ *   <agentDir>/workspaces/<workspace_id>/
+ */
+export function getWorkspaceDir(workspaceId, agentDir = getDefaultAgentDir()) {
+    const dir = join(agentDir, "workspaces", workspaceId);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+/** Returns the primary SQLite event database path for a workspace. */
+export function getEventDatabasePath(workspaceId, agentDir) {
+    return join(getWorkspaceDir(workspaceId, agentDir), "events.sqlite");
+}
+/** Returns the meta.json path for a workspace. */
+export function getWorkspaceMetaPath(workspaceId, agentDir) {
+    return join(getWorkspaceDir(workspaceId, agentDir), "meta.json");
+}
+/** Returns the sessions.json path for a workspace. */
+export function getSessionIndexPath(workspaceId, agentDir) {
+    return join(getWorkspaceDir(workspaceId, agentDir), "sessions.json");
+}
+/** Read workspace metadata, creating it if absent. */
+export function ensureWorkspaceMeta(workspaceId, cwd, agentDir) {
+    const path = getWorkspaceMetaPath(workspaceId, agentDir);
+    if (existsSync(path)) {
+        try {
+            const raw = readFileSync(path, "utf8");
+            const meta = JSON.parse(raw);
+            meta.last_accessed_at = Date.now();
+            writeFileSync(path, JSON.stringify(meta, null, 2));
+            return meta;
+        }
+        catch {
+            // fall through to create
+        }
+    }
+    const meta = {
+        workspace_id: workspaceId,
+        cwd,
+        created_at: Date.now(),
+        last_accessed_at: Date.now(),
+    };
+    writeFileSync(path, JSON.stringify(meta, null, 2));
+    return meta;
+}

package/dist/core/exec.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared command execution utilities for extensions and custom tools.
+ */
+/**
+ * Options for executing shell commands.
+ */
+export interface ExecOptions {
+    /** AbortSignal to cancel the command */
+    signal?: AbortSignal;
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** Working directory */
+    cwd?: string;
+}
+/**
+ * Result of executing a shell command.
+ */
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+    killed: boolean;
+}
+/**
+ * Execute a shell command and return stdout/stderr/code.
+ * Supports timeout and abort signal.
+ */
+export declare function execCommand(command: string, args: string[], cwd: string, options?: ExecOptions): Promise<ExecResult>;