@plico-ai/server 0.0.0-stage → 0.1.0

package/dist/recovery.js

@@ -0,0 +1,84 @@
+import { resolve } from "node:path";
+import { recoverRuns, runProject, } from "@plico-ai/runtime";
+import { finishFailedThreadRun } from "./thread-failure.js";
+/** Continue runs a dead process left behind, settling any failed thread reservations. */
+export async function recoverPlicoState(options) {
+    const dryRuns = recoverRuns({
+        engine: options.engine,
+        eventStore: options.eventStore,
+        recoveryFilter: { projectRoot: options.projectRoot },
+    });
+    const modelRuns = options.provider && options.providerRecoveryKey
+        ? recoverRuns({
+            engine: options.engine,
+            eventStore: options.eventStore,
+            provider: options.provider,
+            recoveryFilter: {
+                projectRoot: options.projectRoot,
+                providerRecoveryKey: options.providerRecoveryKey,
+                providerOnly: true,
+            },
+        })
+        : Promise.resolve([]);
+    const [dry, model] = await Promise.all([dryRuns, modelRuns]);
+    for (const run of [...dry, ...model]) {
+        if (run.state !== "failed")
+            continue;
+        console.error(`Recovered run ${run.runId}: failed${run.error ? ` (${run.error})` : ""}`);
+        if (!options.threadStore || options.isClosed?.())
+            continue;
+        const threadId = await options.threadStore.getThreadForRun(run.runId);
+        if (!threadId || options.isClosed?.())
+            continue;
+        const metadata = (await options.threadStore.getThread(threadId))?.metadata;
+        await finishFailedThreadRun(run.runId, threadId, options.projectRoot, options.engine, options.eventStore, run.error, metadata);
+    }
+}
+/** Start thread runs that were reserved but never reached the engine. */
+export async function resumeQueuedRuns(options) {
+    if (!options.provider || !options.providerAccountKey || !options.threadStore)
+        return;
+    if (!options.threadStore.storageIdentity ||
+        options.threadStore.storageIdentity !== options.eventStore.storageIdentity)
+        throw new Error("Thread and run stores must use the same database.");
+    const queued = await options.threadStore.listQueuedRuns();
+    for (const run of queued) {
+        if (options.isClosed?.())
+            return;
+        if (!run.projectRoot ||
+            identity(run.projectRoot) !== identity(options.projectRoot) ||
+            run.providerKey !== options.providerAccountKey)
+            continue;
+        const metadata = (await options.threadStore.getThread(run.threadId))?.metadata;
+        const status = await options.engine.status(run.runId);
+        if (status) {
+            if (status.state === "failed" || status.state === "cancelled" || status.state === "completed")
+                await finishFailedThreadRun(run.runId, run.threadId, options.projectRoot, options.engine, options.eventStore, status.state === "failed" ? "Queued run failed before it could be resumed." : undefined, metadata).catch((error) => console.error("Could not settle queued thread run", error));
+            continue;
+        }
+        void runProject(options.projectRoot, {
+            runId: run.runId,
+            threadId: run.threadId,
+            ...(metadata === undefined ? {} : { metadata }),
+            ...(run.context === undefined ? {} : { context: run.context }),
+            history: run.history,
+            message: run.content,
+            provider: options.provider,
+            providerRecoveryKey: options.providerRecoveryKey ?? options.providerAccountKey,
+            engine: options.engine,
+            eventStore: options.eventStore,
+        }).catch(async (error) => {
+            try {
+                await finishFailedThreadRun(run.runId, run.threadId, options.projectRoot, options.engine, options.eventStore, error, metadata);
+            }
+            catch (settleError) {
+                console.error("Could not record failed queued thread run", settleError);
+            }
+            console.error(`Queued run ${run.runId} failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+}
+function identity(path) {
+    const absolute = resolve(path);
+    return process.platform === "win32" ? absolute.toLowerCase() : absolute;
+}

package/dist/responses.d.ts

@@ -0,0 +1 @@
+export declare function jsonResponse(status: number, body: unknown, headers?: Record<string, string>): Response;

package/dist/responses.js

@@ -0,0 +1,6 @@
+export function jsonResponse(status, body, headers) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json; charset=utf-8", ...headers },
+    });
+}

package/dist/routes/artifacts.d.ts

@@ -0,0 +1,2 @@
+import type { Route } from "./types.js";
+export declare const artifactRoutes: Route[];

package/dist/routes/artifacts.js

@@ -0,0 +1,165 @@
+import { buildArtifactWorkspace, readArtifactSnapshot, readArtifactVersion, } from "@plico-ai/runtime";
+import { createTwoFilesPatch } from "diff";
+import { requireRun } from "../app/runs.js";
+import { HttpError } from "../errors.js";
+import { jsonResponse } from "../responses.js";
+async function readRunEvents(context, runId) {
+    const { eventStore, threadStore } = context;
+    await requireRun(context.app, runId);
+    const threadId = await threadStore?.getThreadForRun(runId);
+    if (!threadId)
+        return eventStore.getEvents(runId);
+    if (eventStore.getThreadRunEventsThrough)
+        return eventStore.getThreadRunEventsThrough(threadId, runId);
+    if (!eventStore.getThreadRunEvents)
+        throw new HttpError(503, "workspace.unavailable", "Thread workspace projection is unavailable.");
+    const events = await eventStore.getThreadRunEvents(threadId);
+    let lastRunEvent = -1;
+    events.forEach((event, index) => {
+        if (event.runId === runId)
+            lastRunEvent = index;
+    });
+    return lastRunEvent < 0 ? [] : events.slice(0, lastRunEvent + 1);
+}
+function requireWorkspace(runId, events) {
+    const workspace = buildArtifactWorkspace(runId, events);
+    if (!workspace) {
+        throw new HttpError(404, "workspace.not_found", `No artifact workspace for run: ${runId}`);
+    }
+    return workspace;
+}
+async function readWorkspace(context, runId) {
+    return requireWorkspace(runId, await readRunEvents(context, runId));
+}
+export const artifactRoutes = [
+    {
+        method: "GET",
+        pattern: /^\/v1\/runs\/([^/]+)\/workspace\/diffs$/,
+        handler: async (context) => {
+            const [runId = ""] = context.params;
+            const events = await readRunEvents(context, runId);
+            const workspace = requireWorkspace(runId, events);
+            const path = context.url.searchParams.get("path");
+            if (!path) {
+                throw new HttpError(400, "artifact.path_required", "A path is required to diff artifacts.");
+            }
+            if (!workspace.files.some((file) => file.path === path)) {
+                throw new HttpError(404, "artifact.not_found", `Unknown artifact file: ${path}`);
+            }
+            const fromVersion = readVersionQuery(context.url, "fromVersion");
+            const toVersion = readVersionQuery(context.url, "toVersion");
+            const from = readArtifactVersion(events, path, fromVersion);
+            const to = readArtifactVersion(events, path, toVersion);
+            if (!from || !to) {
+                throw new HttpError(404, "artifact.version_not_found", `Unknown artifact version for ${path}: ${!from ? fromVersion : toVersion}`);
+            }
+            if (typeof from.content !== "string" ||
+                typeof to.content !== "string" ||
+                !isDiffableMimeType(from.mimeType) ||
+                !isDiffableMimeType(to.mimeType)) {
+                throw new HttpError(415, "artifact.diff_unsupported_media_type", "Artifact diffs support text, JSON, and XML content.");
+            }
+            if (Buffer.byteLength(from.content, "utf8") > maxDiffContentBytes ||
+                Buffer.byteLength(to.content, "utf8") > maxDiffContentBytes) {
+                throw new HttpError(413, "artifact.diff_too_large", `Artifact versions must be at most ${maxDiffContentBytes} bytes to diff.`);
+            }
+            return jsonResponse(200, {
+                path,
+                fromVersion,
+                toVersion,
+                diff: createTwoFilesPatch(path, path, from.content, to.content, `version ${fromVersion}`, `version ${toVersion}`),
+            });
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/v1\/runs\/([^/]+)\/workspace$/,
+        handler: async (context) => {
+            const runId = context.params[0] ?? "";
+            const workspace = await readWorkspace(context, runId);
+            const threadId = await context.threadStore?.getThreadForRun(runId);
+            return jsonResponse(200, threadId ? { ...workspace, threadId } : workspace);
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/v1\/runs\/([^/]+)\/workspace\/files\/(.+)$/,
+        handler: async (context) => {
+            const [runId = "", path = ""] = context.params;
+            const workspace = await readWorkspace(context, runId);
+            const file = workspace.files.find((candidate) => candidate.path === path);
+            if (!file) {
+                throw new HttpError(404, "artifact.not_found", `Unknown artifact file: ${path}`);
+            }
+            return jsonResponse(200, file);
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/v1\/runs\/([^/]+)\/workspace\/exports$/,
+        handler: async (context) => {
+            const [runId = ""] = context.params;
+            const workspace = await readWorkspace(context, runId);
+            const path = context.url.searchParams.get("path");
+            if (!path) {
+                throw new HttpError(400, "artifact.path_required", "A path is required to export an artifact.");
+            }
+            const file = workspace.files.find((candidate) => candidate.path === path);
+            if (!file) {
+                throw new HttpError(404, "artifact.not_found", `Unknown artifact file: ${path}`);
+            }
+            const filename = path.split("/").at(-1) || "artifact";
+            const encodedFilename = encodeURIComponent(filename).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+            return new Response(typeof file.content === "string" ? file.content : Buffer.from(file.content.data, "base64"), {
+                headers: {
+                    "x-content-type-options": "nosniff",
+                    "content-type": exportMediaType(file.mimeType),
+                    "content-disposition": `attachment; filename*=UTF-8''${encodedFilename}`,
+                },
+            });
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/v1\/runs\/([^/]+)\/workspace\/snapshots\/([^/]+)$/,
+        handler: async (context) => {
+            const [runId = "", snapshotId = ""] = context.params;
+            const events = await readRunEvents(context, runId);
+            requireWorkspace(runId, events);
+            const snapshot = readArtifactSnapshot(events, snapshotId);
+            if (!snapshot) {
+                throw new HttpError(404, "artifact.not_found", `Unknown artifact snapshot: ${snapshotId}`);
+            }
+            return jsonResponse(200, snapshot);
+        },
+    },
+];
+function exportMediaType(mimeType) {
+    const mediaType = mimeType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+    if (mediaType === "text/html" ||
+        mediaType === "application/xhtml+xml" ||
+        mediaType === "image/svg+xml" ||
+        /\/(?:x-)?(?:java|ecma)script$/.test(mediaType) ||
+        /\+(?:java|ecma)script$/.test(mediaType)) {
+        return "application/octet-stream";
+    }
+    return /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/.test(mediaType)
+        ? mediaType
+        : "application/octet-stream";
+}
+function readVersionQuery(url, name) {
+    const value = url.searchParams.get(name);
+    if (!value || !/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value))) {
+        throw new HttpError(400, "artifact.invalid_version", `${name} must be a positive integer.`);
+    }
+    return Number(value);
+}
+const maxDiffContentBytes = 1024 * 1024;
+function isDiffableMimeType(mimeType) {
+    const mediaType = mimeType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+    return (mediaType.startsWith("text/") ||
+        mediaType === "application/json" ||
+        mediaType.endsWith("+json") ||
+        mediaType === "application/xml" ||
+        mediaType.endsWith("+xml"));
+}

package/dist/routes/eval.d.ts

@@ -0,0 +1,2 @@
+import type { Route } from "./types.js";
+export declare const evalRoutes: Route[];

package/dist/routes/eval.js

@@ -0,0 +1,38 @@
+import { runEvals } from "@plico-ai/runtime";
+import { HttpError } from "../errors.js";
+import { jsonResponse } from "../responses.js";
+async function readLatestReport(eventStore) {
+    const report = await eventStore.getLatestEvalReport();
+    if (!report) {
+        throw new HttpError(404, "eval.not_found", "No eval results yet. Run evals first.");
+    }
+    return report;
+}
+export const evalRoutes = [
+    {
+        method: "POST",
+        hostOnly: true,
+        pattern: /^\/v1\/eval$/,
+        handler: async ({ projectRoot, eventStore }) => jsonResponse(200, await runEvals(projectRoot, { eventStore })),
+    },
+    {
+        method: "GET",
+        hostOnly: true,
+        pattern: /^\/v1\/eval$/,
+        handler: async ({ eventStore }) => jsonResponse(200, await readLatestReport(eventStore)),
+    },
+    {
+        method: "GET",
+        hostOnly: true,
+        pattern: /^\/v1\/eval\/([^/]+)$/,
+        handler: async ({ eventStore, params }) => {
+            const name = params[0] ?? "";
+            const report = await readLatestReport(eventStore);
+            const result = report.results.find((candidate) => candidate.name === name);
+            if (!result) {
+                throw new HttpError(404, "eval.not_found", `Unknown eval: ${name}`);
+            }
+            return jsonResponse(200, result);
+        },
+    },
+];

package/dist/routes/health.d.ts

@@ -0,0 +1,2 @@
+import type { Route } from "./types.js";
+export declare const healthRoutes: Route[];

package/dist/routes/health.js

@@ -0,0 +1,8 @@
+import { jsonResponse } from "../responses.js";
+export const healthRoutes = [
+    {
+        method: "GET",
+        pattern: /^\/health$/,
+        handler: async ({ app }) => jsonResponse(200, app.inspect ? { ok: true, inspection: true } : { ok: true }),
+    },
+];

package/dist/routes/index.d.ts

@@ -0,0 +1,11 @@
+import type { AppDeps } from "../app/types.js";
+interface HandleRequestOptions {
+    app: AppDeps;
+    /** Aborts when the host closes Plico, so open event streams end. */
+    stop: AbortSignal;
+    studioPath: string | undefined;
+    allowScript: boolean;
+    request: Request;
+}
+export declare function handleRequest(options: HandleRequestOptions): Promise<Response>;
+export {};

package/dist/routes/index.js

@@ -0,0 +1,72 @@
+import { PlicoError, statusForCode } from "../app/errors.js";
+import { errorMessage, errorResponse, HttpError } from "../errors.js";
+import { artifactRoutes } from "./artifacts.js";
+import { evalRoutes } from "./eval.js";
+import { healthRoutes } from "./health.js";
+import { projectRoutes } from "./project.js";
+import { readinessRoutes } from "./readiness.js";
+import { runRoutes } from "./runs.js";
+import { threadRoutes } from "./threads.js";
+const routes = [
+    ...healthRoutes,
+    ...projectRoutes,
+    ...runRoutes,
+    ...threadRoutes,
+    ...artifactRoutes,
+    ...evalRoutes,
+    ...readinessRoutes,
+];
+export async function handleRequest(options) {
+    const { app, stop, studioPath, allowScript, request } = options;
+    const url = new URL(request.url);
+    try {
+        if (app.inspect && request.method !== "GET" && request.method !== "HEAD")
+            return errorResponse(403, "inspection.read_only", "This Plico server is inspection-only and does not change runs or threads.");
+        const pathMatches = routes.filter((route) => route.pattern.test(url.pathname) && !(app.scope && route.hostOnly));
+        const route = pathMatches.find((candidate) => candidate.method === request.method);
+        if (route) {
+            const match = route.pattern.exec(url.pathname);
+            const params = (match?.slice(1) ?? []).map(decodeParam);
+            return await route.handler({
+                app,
+                stop,
+                projectRoot: app.projectRoot,
+                eventStore: app.eventStore,
+                threadStore: app.threadStore,
+                provider: app.provider,
+                providerRecoveryKey: app.providerRecoveryKey,
+                providerAccountKey: app.providerAccountKey,
+                engine: app.engine,
+                studioPath,
+                allowScript,
+                request,
+                url,
+                params,
+            });
+        }
+        if (pathMatches.length > 0) {
+            return errorResponse(405, "method.not_allowed", "Method not allowed.", {
+                allow: [...new Set(pathMatches.map((r) => r.method))].join(", "),
+            });
+        }
+        return errorResponse(404, "route.not_found", "Unknown route.");
+    }
+    catch (error) {
+        if (error instanceof HttpError) {
+            return errorResponse(error.status, error.code, error.message);
+        }
+        if (error instanceof PlicoError) {
+            return errorResponse(statusForCode(error.code), error.code, error.message);
+        }
+        console.error(`plico server error: ${errorMessage(error)}`);
+        return errorResponse(500, "server.error", "Internal server error.");
+    }
+}
+function decodeParam(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        throw new HttpError(400, "request.invalid_path", "Malformed percent-encoding in path.");
+    }
+}

package/dist/routes/metadata-query.d.ts

@@ -0,0 +1,4 @@
+/** Reads the `metadata` query parameter, a URL-encoded JSON object, as a list filter. */
+export declare function readMetadataFilter(url: URL): {
+    metadata?: unknown;
+};

package/dist/routes/metadata-query.js

@@ -0,0 +1,13 @@
+import { HttpError } from "../errors.js";
+/** Reads the `metadata` query parameter, a URL-encoded JSON object, as a list filter. */
+export function readMetadataFilter(url) {
+    const raw = url.searchParams.get("metadata");
+    if (raw === null)
+        return {};
+    try {
+        return { metadata: JSON.parse(raw) };
+    }
+    catch {
+        throw new HttpError(400, "request.invalid", "metadata must be a URL-encoded JSON object.");
+    }
+}

package/dist/routes/project.d.ts

@@ -0,0 +1,2 @@
+import type { Route } from "./types.js";
+export declare const projectRoutes: Route[];

package/dist/routes/project.js

@@ -0,0 +1,23 @@
+import { composeInstructions } from "@plico-ai/runtime";
+import { loadProjectOrThrow } from "../project.js";
+import { jsonResponse } from "../responses.js";
+export const projectRoutes = [
+    {
+        method: "GET",
+        hostOnly: true,
+        pattern: /^\/v1\/project$/,
+        handler: async ({ projectRoot }) => {
+            const project = await loadProjectOrThrow(projectRoot);
+            return jsonResponse(200, { project });
+        },
+    },
+    {
+        method: "GET",
+        hostOnly: true,
+        pattern: /^\/v1\/instructions$/,
+        handler: async ({ projectRoot }) => {
+            const project = await loadProjectOrThrow(projectRoot);
+            return jsonResponse(200, await composeInstructions(project));
+        },
+    },
+];

package/dist/routes/readiness.d.ts

@@ -0,0 +1,2 @@
+import type { Route } from "./types.js";
+export declare const readinessRoutes: Route[];

package/dist/routes/readiness.js

@@ -0,0 +1,17 @@
+import { checkReadiness } from "@plico-ai/runtime";
+import { jsonResponse } from "../responses.js";
+export const readinessRoutes = [
+    {
+        method: "GET",
+        hostOnly: true,
+        pattern: /^\/v1\/readiness$/,
+        handler: async ({ projectRoot, eventStore, threadStore, studioPath }) => {
+            const report = await checkReadiness(projectRoot, {
+                eventStore,
+                ...(threadStore ? { threadStore } : {}),
+                studioPath,
+            });
+            return jsonResponse(200, report);
+        },
+    },
+];

package/dist/routes/runs.d.ts

@@ -0,0 +1,2 @@
+import type { Route } from "./types.js";
+export declare const runRoutes: Route[];

package/dist/routes/runs.js

@@ -0,0 +1,82 @@
+import { cancelRun, listRunEvents, listRuns, requireRun, runDry, signalRun, startRun, } from "../app/runs.js";
+import { readJsonBody } from "../body.js";
+import { jsonResponse } from "../responses.js";
+import { readScript } from "../script.js";
+import { eventStreamResponse, parseAfterCursor } from "../stream.js";
+import { readMetadataFilter } from "./metadata-query.js";
+function readAfterCursor(url) {
+    const after = url.searchParams.get("after");
+    return after === null ? undefined : parseAfterCursor(after);
+}
+export const runRoutes = [
+    {
+        method: "POST",
+        pattern: /^\/v1\/runs$/,
+        handler: async ({ app, allowScript, request }) => {
+            const body = await readJsonBody(request);
+            const script = readScript(body, allowScript);
+            return jsonResponse(202, await startRun(app, {
+                // A script sent over HTTP comes from the caller, so its tool steps never run handlers.
+                ...(script === undefined ? {} : { script, mockTools: true }),
+                metadata: body.metadata,
+            }));
+        },
+    },
+    {
+        method: "POST",
+        hostOnly: true,
+        pattern: /^\/v1\/runs\/dry$/,
+        handler: async ({ app, allowScript, request }) => {
+            const script = readScript(await readJsonBody(request), allowScript);
+            return jsonResponse(200, await runDry(app, script === undefined ? {} : { script, mockTools: true }));
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/v1\/runs$/,
+        handler: async ({ app, url }) => jsonResponse(200, await listRuns(app, readMetadataFilter(url))),
+    },
+    {
+        method: "GET",
+        pattern: /^\/v1\/runs\/([^/]+)$/,
+        handler: async ({ app, params }) => jsonResponse(200, await requireRun(app, params[0] ?? "")),
+    },
+    {
+        method: "GET",
+        pattern: /^\/v1\/runs\/([^/]+)\/events\/stream$/,
+        handler: async (context) => {
+            const lastEventId = context.request.headers.get("last-event-id");
+            const afterSequence = lastEventId === null || lastEventId === ""
+                ? readAfterCursor(context.url)
+                : parseAfterCursor(lastEventId);
+            return eventStreamResponse({
+                app: context.app,
+                stop: context.stop,
+                request: context.request,
+                runId: context.params[0] ?? "",
+                afterSequence,
+            });
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/v1\/runs\/([^/]+)\/events$/,
+        handler: async ({ app, params, url }) => jsonResponse(200, await listRunEvents(app, params[0] ?? "", readAfterCursor(url))),
+    },
+    {
+        method: "POST",
+        pattern: /^\/v1\/runs\/([^/]+)\/cancel$/,
+        handler: async ({ app, params }) => jsonResponse(200, { result: await cancelRun(app, params[0] ?? "") }),
+    },
+    {
+        method: "POST",
+        pattern: /^\/v1\/runs\/([^/]+)\/signal$/,
+        handler: async ({ app, params, request }) => {
+            const runId = params[0] ?? "";
+            await requireRun(app, runId);
+            const body = await readJsonBody(request);
+            const name = typeof body.name === "string" ? body.name : "";
+            return jsonResponse(200, { result: await signalRun(app, runId, name, body.value) });
+        },
+    },
+];

package/dist/routes/threads.d.ts

@@ -0,0 +1,2 @@
+import type { Route } from "./types.js";
+export declare const threadRoutes: Route[];

package/dist/routes/threads.js

@@ -0,0 +1,60 @@
+import { createThread, listThreads, renameThread, requireThread, sendMessage, threadMessages, threadWorkspace, } from "../app/threads.js";
+import { readJsonBody, readOptionalJsonBody } from "../body.js";
+import { HttpError } from "../errors.js";
+import { jsonResponse } from "../responses.js";
+import { readMetadataFilter } from "./metadata-query.js";
+export const threadRoutes = [
+    {
+        method: "POST",
+        pattern: /^\/v1\/threads$/,
+        handler: async (ctx) => {
+            const { metadata } = await readOptionalJsonBody(ctx.request);
+            return jsonResponse(201, await createThread(ctx.app, { metadata }));
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/v1\/threads$/,
+        handler: async (ctx) => jsonResponse(200, await listThreads(ctx.app, readMetadataFilter(ctx.url))),
+    },
+    {
+        method: "GET",
+        pattern: /^\/v1\/threads\/([^/]+)$/,
+        handler: async (ctx) => jsonResponse(200, await requireThread(ctx.app, ctx.params[0] ?? "")),
+    },
+    {
+        method: "PATCH",
+        pattern: /^\/v1\/threads\/([^/]+)$/,
+        handler: async (ctx) => {
+            const threadId = ctx.params[0] ?? "";
+            await requireThread(ctx.app, threadId);
+            const { title } = await readJsonBody(ctx.request);
+            return jsonResponse(200, await renameThread(ctx.app, threadId, title));
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/v1\/threads\/([^/]+)\/workspace$/,
+        handler: async (ctx) => jsonResponse(200, await threadWorkspace(ctx.app, ctx.params[0] ?? "")),
+    },
+    {
+        method: "GET",
+        pattern: /^\/v1\/threads\/([^/]+)\/messages$/,
+        handler: async (ctx) => jsonResponse(200, await threadMessages(ctx.app, ctx.params[0] ?? "")),
+    },
+    {
+        method: "POST",
+        pattern: /^\/v1\/threads\/([^/]+)\/messages$/,
+        handler: async (ctx) => {
+            const threadId = ctx.params[0] ?? "";
+            await requireThread(ctx.app, threadId);
+            const body = await readJsonBody(ctx.request);
+            if (body.startRun !== undefined && typeof body.startRun !== "boolean")
+                throw new HttpError(400, "message.invalid", "startRun must be a boolean.");
+            const message = await sendMessage(ctx.app, threadId, body.content, {
+                startRun: body.startRun !== false,
+            });
+            return jsonResponse(201, message);
+        },
+    },
+];

package/dist/routes/types.d.ts

@@ -0,0 +1,30 @@
+import type { Engine, EventStore, ModelProvider, ThreadStore } from "@plico-ai/runtime";
+import type { AppDeps } from "../app/types.js";
+export interface RouteContext {
+    /** The shared layer the thread and run routes call. */
+    app: AppDeps;
+    /** Aborts when the host closes Plico, so open event streams end. */
+    stop: AbortSignal;
+    projectRoot: string;
+    eventStore: EventStore;
+    threadStore: ThreadStore | undefined;
+    provider: ModelProvider | undefined;
+    providerRecoveryKey: string | undefined;
+    /** Account-only identity used to resume queued runs after a model change. */
+    providerAccountKey: string | undefined;
+    engine: Engine | undefined;
+    studioPath: string | undefined;
+    /** Whether a request may carry a `script` that drives project tools without a model. */
+    allowScript: boolean;
+    request: Request;
+    url: URL;
+    /** Decoded capture groups from the route pattern, in order. */
+    params: string[];
+}
+export interface Route {
+    method: "GET" | "POST" | "PATCH";
+    pattern: RegExp;
+    /** Project-level routes. A scoped mount does not serve them. */
+    hostOnly?: true;
+    handler: (context: RouteContext) => Promise<Response>;
+}

package/dist/routes/types.js

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