@plico-ai/server 0.0.0-reserved.0 → 0.1.0

package/NOTICE

@@ -0,0 +1,4 @@
+Plico
+Copyright 2026 Plico contributors
+
+This product includes software developed by the Plico contributors.

package/README.md

@@ -1,6 +1,11 @@
 # @plico-ai/server
 
-The Plico HTTP API and embeddable library.
+The thin native HTTP API over the Plico runtime and event store: runs, threads, signals, approvals, cancel, artifacts, events and readiness.
 
-This is a pre-release placeholder. The first developer preview is in progress at
-https://github.com/ITZSHOAIB/plico. Docs: https://plico.sohab.dev
+Embed it in your own Node backend with `createPlico({ projectRoot, databasePath })`, which returns `threads`, `runs` (including `runs.events()`, an async iterator over a run's events), `approvals` and `close()`. Files define the agent; the library only runs it. `plico.fetch()` and `plico.node()` mount the `/v1` API in Express, Hono, Next.js and similar hosts, with a per-request `scope` and `context`. `servePlico` is `createPlico` plus an HTTP listener.
+
+Threads and runs take a host `metadata` JSON object at creation (immutable; lists filter by exact match on top-level keys). A run takes a `context` that tools read as `ctx.context`; it is recorded on `run.started`, so it must not carry secrets. See `docs/threads.md`.
+
+Start the HTTP server with `plico serve [path]` from [`@plico-ai/cli`](../cli). It binds to loopback by default and rejects cross-origin and DNS-rebinding requests unless `--allow-remote` is set. Run requests that carry a `script` are refused with 403 `run.script_disabled` unless `--allow-script` (`allowScript: true`) is set.
+
+Requires Node `>=22.18`. Wire types come from `@plico-ai/contracts`.

package/dist/api.d.ts

@@ -0,0 +1,32 @@
+import { Hono } from "hono";
+import type { PlicoInternals } from "./app/assemble.js";
+import type { Metadata } from "./app/metadata.js";
+/** What a host computes from each request on a mounted API. */
+export type RequestData = (request: Request) => Metadata | undefined | Promise<Metadata | undefined>;
+/** The HTTP-only options. A library embedder never sets these. */
+export interface ListenerOptions {
+    studioPath?: string;
+    /**
+     * Skip the loopback `Host` check. Set it when the server is deliberately reachable under another
+     * name, for example behind a host app's own authentication. Cross-origin requests stay refused.
+     */
+    allowRemote?: boolean;
+    /**
+     * The origin browsers use to reach this server, such as `https://plico.example` when TLS ends at
+     * a proxy. A request `Origin` must match it exactly, scheme and port included. Without it, the
+     * scheme of the connection and the `Host` header decide.
+     */
+    publicOrigin?: string;
+    /**
+     * Accept a `script` on `POST /v1/runs` and `POST /v1/runs/dry`. A script calls project tool
+     * handlers with arguments the caller chooses and skips the model, so it is off by default.
+     */
+    allowScript?: boolean;
+    /** Computed per request on a mounted API; see `MountOptions`. */
+    scope?: RequestData;
+    context?: RequestData;
+    /** The path the API is mounted under, removed before routing. */
+    basePath?: string;
+}
+/** The `/v1` API, and Studio when `studioPath` is set, over one `Plico`, as a Hono app. */
+export declare function createApi({ deps, stop }: PlicoInternals, options?: ListenerOptions): Hono;

package/dist/api.js

@@ -0,0 +1,87 @@
+import { Hono } from "hono";
+import { readMetadata } from "./app/metadata.js";
+import { errorResponse, HttpError } from "./errors.js";
+import { assertTrustedRequest } from "./origin-guard.js";
+import { handleRequest } from "./routes/index.js";
+import { serveStaticFile } from "./serve-static.js";
+/** The `/v1` API, and Studio when `studioPath` is set, over one `Plico`, as a Hono app. */
+export function createApi({ deps, stop }, options = {}) {
+    const { studioPath } = options;
+    const api = new Hono();
+    api.use("*", async (context, next) => {
+        try {
+            assertTrustedRequest(context.req.raw, {
+                allowRemote: options.allowRemote === true,
+                publicOrigin: options.publicOrigin,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof HttpError))
+                throw error;
+            return errorResponse(error.status, error.code, error.message);
+        }
+        await next();
+    });
+    api.all("*", async (context) => {
+        const request = withoutBasePath(context.req.raw, options.basePath);
+        const url = new URL(request.url);
+        const isApiPath = url.pathname === "/health" || url.pathname.startsWith("/v1/");
+        const route = async () => {
+            try {
+                return await handleRequest({
+                    app: await requestDeps(deps, request, options),
+                    stop,
+                    studioPath,
+                    allowScript: options.allowScript === true,
+                    request,
+                });
+            }
+            catch (error) {
+                if (!(error instanceof HttpError))
+                    throw error;
+                return errorResponse(error.status, error.code, error.message);
+            }
+        };
+        if (isApiPath || !studioPath)
+            return route();
+        return ((await serveStaticFile(studioPath, url.pathname)) ??
+            (await serveStaticFile(studioPath, "/index.html")) ??
+            route());
+    });
+    return api;
+}
+/**
+ * The deps for one request. A host function that fails or returns something other than a JSON
+ * object ends the request: an unreadable scope must never mean "no scope".
+ */
+async function requestDeps(deps, request, options) {
+    if (!options.scope && !options.context)
+        return deps;
+    try {
+        const scope = options.scope ? readMetadata(await options.scope(request), "scope") : undefined;
+        if (options.scope && scope === undefined)
+            throw new TypeError("scope must be a JSON object.");
+        const context = options.context
+            ? readMetadata(await options.context(request), "context")
+            : undefined;
+        return {
+            ...deps,
+            ...(scope === undefined ? {} : { scope }),
+            ...(context === undefined ? {} : { context }),
+        };
+    }
+    catch (error) {
+        console.error(`plico: could not compute scope or context: ${error instanceof Error ? error.message : String(error)}`);
+        throw new HttpError(500, "server.error", "Internal server error.");
+    }
+}
+function withoutBasePath(request, basePath) {
+    const prefix = basePath?.replace(/\/+$/, "");
+    if (!prefix)
+        return request;
+    const url = new URL(request.url);
+    if (url.pathname !== prefix && !url.pathname.startsWith(`${prefix}/`))
+        return request;
+    url.pathname = url.pathname.slice(prefix.length) || "/";
+    return new Request(url, request);
+}

package/dist/app/assemble.d.ts

@@ -0,0 +1,10 @@
+import type { AppDeps, Plico } from "./types.js";
+/** What the HTTP listener needs behind a `Plico`. Never part of the public surface. */
+export interface PlicoInternals {
+    deps: AppDeps;
+    /** Aborts when `close()` starts, so open event streams end. */
+    stop: AbortSignal;
+}
+export declare function internalsOf(plico: Plico): PlicoInternals;
+/** Builds the programmatic API over stores that already exist. `onClose` releases what they hold. */
+export declare function assemblePlico(appDeps: AppDeps, onClose?: () => void | Promise<void>): Plico;

package/dist/app/assemble.js

@@ -0,0 +1,49 @@
+import { createFetchHandler, createNodeHandler } from "../mount.js";
+import { withThreadTitles } from "../thread-titles.js";
+import { followEvents } from "./events.js";
+import { cancelRun, decideApproval, listRuns, startRun } from "./runs.js";
+import { createThread, getThread, listThreads, renameThread, sendMessage, threadMessages, } from "./threads.js";
+const registry = new WeakMap();
+export function internalsOf(plico) {
+    const internals = registry.get(plico);
+    if (!internals)
+        throw new TypeError("Not a Plico instance created by this package.");
+    return internals;
+}
+/** Builds the programmatic API over stores that already exist. `onClose` releases what they hold. */
+export function assemblePlico(appDeps, onClose = () => { }) {
+    const deps = { ...appDeps, eventStore: withThreadTitles(appDeps) };
+    const stopper = new AbortController();
+    let closing;
+    const plico = {
+        threads: {
+            create: (options) => createThread(deps, options),
+            get: (threadId) => getThread(deps, threadId),
+            list: (filter) => listThreads(deps, filter),
+            rename: (threadId, title) => renameThread(deps, threadId, title),
+            messages: (threadId) => threadMessages(deps, threadId),
+            send: (threadId, content, options) => sendMessage(deps, threadId, content, options),
+        },
+        runs: {
+            start: (options) => startRun(deps, options),
+            get: (runId) => deps.eventStore.getRun(runId),
+            list: (filter) => listRuns(deps, filter),
+            cancel: (runId) => cancelRun(deps, runId),
+            events: (runId, options) => followEvents(deps, runId, { ...options, stop: stopper.signal }),
+        },
+        approvals: {
+            decide: (runId, requestId, approved, options) => decideApproval(deps, runId, requestId, approved, options),
+        },
+        fetch: (options) => createFetchHandler({ deps, stop: stopper.signal }, options),
+        node: (options) => createNodeHandler({ deps, stop: stopper.signal }, options),
+        close() {
+            closing ??= (async () => {
+                stopper.abort();
+                await onClose();
+            })();
+            return closing;
+        },
+    };
+    registry.set(plico, { deps, stop: stopper.signal });
+    return plico;
+}

package/dist/app/errors.d.ts

@@ -0,0 +1,6 @@
+/** A failure the shared layer reports by code. The HTTP routes map the code to a status. */
+export declare class PlicoError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function statusForCode(code: string): number;

package/dist/app/errors.js

@@ -0,0 +1,24 @@
+/** A failure the shared layer reports by code. The HTTP routes map the code to a status. */
+export class PlicoError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const statusByCode = {
+    "thread.not_found": 404,
+    "run.not_found": 404,
+    "workspace.not_found": 404,
+    "thread.busy": 409,
+    "thread.invalid_title": 400,
+    "message.invalid": 400,
+    "request.invalid": 400,
+    "threads.unavailable": 503,
+    "threads.store_mismatch": 503,
+    "provider.unavailable": 503,
+    "workspace.unavailable": 503,
+};
+export function statusForCode(code) {
+    return statusByCode[code] ?? 500;
+}

package/dist/app/events.d.ts

@@ -0,0 +1,9 @@
+import type { PlicoEvent } from "@plico-ai/contracts";
+import type { AppDeps, EventFollowOptions } from "./types.js";
+/**
+ * Yields a run's events from a cursor and ends after its terminal event. The first read happens
+ * on the first `next()`, so callers that need a 404 before writing anything check the run first.
+ */
+export declare function followEvents(deps: Pick<AppDeps, "eventStore" | "scope">, runId: string, options: EventFollowOptions & {
+    stop: AbortSignal;
+}): AsyncGenerator<PlicoEvent, void, void>;

package/dist/app/events.js

@@ -0,0 +1,52 @@
+import { PlicoError } from "./errors.js";
+import { inScope } from "./scope.js";
+// Waiting is not terminal: the stream stays open for approval (#69). run.error is followed by
+// run.failed, which closes the stream.
+const terminalEventTypes = [
+    "run.completed",
+    "run.failed",
+    "run.cancelled",
+];
+const terminalStatuses = ["completed", "failed", "cancelled"];
+/**
+ * Yields a run's events from a cursor and ends after its terminal event. The first read happens
+ * on the first `next()`, so callers that need a 404 before writing anything check the run first.
+ */
+export async function* followEvents(deps, runId, options) {
+    const { eventStore } = deps;
+    const stop = options.signal ? AbortSignal.any([options.signal, options.stop]) : options.stop;
+    const pollMs = options.pollMs ?? 2000;
+    const first = await eventStore.getRun(runId);
+    if (!first || !inScope(deps, first.metadata))
+        throw new PlicoError("run.not_found", `Unknown run ID: ${runId}`);
+    let cursor = options.after ?? 0;
+    while (!stop.aborted) {
+        const events = await eventStore.getEvents(runId, { afterSequence: cursor });
+        for (const event of events) {
+            yield event;
+            cursor = event.sequence;
+        }
+        if (events.some((event) => terminalEventTypes.includes(event.type)))
+            return;
+        const run = await eventStore.getRun(runId);
+        if (run && terminalStatuses.includes(run.status)) {
+            for (const event of await eventStore.getEvents(runId, { afterSequence: cursor }))
+                yield event;
+            return;
+        }
+        await sleep(pollMs, stop);
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done);
+    });
+}

