@personaai/runtime 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,247 @@
+import { ChatMessageInput } from '@personaai/sdk';
+
+type RuntimeMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** A single uploaded file — present on `RuntimeRequest.file` for a multipart `POST /files`. */
+interface RuntimeUploadedFile {
+    filename: string;
+    content: Uint8Array;
+    contentType?: string;
+}
+/**
+ * Framework-neutral inbound request. A framework adapter (Express, Node
+ * `http`, ...) translates its own request object into this shape and calls
+ * `Runtime.handle()` — the runtime never imports a framework.
+ */
+interface RuntimeRequest {
+    method: RuntimeMethod;
+    /** Pathname only (no query string). May still include the `mountPath` prefix — the runtime strips it. */
+    path: string;
+    /** Header names as the adapter received them (Node's `http` already lowercases these). */
+    headers: Record<string, string | undefined>;
+    query: Record<string, string | undefined>;
+    /**
+     * Already-parsed JSON body, or `undefined` for bodyless requests. For a
+     * multipart request (`POST /files`, `POST /knowledge/:id/documents`), this
+     * holds the non-file form fields (e.g. `{ agentId, threadId }`) — the
+     * file(s) themselves are on `file`/`files`, not here. Parsing raw bytes is
+     * the adapter's job either way.
+     */
+    body: unknown;
+    /** The uploaded file, for a multipart `POST /files` request (single-file upload) only. */
+    file?: RuntimeUploadedFile;
+    /** The uploaded files, for a multipart `POST /knowledge/:id/documents` request (multi-file upload) only. */
+    files?: RuntimeUploadedFile[];
+    /**
+     * The resolved external user id. Always `null` on the request the host
+     * constructs — the runtime fills this in via `resolveUser` before an
+     * auth-required route handler sees it.
+     */
+    userId: string | null;
+}
+
+/** A complete response with a known-length body — every route except streaming chat. */
+interface RuntimeBufferedResponse {
+    kind: 'buffered';
+    status: number;
+    headers: Record<string, string>;
+    /** Pre-serialized (e.g. already `JSON.stringify`-ed) — adapters never need to know content-type semantics. */
+    body: string;
+}
+/** An open-ended SSE response — the chat route only. */
+interface RuntimeStreamResponse {
+    kind: 'stream';
+    status: number;
+    headers: Record<string, string>;
+    /** Already-formatted SSE frame text chunks (`"data: ...\n\n"`); adapters just write them through as they arrive. */
+    body: AsyncIterable<string>;
+}
+/** Raw bytes with a known (or unknown, chunked) length — file downloads only. */
+interface RuntimeBinaryResponse {
+    kind: 'binary';
+    status: number;
+    headers: Record<string, string>;
+    body: AsyncIterable<Uint8Array>;
+}
+type RuntimeResponse = RuntimeBufferedResponse | RuntimeStreamResponse | RuntimeBinaryResponse;
+
+interface RunContext {
+    userId: string;
+    /** Which endpoint started this run. */
+    kind: 'chat' | 'architect';
+    /** Absent for `kind: 'architect'` — the Architect co-pilot has no target agentId, it builds/edits Agents itself. */
+    agentId?: string;
+    threadId?: string;
+    messages: ChatMessageInput[];
+}
+interface RunResult {
+    /** Assembled assistant text (concatenated TEXT_MESSAGE_CHUNK deltas), same as `ChatResult.text`. */
+    text: string;
+    eventCount: number;
+    /** True when the run paused on a HITL/clarification interrupt instead of finishing normally. */
+    interrupted: boolean;
+    /** True when a RUN_ERROR event was seen — the run still completed (as far as the stream is concerned); see README on the `onError` vs `erroredInBand` distinction. */
+    erroredInBand: boolean;
+}
+interface ErrorContext {
+    userId: string | null;
+    /** Which stage of request handling the error came from. */
+    phase: 'auth' | 'chat' | 'architect';
+    agentId?: string;
+    threadId?: string;
+}
+interface ToolCallContext {
+    userId: string;
+    /** Absent for a tool call inside an Architect run. */
+    agentId?: string;
+    threadId?: string;
+    toolName: string;
+    toolCallId: string;
+}
+interface FileUploadContext {
+    userId: string;
+    fileName: string;
+    mimeType?: string;
+}
+interface ThreadCreateContext {
+    userId: string;
+    agentId: string;
+    threadId: string;
+}
+interface MemoryWriteContext {
+    userId: string;
+    /** Set when the write was agent-scoped (`scope: 'agent'`); absent for a user-scoped write. */
+    agentId?: string;
+    path: string;
+}
+/**
+ * Lifecycle hooks — the host application's voice inside the runtime's
+ * request handling. Plain async event listeners, not middleware: the
+ * runtime proceeds with sensible defaults when a hook is omitted, and a
+ * hook that wants to reject a run simply throws (the throw is caught and
+ * routed through the same sanitized error path as any other failure).
+ */
+interface RuntimeHooks {
+    beforeRun?(ctx: RunContext): void | Promise<void>;
+    afterRun?(ctx: RunContext, result: RunResult): void | Promise<void>;
+    onError?(ctx: ErrorContext, error: unknown): void | Promise<void>;
+    /** Fires when a TOOL_CALL_START event arrives in the chat stream, before its result is known. */
+    beforeToolCall?(ctx: ToolCallContext): void | Promise<void>;
+    /** Fires when the matching TOOL_CALL_RESULT event arrives. `result` is the raw (string or JSON-parsed) tool output. */
+    afterToolCall?(ctx: ToolCallContext, result: unknown): void | Promise<void>;
+    /** Fires after a file finishes uploading via `POST /files`. */
+    onFileUpload?(ctx: FileUploadContext): void | Promise<void>;
+    /**
+     * Fires after a Thread is created — either explicitly via `POST /threads`,
+     * or implicitly by `POST /chat` when no `threadId` was supplied and the
+     * run's `RUN_STARTED` event reports one that didn't exist yet.
+     */
+    onThreadCreate?(ctx: ThreadCreateContext): void | Promise<void>;
+    /** Fires after a memory file is written via `PUT /memory/file`. */
+    onMemoryWrite?(ctx: MemoryWriteContext): void | Promise<void>;
+}
+
+/**
+ * The single point of contact between the host's auth world and the
+ * runtime's world. Receives the inbound request (with `userId: null`) and
+ * returns the resolved external user id, or `null`/a thrown error if the
+ * request isn't authenticated — either way the runtime responds 401.
+ * Persona never authenticates users; this function is entirely the host's.
+ */
+type ResolveUser = (request: RuntimeRequest) => string | null | Promise<string | null>;
+/**
+ * Every one of these is `false` unless explicitly enabled — always-off by
+ * default so upgrading this package never silently exposes new surface to
+ * whoever `resolveUser` accepts. These resources are Project-level
+ * configuration (LLM provider credentials, skill/knowledge-base/vector-store
+ * management, security audit logs, an agent-building co-pilot) rather than
+ * things an end user does in a chat session — most hosts should manage them
+ * via `@personaai/sdk` directly from their own admin surface and never turn
+ * these on. Turn one on only if you specifically want it reachable through
+ * whatever `resolveUser` gates (which may not be "any logged-in end user" —
+ * that's your call).
+ */
+interface RuntimeCapabilities {
+    /** Full Agent CRUD (create/get/update/delete/bulk-delete) beyond the always-on read-only `GET /agents` list. @default false */
+    agentsWrite?: boolean;
+    /** Full MCP server CRUD + testConnection/readResource/callTool, beyond the always-on `/mcps/:id/oauth/*` routes. @default false */
+    mcps?: boolean;
+    /** LLM provider configuration — **holds API keys**. @default false */
+    providers?: boolean;
+    /** Skill authoring. @default false */
+    skills?: boolean;
+    /** Knowledge base CRUD, document upload/search. @default false */
+    knowledge?: boolean;
+    /** Vector store CRUD and file read/write. @default false */
+    stores?: boolean;
+    /** Security/compliance audit log read access. @default false */
+    auditLogs?: boolean;
+    /** The Architect co-pilot — builds/edits Agents on the caller's behalf via tool calls. @default false */
+    architect?: boolean;
+}
+interface CreateRuntimeOptions {
+    /** Base URL of the Persona Developer Platform API, e.g. "https://api.persona.hasanraiyan.me". */
+    baseUrl: string;
+    /** Project credential, shaped "<keyId>.<secret>" — never expose this to a browser. */
+    credential: string;
+    resolveUser: ResolveUser;
+    hooks?: RuntimeHooks;
+    /** Prefix to strip from `request.path` before routing, e.g. '/api/persona'. @default '' (no stripping) */
+    mountPath?: string;
+    /**
+     * 'development' includes error detail (message/stack/upstream response)
+     * in error responses; 'production' hides it behind a generic message.
+     * @default 'production', unless `process.env.NODE_ENV === 'development'`.
+     */
+    mode?: 'development' | 'production';
+    /** Override fetch (proxying, tracing, or test injection). Forwarded to every per-request PersonaClient. */
+    fetch?: typeof fetch;
+    /**
+     * How often to send an SSE comment-line heartbeat (`: heartbeat\n\n`)
+     * during a gap in the `/chat` stream — e.g. a long-running tool call with
+     * no token output — so intermediary proxies/load balancers with an idle
+     * timeout don't kill the connection. Comment lines are invisible to any
+     * `data:`-only SSE parser (including `@personaai/sdk`'s own), so this
+     * never changes the AG-UI event sequence a consumer sees.
+     * @default 15000
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * How long a finished `/chat` run stays resumable via `GET /chat/:runId/resume`
+     * before an internal eviction sweep removes it.
+     * @default 300000 (5 minutes)
+     */
+    runGraceMs?: number;
+    /**
+     * Safety valve on the in-memory resumable-run registry — once over this
+     * many tracked runs, the oldest-finished ones are evicted first (still
+     * in-flight runs are never evicted by this cap).
+     * @default 1000
+     */
+    maxTrackedRuns?: number;
+    /** Opt-in switches for Project-level admin surface. See {@link RuntimeCapabilities} — everything defaults to off. */
+    capabilities?: RuntimeCapabilities;
+}
+interface Runtime {
+    handle(request: RuntimeRequest): Promise<RuntimeResponse>;
+    /**
+     * Stops the background eviction timer used for resumable-run bookkeeping.
+     * The timer is `unref`'d and won't itself keep a Node process alive, so
+     * calling this is optional — but do call it if you `createRuntime()`
+     * repeatedly in a long-lived process (e.g. per-test-suite setup) to avoid
+     * accumulating timers.
+     */
+    close(): void;
+}
+
+declare function createRuntime(options: CreateRuntimeOptions): Runtime;
+
+/** A runtime-originated HTTP error (routing, validation, auth) — as opposed to one surfaced from the Persona API itself. */
+declare class RuntimeHttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+
+declare const RUNTIME_VERSION = "0.5.0";
+
+export { type CreateRuntimeOptions, type ErrorContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type ResolveUser, type RunContext, type RunResult, type Runtime, type RuntimeBinaryResponse, type RuntimeBufferedResponse, type RuntimeCapabilities, type RuntimeHooks, RuntimeHttpError, type RuntimeMethod, type RuntimeRequest, type RuntimeResponse, type RuntimeStreamResponse, type RuntimeUploadedFile, type ThreadCreateContext, type ToolCallContext, createRuntime };