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

package/dist/server.js

@@ -0,0 +1,25 @@
+import { createServer } from "node:http";
+import { openPlico } from "./create-plico.js";
+import { createRequestListener } from "./listener.js";
+/** `createPlico` plus an HTTP listener over its `/v1` API. Closing the server closes Plico. */
+export async function servePlico(options) {
+    const plico = await openPlico({ projectRoot: options.projectRoot, databasePath: options.databasePath }, options.inspect === true);
+    const server = createServer(createRequestListener(plico, {
+        ...(options.studioPath === undefined ? {} : { studioPath: options.studioPath }),
+        ...(options.allowRemote === undefined ? {} : { allowRemote: options.allowRemote }),
+        ...(options.publicOrigin === undefined ? {} : { publicOrigin: options.publicOrigin }),
+        ...(options.allowScript === undefined ? {} : { allowScript: options.allowScript }),
+    }));
+    server.once("close", () => void plico.close());
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(options.port ?? 3000, options.host ?? "127.0.0.1", () => resolve());
+        });
+    }
+    catch (error) {
+        await plico.close();
+        throw error;
+    }
+    return server;
+}

package/dist/sse.d.ts

@@ -0,0 +1,3 @@
+export declare const sseHeaders: Record<string, string>;
+export declare function sseEvent(event: string, data: unknown, id?: string): Uint8Array;
+export declare function sseHeartbeat(): Uint8Array;

package/dist/sse.js