package/dist/app/metadata.d.ts

@@ -0,0 +1,4 @@
+import type { JsonValue } from "@plico-ai/contracts";
+export type Metadata = Record<string, JsonValue>;
+/** Accepts a plain JSON object and returns it; anything else is a `request.invalid` error. */
+export declare function readMetadata(value: unknown, name?: string): Metadata | undefined;

package/dist/app/metadata.js

@@ -0,0 +1,24 @@
+import { PlicoError } from "./errors.js";
+/** Accepts a plain JSON object and returns it; anything else is a `request.invalid` error. */
+export function readMetadata(value, name = "metadata") {
+    if (value === undefined)
+        return undefined;
+    if (!isPlainObject(value) || !isJson(value))
+        throw new PlicoError("request.invalid", `${name} must be a JSON object.`);
+    return value;
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function isJson(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJson);
+    return isPlainObject(value) && Object.values(value).every(isJson);
+}

package/dist/app/runs.d.ts

@@ -0,0 +1,31 @@
+import type { PlicoEvent, RunSummary } from "@plico-ai/contracts";
+import { type DryRunScriptStep, type RunResult } from "@plico-ai/runtime";
+import type { AppDeps } from "./types.js";
+export declare function startRun(deps: AppDeps, options?: {
+    script?: DryRunScriptStep[];
+    mockTools?: boolean;
+    metadata?: unknown;
+    context?: unknown;
+}): Promise<{
+    runId: string;
+}>;
+/** Runs the project to the end without a model and returns its result. */
+export declare function runDry(deps: AppDeps, options?: {
+    script?: DryRunScriptStep[];
+    mockTools?: boolean;
+}): Promise<RunResult>;
+export declare function listRuns(deps: AppDeps, filter?: {
+    metadata?: unknown;
+}): Promise<RunSummary[]>;
+export declare function requireRun(deps: AppDeps, runId: string): Promise<RunSummary>;
+export declare function cancelRun(deps: AppDeps, runId: string): Promise<string>;
+/**
+ * Sends a client's signal. An approval signal from a client carries no `context` of its own: only
+ * the host may say who decided, through `decideApproval` or the `context` of a mounted handler.
+ */
+export declare function signalRun(deps: AppDeps, runId: string, name: string, value: unknown): Promise<string>;
+/** Approval decisions are signals on the wait named `approval:<requestId>` (ADR 0008). */
+export declare function decideApproval(deps: AppDeps, runId: string, requestId: string, approved: boolean, options?: {
+    context?: unknown;
+}): Promise<string>;
+export declare function listRunEvents(deps: AppDeps, runId: string, afterSequence?: number): Promise<PlicoEvent[]>;

