@personaai/runtime 0.21.0 → 0.23.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-import { ChatMessageInput, CreateRestToolInput, LogLevel, Logger } from '@personaai/sdk';
+import { ChatMessageInput, CreateRestToolInput, AgentEnvironment, LogLevel, Logger } from '@personaai/sdk';
+import { WebhookEventType, WebhookEvent } from '@personaai/sdk/webhooks';
 import { RcpTool } from 'rcp-sdk';
 export { RcpTool } from 'rcp-sdk';
 
@@ -39,6 +40,12 @@ interface RuntimeRequest {
      * auth-required route handler sees it.
      */
     userId: string | null;
+    /**
+     * The exact request body bytes, before JSON parsing. Only needed by
+     * `POST /webhooks/persona` (the signature is over the raw bytes, and a
+     * re-serialised body won't match); adapters set it for that route.
+     */
+    rawBody?: Uint8Array | string;
 }
 
 /** A complete response with a known-length body — every route except streaming chat. */
@@ -78,6 +85,10 @@ interface RunContext {
     messages?: ChatMessageInput[];
     /** Input parameters provided to the workflow run. */
     input?: unknown;
+    /** The environment this run asked for (from `selectVersion`, `defaultEnvironment` or the client). */
+    environment?: 'development' | 'production';
+    /** The published version this run asked for. */
+    agentVersion?: number;
 }
 interface RunResult {
     /** Assembled assistant text (concatenated TEXT_MESSAGE_CHUNK deltas), same as `ChatResult.text`. */
@@ -87,6 +98,14 @@ interface RunResult {
     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;
+    /**
+     * Persona's own id for this run (`RUN_STARTED.runId`): what
+     * `POST /feedback` and `client.traces.getByRunId()` take. Not the
+     * runtime's `x-persona-run-id` resume id.
+     */
+    personaRunId?: string;
+    /** The run's thread (also set when the run created one). */
+    threadId?: string;
 }
 interface ErrorContext {
     userId: string | null;
@@ -128,11 +147,31 @@ interface MemoryWriteContext {
     agentId?: string;
     path: string;
 }
+interface FeedbackContext {
+    userId: string;
+    /** Persona's run id the rating is for. */
+    runId: string;
+    score: 1 | -1;
+    comment?: string;
+    tags?: string[];
+}
+/** A Project-wide admin action taken through an admin capability (deploy, traces, evals). */
+interface AdminActionContext {
+    /** Your user who did it (Persona's audit log only knows the API key). */
+    userId: string;
+    capability: 'deploy' | 'traces' | 'evals';
+    /** e.g. `agent.version.deploy`, `trace.replay`, `eval_run.start`. */
+    action: string;
+    /** Ids the action touched. */
+    target: Record<string, unknown>;
+}
 interface VoiceSessionCreateContext {
     userId: string;
     agentId: string;
     /** Set when the session resumed an existing conversation (optional `threadId` on the request). */
     threadId?: string;
+    environment?: 'development' | 'production';
+    agentVersion?: number;
 }
 /**
  * Lifecycle hooks — the host application's voice inside the runtime's
@@ -163,6 +202,15 @@ interface RuntimeHooks {
     onThreadCreate?(ctx: ThreadCreateContext): void | Promise<void>;
     /** Fires after a memory file is written via `PUT /memory/file`. */
     onMemoryWrite?(ctx: MemoryWriteContext): void | Promise<void>;
+    /**
+     * Fires after a Project-wide change or replay through an admin capability
+     * (publish, deploy, rollback, serve policy, replay, eval run and dataset
+     * changes). Persona's audit log names only the API key, so record your
+     * user here.
+     */
+    onAdminAction?(ctx: AdminActionContext): void | Promise<void>;
+    /** Fires after an end user's rating is saved via `POST /feedback`. */
+    onFeedback?(ctx: FeedbackContext): void | Promise<void>;
     /** Fires after a voice session ticket is minted via `POST /voice/sessions`. */
     onVoiceSessionCreate?(ctx: VoiceSessionCreateContext): void | Promise<void>;
 }
@@ -224,6 +272,69 @@ interface RuntimeCapabilities {
      * end-user-scoped. @default false
      */
     messages?: boolean;
+    /** Project secrets (`/secrets`) — write-only values, but creating/rotating them is configuration. @default false */
+    secrets?: boolean;
+    /** REST tool sources (`/rest-tool-sources`) CRUD + Test Connection. @default false */
+    restToolSources?: boolean;
+    /**
+     * Agent versions (`/agents/:id/versions`, `/agents/:id/deployments`):
+     * publish, diff, stats, deploy, rollback, serve policy. Key scope
+     * `deploy:write`. @default false
+     */
+    deploy?: boolean;
+    /** Traces and replays (`/traces`): every end user's conversations. Key scope `traces:read` (+ `agent:invoke` to replay). @default false */
+    traces?: boolean;
+    /** Datasets and eval runs (`/datasets`, `/eval-runs`). Key scope `eval:run`. @default false */
+    evals?: boolean;
+    /** Budget status and usage stats (`/observe/budget`, `/observe/usage`), read-only. Key scope `traces:read`. @default false */
+    observe?: boolean;
+}
+/** What {@link CreateRuntimeOptions.selectVersion} is asked about. */
+interface VersionSelectionContext {
+    userId: string;
+    agentId: string;
+    /** Which route is starting the run. */
+    kind: 'chat' | 'voice';
+}
+/** Which published version of an Agent a run uses. Empty = the Agent's own default. */
+interface VersionSelection {
+    environment?: AgentEnvironment;
+    /** A published version number; wins over `environment`. */
+    agentVersion?: number;
+}
+/** Handler for one Persona webhook event type. Throw to answer 500, so Persona retries. */
+type WebhookHandler = (event: WebhookEvent, delivery: WebhookDelivery) => void | Promise<void>;
+interface WebhookDelivery {
+    /** `X-Persona-Delivery` — the same on every retry of one delivery. */
+    id: string | undefined;
+    /** `X-Persona-Event`. */
+    type: WebhookEventType;
+}
+/**
+ * Receives Persona's outgoing webhooks (Platform → Observe → Webhooks) at
+ * `POST {mountPath}/webhooks/persona`. Public route: it checks
+ * `X-Persona-Signature` (HMAC-SHA256 over the raw body) instead of
+ * `resolveUser`. Needs the adapter to put the raw body on
+ * `RuntimeRequest.rawBody`.
+ */
+interface WebhooksOptions {
+    /** The endpoint's signing secret (`whsec_…`, shown once when you create the webhook). */
+    secret: string;
+    /** One handler per event type, and/or `'*'` for every event. */
+    on: Partial<Record<WebhookEventType | '*', WebhookHandler>>;
+    /** Reject deliveries whose signature timestamp is further than this from now. @default 300 */
+    toleranceSec?: number;
+    /**
+     * Where handled delivery ids are remembered, so a retried delivery
+     * (same `X-Persona-Delivery`) runs your handler once. `add` is called
+     * only after the handlers succeed. The default keeps the last 1000 ids
+     * in memory (one process); use your database or Redis when running
+     * several instances.
+     */
+    dedupe?: {
+        has(deliveryId: string): boolean | Promise<boolean>;
+        add(deliveryId: string): void | Promise<void>;
+    };
 }
 /**
  * Serves a list of code-defined REST tools (built with `defineRestTool`
@@ -381,6 +492,34 @@ interface CreateRuntimeOptions {
      * this is provided.
      */
     channels?: ChannelsOptions;
+    /**
+     * Picks the published version a run uses, per request — canaries, beta
+     * users on `development`, pinning one customer to a version. Applies to
+     * `/chat` and `/voice/sessions`. Return `undefined` for the default.
+     */
+    selectVersion?: (ctx: VersionSelectionContext) => VersionSelection | undefined | Promise<VersionSelection | undefined>;
+    /**
+     * Shortcut for `selectVersion: () => ({ environment })`. Without either,
+     * an Agent runs its editable **draft** for your end users unless its
+     * "serve only deployed versions" policy is on — set this to
+     * `'production'` for a production app. `selectVersion` wins when both are set.
+     */
+    defaultEnvironment?: AgentEnvironment;
+    /**
+     * Lets the browser choose with `environment` / `agentVersion` in the
+     * `/chat` and `/voice/sessions` body (e.g. an internal preview build).
+     * Off by default: otherwise any end user could run an unreleased version.
+     * When on, the browser's choice wins over `selectVersion`.
+     * @default false
+     */
+    allowClientVersionSelection?: boolean;
+    /**
+     * Forward the incoming `traceparent` header to Persona on `/chat`, so the
+     * run's spans join your own OpenTelemetry trace. @default true
+     */
+    forwardTraceparent?: boolean;
+    /** Receive Persona webhooks at `POST /webhooks/persona`. See {@link WebhooksOptions}. Unset by default. */
+    webhooks?: WebhooksOptions;
     /** Log level for the runtime — off by default. Overrides the global level set via `setLogLevel()` from `@personaai/sdk`. */
     logLevel?: LogLevel;
     /** Custom logger instance — when provided, `logLevel` is ignored. */
@@ -407,6 +546,9 @@ declare class RuntimeHttpError extends Error {
     constructor(status: number, code: string, message: string);
 }
 
-declare const RUNTIME_VERSION = "0.21.0";
+declare const RUNTIME_VERSION = "0.23.0";
+
+/** The API key scope each capability needs (`*` covers everything). */
+declare const CAPABILITY_SCOPES: Record<keyof RuntimeCapabilities, string[]>;
 
-export { type ChannelsOptions, type CreateRuntimeOptions, type ErrorContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type RcpManifestOptions, type ResolveTwilioChannelUser, type ResolveUser, type RestToolManifestEntry, type RestToolsManifestOptions, 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, type TwilioChannelOptions, type TwilioChannelRequest, type TwilioChannelUser, type VoiceSessionCreateContext, type WorkflowNodeContext, createRuntime };
+export { type AdminActionContext, CAPABILITY_SCOPES, type ChannelsOptions, type CreateRuntimeOptions, type ErrorContext, type FeedbackContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type RcpManifestOptions, type ResolveTwilioChannelUser, type ResolveUser, type RestToolManifestEntry, type RestToolsManifestOptions, 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, type TwilioChannelOptions, type TwilioChannelRequest, type TwilioChannelUser, type VersionSelection, type VersionSelectionContext, type VoiceSessionCreateContext, type WebhookDelivery, type WebhookHandler, type WebhooksOptions, type WorkflowNodeContext, createRuntime };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { ChatMessageInput, CreateRestToolInput, LogLevel, Logger } from '@personaai/sdk';
+import { ChatMessageInput, CreateRestToolInput, AgentEnvironment, LogLevel, Logger } from '@personaai/sdk';
+import { WebhookEventType, WebhookEvent } from '@personaai/sdk/webhooks';
 import { RcpTool } from 'rcp-sdk';
 export { RcpTool } from 'rcp-sdk';
 
@@ -39,6 +40,12 @@ interface RuntimeRequest {
      * auth-required route handler sees it.
      */
     userId: string | null;
+    /**
+     * The exact request body bytes, before JSON parsing. Only needed by
+     * `POST /webhooks/persona` (the signature is over the raw bytes, and a
+     * re-serialised body won't match); adapters set it for that route.
+     */
+    rawBody?: Uint8Array | string;
 }
 
 /** A complete response with a known-length body — every route except streaming chat. */
@@ -78,6 +85,10 @@ interface RunContext {
     messages?: ChatMessageInput[];
     /** Input parameters provided to the workflow run. */
     input?: unknown;
+    /** The environment this run asked for (from `selectVersion`, `defaultEnvironment` or the client). */
+    environment?: 'development' | 'production';
+    /** The published version this run asked for. */
+    agentVersion?: number;
 }
 interface RunResult {
     /** Assembled assistant text (concatenated TEXT_MESSAGE_CHUNK deltas), same as `ChatResult.text`. */
@@ -87,6 +98,14 @@ interface RunResult {
     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;
+    /**
+     * Persona's own id for this run (`RUN_STARTED.runId`): what
+     * `POST /feedback` and `client.traces.getByRunId()` take. Not the
+     * runtime's `x-persona-run-id` resume id.
+     */
+    personaRunId?: string;
+    /** The run's thread (also set when the run created one). */
+    threadId?: string;
 }
 interface ErrorContext {
     userId: string | null;
@@ -128,11 +147,31 @@ interface MemoryWriteContext {
     agentId?: string;
     path: string;
 }
+interface FeedbackContext {
+    userId: string;
+    /** Persona's run id the rating is for. */
+    runId: string;
+    score: 1 | -1;
+    comment?: string;
+    tags?: string[];
+}
+/** A Project-wide admin action taken through an admin capability (deploy, traces, evals). */
+interface AdminActionContext {
+    /** Your user who did it (Persona's audit log only knows the API key). */
+    userId: string;
+    capability: 'deploy' | 'traces' | 'evals';
+    /** e.g. `agent.version.deploy`, `trace.replay`, `eval_run.start`. */
+    action: string;
+    /** Ids the action touched. */
+    target: Record<string, unknown>;
+}
 interface VoiceSessionCreateContext {
     userId: string;
     agentId: string;
     /** Set when the session resumed an existing conversation (optional `threadId` on the request). */
     threadId?: string;
+    environment?: 'development' | 'production';
+    agentVersion?: number;
 }
 /**
  * Lifecycle hooks — the host application's voice inside the runtime's
@@ -163,6 +202,15 @@ interface RuntimeHooks {
     onThreadCreate?(ctx: ThreadCreateContext): void | Promise<void>;
     /** Fires after a memory file is written via `PUT /memory/file`. */
     onMemoryWrite?(ctx: MemoryWriteContext): void | Promise<void>;
+    /**
+     * Fires after a Project-wide change or replay through an admin capability
+     * (publish, deploy, rollback, serve policy, replay, eval run and dataset
+     * changes). Persona's audit log names only the API key, so record your
+     * user here.
+     */
+    onAdminAction?(ctx: AdminActionContext): void | Promise<void>;
+    /** Fires after an end user's rating is saved via `POST /feedback`. */
+    onFeedback?(ctx: FeedbackContext): void | Promise<void>;
     /** Fires after a voice session ticket is minted via `POST /voice/sessions`. */
     onVoiceSessionCreate?(ctx: VoiceSessionCreateContext): void | Promise<void>;
 }
@@ -224,6 +272,69 @@ interface RuntimeCapabilities {
      * end-user-scoped. @default false
      */
     messages?: boolean;
+    /** Project secrets (`/secrets`) — write-only values, but creating/rotating them is configuration. @default false */
+    secrets?: boolean;
+    /** REST tool sources (`/rest-tool-sources`) CRUD + Test Connection. @default false */
+    restToolSources?: boolean;
+    /**
+     * Agent versions (`/agents/:id/versions`, `/agents/:id/deployments`):
+     * publish, diff, stats, deploy, rollback, serve policy. Key scope
+     * `deploy:write`. @default false
+     */
+    deploy?: boolean;
+    /** Traces and replays (`/traces`): every end user's conversations. Key scope `traces:read` (+ `agent:invoke` to replay). @default false */
+    traces?: boolean;
+    /** Datasets and eval runs (`/datasets`, `/eval-runs`). Key scope `eval:run`. @default false */
+    evals?: boolean;
+    /** Budget status and usage stats (`/observe/budget`, `/observe/usage`), read-only. Key scope `traces:read`. @default false */
+    observe?: boolean;
+}
+/** What {@link CreateRuntimeOptions.selectVersion} is asked about. */
+interface VersionSelectionContext {
+    userId: string;
+    agentId: string;
+    /** Which route is starting the run. */
+    kind: 'chat' | 'voice';
+}
+/** Which published version of an Agent a run uses. Empty = the Agent's own default. */
+interface VersionSelection {
+    environment?: AgentEnvironment;
+    /** A published version number; wins over `environment`. */
+    agentVersion?: number;
+}
+/** Handler for one Persona webhook event type. Throw to answer 500, so Persona retries. */
+type WebhookHandler = (event: WebhookEvent, delivery: WebhookDelivery) => void | Promise<void>;
+interface WebhookDelivery {
+    /** `X-Persona-Delivery` — the same on every retry of one delivery. */
+    id: string | undefined;
+    /** `X-Persona-Event`. */
+    type: WebhookEventType;
+}
+/**
+ * Receives Persona's outgoing webhooks (Platform → Observe → Webhooks) at
+ * `POST {mountPath}/webhooks/persona`. Public route: it checks
+ * `X-Persona-Signature` (HMAC-SHA256 over the raw body) instead of
+ * `resolveUser`. Needs the adapter to put the raw body on
+ * `RuntimeRequest.rawBody`.
+ */
+interface WebhooksOptions {
+    /** The endpoint's signing secret (`whsec_…`, shown once when you create the webhook). */
+    secret: string;
+    /** One handler per event type, and/or `'*'` for every event. */
+    on: Partial<Record<WebhookEventType | '*', WebhookHandler>>;
+    /** Reject deliveries whose signature timestamp is further than this from now. @default 300 */
+    toleranceSec?: number;
+    /**
+     * Where handled delivery ids are remembered, so a retried delivery
+     * (same `X-Persona-Delivery`) runs your handler once. `add` is called
+     * only after the handlers succeed. The default keeps the last 1000 ids
+     * in memory (one process); use your database or Redis when running
+     * several instances.
+     */
+    dedupe?: {
+        has(deliveryId: string): boolean | Promise<boolean>;
+        add(deliveryId: string): void | Promise<void>;
+    };
 }
 /**
  * Serves a list of code-defined REST tools (built with `defineRestTool`
@@ -381,6 +492,34 @@ interface CreateRuntimeOptions {
      * this is provided.
      */
     channels?: ChannelsOptions;
+    /**
+     * Picks the published version a run uses, per request — canaries, beta
+     * users on `development`, pinning one customer to a version. Applies to
+     * `/chat` and `/voice/sessions`. Return `undefined` for the default.
+     */
+    selectVersion?: (ctx: VersionSelectionContext) => VersionSelection | undefined | Promise<VersionSelection | undefined>;
+    /**
+     * Shortcut for `selectVersion: () => ({ environment })`. Without either,
+     * an Agent runs its editable **draft** for your end users unless its
+     * "serve only deployed versions" policy is on — set this to
+     * `'production'` for a production app. `selectVersion` wins when both are set.
+     */
+    defaultEnvironment?: AgentEnvironment;
+    /**
+     * Lets the browser choose with `environment` / `agentVersion` in the
+     * `/chat` and `/voice/sessions` body (e.g. an internal preview build).
+     * Off by default: otherwise any end user could run an unreleased version.
+     * When on, the browser's choice wins over `selectVersion`.
+     * @default false
+     */
+    allowClientVersionSelection?: boolean;
+    /**
+     * Forward the incoming `traceparent` header to Persona on `/chat`, so the
+     * run's spans join your own OpenTelemetry trace. @default true
+     */
+    forwardTraceparent?: boolean;
+    /** Receive Persona webhooks at `POST /webhooks/persona`. See {@link WebhooksOptions}. Unset by default. */
+    webhooks?: WebhooksOptions;
     /** Log level for the runtime — off by default. Overrides the global level set via `setLogLevel()` from `@personaai/sdk`. */
     logLevel?: LogLevel;
     /** Custom logger instance — when provided, `logLevel` is ignored. */
@@ -407,6 +546,9 @@ declare class RuntimeHttpError extends Error {
     constructor(status: number, code: string, message: string);
 }
 
-declare const RUNTIME_VERSION = "0.21.0";
+declare const RUNTIME_VERSION = "0.23.0";
+
+/** The API key scope each capability needs (`*` covers everything). */
+declare const CAPABILITY_SCOPES: Record<keyof RuntimeCapabilities, string[]>;
 
-export { type ChannelsOptions, type CreateRuntimeOptions, type ErrorContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type RcpManifestOptions, type ResolveTwilioChannelUser, type ResolveUser, type RestToolManifestEntry, type RestToolsManifestOptions, 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, type TwilioChannelOptions, type TwilioChannelRequest, type TwilioChannelUser, type VoiceSessionCreateContext, type WorkflowNodeContext, createRuntime };
+export { type AdminActionContext, CAPABILITY_SCOPES, type ChannelsOptions, type CreateRuntimeOptions, type ErrorContext, type FeedbackContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type RcpManifestOptions, type ResolveTwilioChannelUser, type ResolveUser, type RestToolManifestEntry, type RestToolsManifestOptions, 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, type TwilioChannelOptions, type TwilioChannelRequest, type TwilioChannelUser, type VersionSelection, type VersionSelectionContext, type VoiceSessionCreateContext, type WebhookDelivery, type WebhookHandler, type WebhooksOptions, type WorkflowNodeContext, createRuntime };