@@ -0,0 +1,12 @@
+const encoder = new TextEncoder();
+export const sseHeaders = {
+    "content-type": "text/event-stream",
+    "cache-control": "no-cache",
+};
+export function sseEvent(event, data, id) {
+    const idLine = id === undefined ? "" : `id: ${id}\n`;
+    return encoder.encode(`${idLine}event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+}
+export function sseHeartbeat() {
+    return encoder.encode(": heartbeat\n\n");
+}

package/dist/stream.d.ts

@@ -0,0 +1,13 @@
+import type { AppDeps } from "./app/types.js";
+export interface EventStreamOptions {
+    app: AppDeps;
+    /** Aborts when the host closes Plico. */
+    stop: AbortSignal;
+    request: Request;
+    runId: string;
+    afterSequence: number | undefined;
+    heartbeatInterval?: number;
+}
+/** Answers with a run's events as server-sent events until the run ends or the client leaves. */
+export declare function eventStreamResponse(options: EventStreamOptions): Promise<Response>;
+export declare function parseAfterCursor(value: string): number;

package/dist/stream.js

@@ -0,0 +1,58 @@
+import { followEvents } from "./app/events.js";
+import { requireRun } from "./app/runs.js";
+import { HttpError } from "./errors.js";
+import { sseEvent, sseHeaders, sseHeartbeat } from "./sse.js";
+/** Answers with a run's events as server-sent events until the run ends or the client leaves. */
+export async function eventStreamResponse(options) {
+    const { app, stop, request, runId, heartbeatInterval = 2000 } = options;
+    await requireRun(app, runId);
+    const cancelled = new AbortController();
+    const disconnected = AbortSignal.any([request.signal, cancelled.signal]);
+    const body = new ReadableStream({
+        start(controller) {
+            const write = (chunk) => {
+                try {
+                    controller.enqueue(chunk);
+                }
+                catch {
+                    // The client already left.
+                }
+            };
+            const heartbeat = setInterval(() => write(sseHeartbeat()), heartbeatInterval);
+            void (async () => {
+                try {
+                    const events = followEvents(app, runId, {
+                        ...(options.afterSequence === undefined ? {} : { after: options.afterSequence }),
+                        signal: disconnected,
+                        stop,
+                        pollMs: heartbeatInterval,
+                    });
+                    for await (const event of events) {
+                        write(sseEvent("plico.event", event, String(event.sequence)));
+                    }
+                    write(sseHeartbeat());
+                }
+                finally {
+                    clearInterval(heartbeat);
+                    try {
+                        controller.close();
+                    }
+                    catch {
+                        // Already closed by the client.
+                    }
+                }
+            })();
+        },
+        cancel() {
+            cancelled.abort();
+        },
+    });
+    return new Response(body, { headers: sseHeaders });
+}
+export function parseAfterCursor(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new HttpError(400, "cursor.invalid", `Malformed cursor: ${value}`);
+    }
+    return parsed;
+}

package/dist/thread-failure.d.ts

@@ -0,0 +1,7 @@
+import { type Engine, type EventStore } from "@plico-ai/runtime";
+import type { Metadata } from "./app/metadata.js";
+/**
+ * Persist a terminal outcome after the engine confirms no worker is still running. A run whose
+ * journal write never happened is also safe to fail: nothing can be executing it.
+ */
+export declare function finishFailedThreadRun(runId: string, threadId: string, projectRoot: string, engine: Engine, eventStore: EventStore, error?: unknown, metadata?: Metadata): Promise<void>;

package/dist/thread-failure.js

@@ -0,0 +1,42 @@
+import { runFailureEvents } from "@plico-ai/runtime";
+/**
+ * Persist a terminal outcome after the engine confirms no worker is still running. A run whose
+ * journal write never happened is also safe to fail: nothing can be executing it.
+ */
+export async function finishFailedThreadRun(runId, threadId, projectRoot, engine, eventStore, error, metadata) {
+    const state = await engine.status(runId);
+    if (state && state.state !== "failed")
+        return;
+    let run = await eventStore.getRun(runId);
+    if (!run) {
+        await eventStore.appendEvent({
+            schemaVersion: 1,
+            streamType: "run",
+            streamId: runId,
+            runId,
+            id: "evt-0001",
+            sequence: 1,
+            timestamp: new Date().toISOString(),
+            type: "run.started",
+            payload: {
+                projectRoot,
+                projectName: "",
+                threadId,
+                ...(metadata === undefined ? {} : { metadata }),
+            },
+        });
+        run = await eventStore.getRun(runId);
+    }
+    if (run?.status !== "running")
+        return;
+    const events = await eventStore.getEvents(runId);
+    for (const event of runFailureEvents(runId, events.at(-1), failureMessage(error)))
+        await eventStore.appendEvent(event);
+}
+function failureMessage(error) {
+    if (typeof error === "string" && error)
+        return error;
+    if (error instanceof Error && error.message)
+        return error.message;
+    return "Run execution failed before it could finish.";
+}

package/dist/thread-titles.d.ts

@@ -0,0 +1,11 @@
+import { type EventStore, type ModelProvider, type ThreadStore } from "@plico-ai/runtime";
+/**
+ * After a run in a thread completes, asks the project's titler for a title and stores it. The
+ * keyword title is already stored, so a titler that fails or never answers changes nothing.
+ */
+export declare function withThreadTitles(deps: {
+    projectRoot: string;
+    eventStore: EventStore;
+    threadStore?: ThreadStore | undefined;
+    provider?: ModelProvider | undefined;
+}): EventStore;

package/dist/thread-titles.js

@@ -0,0 +1,37 @@
+import { loadProject } from "@plico-ai/core";
+import { createThreadTitler, } from "@plico-ai/runtime";
+/**
+ * After a run in a thread completes, asks the project's titler for a title and stores it. The
+ * keyword title is already stored, so a titler that fails or never answers changes nothing.
+ */
+export function withThreadTitles(deps) {
+    const { threadStore } = deps;
+    if (!threadStore)
+        return deps.eventStore;
+    let titler;
+    const resolve = () => {
+        titler ??= loadProject(deps.projectRoot).then((project) => createThreadTitler(deps.projectRoot, project.config, deps.provider));
+        return titler;
+    };
+    async function name(runId) {
+        const threadId = await threadStore?.getThreadForRun(runId);
+        if (!threadStore || !threadId)
+            return;
+        // Ask the store first so a user-titled or finished thread never pays for a title.
+        const request = await threadStore.getTitleRequest(threadId);
+        const write = request && (await resolve());
+        if (!request || !write)
+            return;
+        const title = await write(request.messages);
+        if (title)
+            await threadStore.setGeneratedTitle(threadId, title, request.revision);
+    }
+    return {
+        ...deps.eventStore,
+        async appendEvent(event) {
+            await deps.eventStore.appendEvent(event);
+            if (event.type === "run.completed" && event.payload.output !== undefined)
+                void name(event.runId).catch(() => { });
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+import type { ListenerOptions } from "./listener.js";
+export interface ServePlicoOptions extends ListenerOptions {
+    projectRoot: string;
+    /**
+     * Serve for inspection beside a host that owns the database: nothing is recovered or resumed,
+     * and every request that would change state is refused with `inspection.read_only`.
+     */
+    inspect?: boolean;
+    databasePath: string;
+    host?: string;
+    port?: number;
+}

package/dist/types.js

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

package/package.json

@@ -1,21 +1,50 @@
 {
   "name": "@plico-ai/server",
-  "version": "0.0.0-reserved.0",
-  "description": "The Plico HTTP API and embeddable library. Not released yet.",
+  "version": "0.1.0",
+  "description": "Plico native HTTP API over the runtime and event store",
   "license": "Apache-2.0",
   "homepage": "https://plico.sohab.dev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ITZSHOAIB/plico.git"
+    "url": "git+https://github.com/ITZSHOAIB/plico.git",
+    "directory": "packages/server"
   },
   "keywords": [
     "plico",
-    "agent"
-  ],
-  "files": [
-    "README.md"
+    "agent",
+    "http",
+    "api"
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "NOTICE",
+    "dist"
+  ],
+  "dependencies": {
+    "@hono/node-server": "2.1.6",
+    "diff": "8.0.4",
+    "hono": "4.13.17",
+    "@plico-ai/contracts": "0.1.0",
+    "@plico-ai/core": "0.1.0",
+    "@plico-ai/runtime": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "test": "vitest run"
   }
-}
+}