package/dist/app/runs.js

@@ -0,0 +1,81 @@
+import { runProject } from "@plico-ai/runtime";
+import { PlicoError } from "./errors.js";
+import { readMetadata } from "./metadata.js";
+import { inScope, scopedFilter, scopedMetadata } from "./scope.js";
+export async function startRun(deps, options = {}) {
+    const metadata = scopedMetadata(deps, readMetadata(options.metadata));
+    const context = readMetadata(options.context, "context") ?? deps.context;
+    let resolveStarted;
+    let rejectStarted;
+    const started = new Promise((resolve, reject) => {
+        resolveStarted = resolve;
+        rejectStarted = reject;
+    });
+    void runProject(deps.projectRoot, {
+        eventStore: deps.eventStore,
+        engine: deps.engine,
+        ...(options.script === undefined ? {} : { script: options.script }),
+        ...(options.mockTools === true ? { mockTools: true } : {}),
+        ...(metadata === undefined ? {} : { metadata }),
+        ...(context === undefined ? {} : { context }),
+        onStarted: resolveStarted,
+    }).catch(rejectStarted);
+    return { runId: await started };
+}
+/** Runs the project to the end without a model and returns its result. */
+export function runDry(deps, options = {}) {
+    return runProject(deps.projectRoot, {
+        ...(options.script === undefined ? {} : { script: options.script }),
+        ...(options.mockTools === true ? { mockTools: true } : {}),
+        eventStore: deps.eventStore,
+        engine: deps.engine,
+    });
+}
+export async function listRuns(deps, filter = {}) {
+    const metadata = scopedFilter(deps, readMetadata(filter.metadata));
+    return deps.eventStore.listRuns(metadata === undefined ? {} : { metadata });
+}
+export async function requireRun(deps, runId) {
+    const run = await deps.eventStore.getRun(runId);
+    if (!run || !inScope(deps, run.metadata))
+        throw new PlicoError("run.not_found", `Unknown run ID: ${runId}`);
+    return run;
+}
+export async function cancelRun(deps, runId) {
+    await requireRun(deps, runId);
+    return deps.engine.cancel(runId);
+}
+/**
+ * Sends a client's signal. An approval signal from a client carries no `context` of its own: only
+ * the host may say who decided, through `decideApproval` or the `context` of a mounted handler.
+ */
+export function signalRun(deps, runId, name, value) {
+    const clean = name.startsWith("approval:") &&
+        typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value)
+        ? {
+            ...Object.fromEntries(Object.entries(value).filter(([key]) => key !== "context")),
+            ...(deps.context === undefined ? {} : { context: deps.context }),
+        }
+        : value;
+    return sendSignal(deps, runId, name, clean);
+}
+async function sendSignal(deps, runId, name, value) {
+    await requireRun(deps, runId);
+    if (!name)
+        throw new PlicoError("request.invalid", "A signal name is required.");
+    return deps.engine.signal(runId, name, value);
+}
+/** Approval decisions are signals on the wait named `approval:<requestId>` (ADR 0008). */
+export function decideApproval(deps, runId, requestId, approved, options = {}) {
+    const context = readMetadata(options.context, "context") ?? deps.context;
+    return sendSignal(deps, runId, `approval:${requestId}`, {
+        approved,
+        ...(context === undefined ? {} : { context }),
+    });
+}
+export async function listRunEvents(deps, runId, afterSequence) {
+    await requireRun(deps, runId);
+    return deps.eventStore.getEvents(runId, afterSequence === undefined ? {} : { afterSequence });
+}

