@plico-ai/server 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

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

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @plico-ai/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The thin native HTTP API over the Plico runtime and event store: runs, threads, signals, approvals, cancel, artifacts, events and readiness.
+
+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;