package/dist/app/scope.d.ts

@@ -0,0 +1,8 @@
+import type { Metadata } from "./metadata.js";
+import type { AppDeps } from "./types.js";
+/** True when the request's scope allows an item with this metadata. Without a scope, always. */
+export declare function inScope(deps: Pick<AppDeps, "scope">, metadata: Metadata | undefined): boolean;
+/** The metadata a new thread or run gets. A scope owns it; a scoped client cannot set its own. */
+export declare function scopedMetadata(deps: Pick<AppDeps, "scope">, requested: Metadata | undefined): Metadata | undefined;
+/** A list filter narrowed by the scope. The scope's keys win, so a client cannot widen it. */
+export declare function scopedFilter(deps: Pick<AppDeps, "scope">, requested: Metadata | undefined): Metadata | undefined;

package/dist/app/scope.js

@@ -0,0 +1,18 @@
+import { matchesMetadata } from "@plico-ai/runtime";
+import { PlicoError } from "./errors.js";
+/** True when the request's scope allows an item with this metadata. Without a scope, always. */
+export function inScope(deps, metadata) {
+    return deps.scope === undefined || matchesMetadata(metadata, deps.scope);
+}
+/** The metadata a new thread or run gets. A scope owns it; a scoped client cannot set its own. */
+export function scopedMetadata(deps, requested) {
+    if (deps.scope === undefined)
+        return requested;
+    if (requested !== undefined)
+        throw new PlicoError("request.invalid", "metadata is set by the host through scope.");
+    return deps.scope;
+}
+/** A list filter narrowed by the scope. The scope's keys win, so a client cannot widen it. */
+export function scopedFilter(deps, requested) {
+    return deps.scope === undefined ? requested : { ...requested, ...deps.scope };
+}

package/dist/app/threads.d.ts

@@ -0,0 +1,15 @@
+import type { Thread, ThreadArtifactWorkspace, ThreadMessage } from "@plico-ai/contracts";
+import type { AppDeps, SendMessageOptions } from "./types.js";
+export declare function requireThread(deps: AppDeps, threadId: string): Promise<Thread>;
+export declare function createThread(deps: AppDeps, options?: {
+    metadata?: unknown;
+}): Promise<Thread>;
+export declare function getThread(deps: AppDeps, threadId: string): Promise<Thread | undefined>;
+export declare function listThreads(deps: AppDeps, filter?: {
+    metadata?: unknown;
+}): Promise<Thread[]>;
+export declare function renameThread(deps: AppDeps, threadId: string, title: unknown): Promise<Thread>;
+export declare function threadMessages(deps: AppDeps, threadId: string): Promise<ThreadMessage[]>;
+export declare function threadWorkspace(deps: AppDeps, threadId: string): Promise<ThreadArtifactWorkspace>;
+/** Records a user message and, unless told not to, starts the run that answers it. */
+export declare function sendMessage(deps: AppDeps, threadId: string, content: unknown, options?: SendMessageOptions): Promise<ThreadMessage>;

package/dist/app/threads.js

@@ -0,0 +1,133 @@
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { buildArtifactWorkspace, runProject, ThreadBusyError } from "@plico-ai/runtime";
+import { finishFailedThreadRun } from "../thread-failure.js";
+import { PlicoError } from "./errors.js";
+import { readMetadata } from "./metadata.js";
+import { inScope, scopedFilter, scopedMetadata } from "./scope.js";
+const maxTitleLength = 200;
+function storeFor(deps) {
+    if (!deps.threadStore)
+        throw new PlicoError("threads.unavailable", "Thread storage is unavailable.");
+    return deps.threadStore;
+}
+export async function requireThread(deps, threadId) {
+    const thread = await storeFor(deps).getThread(threadId);
+    if (!thread || !inScope(deps, thread.metadata))
+        throw new PlicoError("thread.not_found", `Unknown thread ID: ${threadId}`);
+    return thread;
+}
+export async function createThread(deps, options = {}) {
+    return storeFor(deps).createThread(scopedMetadata(deps, readMetadata(options.metadata)));
+}
+export async function getThread(deps, threadId) {
+    const thread = await storeFor(deps).getThread(threadId);
+    return thread && inScope(deps, thread.metadata) ? thread : undefined;
+}
+export async function listThreads(deps, filter = {}) {
+    const metadata = scopedFilter(deps, readMetadata(filter.metadata));
+    return storeFor(deps).listThreads(metadata === undefined ? {} : { metadata });
+}
+export async function renameThread(deps, threadId, title) {
+    const thread = await requireThread(deps, threadId);
+    const trimmed = typeof title === "string" ? title.trim() : "";
+    if (!trimmed || trimmed.length > maxTitleLength)
+        throw new PlicoError("thread.invalid_title", `Title must be a nonempty string of at most ${maxTitleLength} characters.`);
+    const renamed = await storeFor(deps).renameThread(thread.id, trimmed);
+    if (!renamed)
+        throw new PlicoError("thread.not_found", `Unknown thread ID: ${threadId}`);
+    return renamed;
+}
+export async function threadMessages(deps, threadId) {
+    const thread = await requireThread(deps, threadId);
+    return storeFor(deps).getMessages(thread.id);
+}
+export async function threadWorkspace(deps, threadId) {
+    const thread = await requireThread(deps, threadId);
+    if (!deps.eventStore.getThreadRunEvents)
+        throw new PlicoError("workspace.unavailable", "Thread workspace projection is unavailable.");
+    const events = await deps.eventStore.getThreadRunEvents(thread.id);
+    const workspace = buildArtifactWorkspace(thread.id, events);
+    if (!workspace)
+        throw new PlicoError("workspace.not_found", `No artifact workspace for thread: ${thread.id}`);
+    const { runId: _runId, ...threadWorkspace } = workspace;
+    return { ...threadWorkspace, threadId: thread.id };
+}
+/** Records a user message and, unless told not to, starts the run that answers it. */
+export async function sendMessage(deps, threadId, content, options = {}) {
+    const store = storeFor(deps);
+    const thread = await requireThread(deps, threadId);
+    if (typeof content !== "string" || !content.trim())
+        throw new PlicoError("message.invalid", "Message content must be a nonempty string.");
+    const startRun = options.startRun !== false;
+    const context = readMetadata(options.context, "context") ?? deps.context;
+    const { provider } = deps;
+    if (startRun && !provider)
+        throw new PlicoError("provider.unavailable", "Configure a model provider before sending a message.");
+    if (startRun &&
+        (!store.storageIdentity || store.storageIdentity !== deps.eventStore.storageIdentity))
+        throw new PlicoError("threads.store_mismatch", "Thread and run stores must use the same database.");
+    const runId = startRun ? `run-${randomUUID()}` : undefined;
+    const providerKey = deps.providerAccountKey ?? deps.providerRecoveryKey;
+    let message;
+    try {
+        message = await store.addMessage(thread.id, content, runId, providerKey
+            ? {
+                providerKey,
+                projectRoot: resolve(deps.projectRoot),
+                ...(context === undefined ? {} : { context }),
+            }
+            : undefined);
+    }
+    catch (error) {
+        if (error instanceof ThreadBusyError)
+            throw new PlicoError("thread.busy", error.message);
+        throw error;
+    }
+    if (!message)
+        throw new PlicoError("thread.not_found", `Unknown thread ID: ${thread.id}`);
+    if (provider && runId) {
+        const history = (await store.getMessages(thread.id)).filter((entry) => entry.id !== message.id);
+        await startThreadRun(deps, {
+            runId,
+            threadId: thread.id,
+            ...(thread.metadata === undefined ? {} : { metadata: thread.metadata }),
+            ...(context === undefined ? {} : { context }),
+            content,
+            history: history.map(({ role, content }) => ({ role, content })),
+        });
+    }
+    return message;
+}
+async function startThreadRun(deps, run) {
+    let resolveStarted;
+    let rejectStarted;
+    const started = new Promise((resolve, reject) => {
+        resolveStarted = resolve;
+        rejectStarted = reject;
+    });
+    void runProject(deps.projectRoot, {
+        runId: run.runId,
+        threadId: run.threadId,
+        ...(run.metadata === undefined ? {} : { metadata: run.metadata }),
+        ...(run.context === undefined ? {} : { context: run.context }),
+        message: run.content,
+        history: run.history,
+        ...(deps.provider ? { provider: deps.provider } : {}),
+        eventStore: deps.eventStore,
+        engine: deps.engine,
+        ...(deps.providerRecoveryKey ? { providerRecoveryKey: deps.providerRecoveryKey } : {}),
+        onStarted: resolveStarted,
+    }).catch(async (error) => {
+        try {
+            await finishFailedThreadRun(run.runId, run.threadId, deps.projectRoot, deps.engine, deps.eventStore, error, run.metadata);
+        }
+        catch (settleError) {
+            console.error("Could not record failed thread run", settleError);
+        }
+        finally {
+            rejectStarted(error);
+        }
+    });
+    await started;
+}