@ixo/oracle-runtime-workers 0.13.0 → 0.15.0

package/src/plugin-api/index.ts

@@ -1,10 +1,16 @@
 /**
  * Plugin authoring surface. A plugin written against `@ixo/oracle-runtime`
  * that uses tools / sub-agents / middlewares / manifest / configSchema /
- * autoDetect / getSharedState compiles unchanged against this module; the
- * only Node-specific hook (`getNestModules`) is replaced by `getRoutes`.
+ * autoDetect / getSharedState / getDecisions compiles unchanged against this
+ * module; the only Node-specific hook (`getNestModules`) is replaced by
+ * `getRoutes`.
  */
 export { OraclePlugin } from './oracle-plugin';
+export type {
+  RequestAdmissionContext,
+  RequestAdmissionResult,
+  RequestDisposition,
+} from './request-admission';
 export type {
   PluginEnv,
   PluginRoute,
@@ -13,8 +19,26 @@ export type {
 export { defineOraclePlugin } from './define-plugin';
 export type { DefineOraclePluginInput } from './define-plugin';
 export { tool } from './tool-helper';
+export {
+  ADMIN_TOOL_ACTION,
+  ADMIN_TOOL_RESOURCE,
+  adminToolCapability,
+  adminToolResource,
+  canAccessToolPlane,
+  requireToolPlane,
+  toolPlaneOf,
+  toolPlaneRequirement,
+} from './tool-plane';
 export type { ToolHelperOptions } from './tool-helper';
 export { UcanMintUnavailableError } from './ucan-errors';
+export {
+  USER_KV_MAX_ENTRIES_PER_NAMESPACE,
+  USER_KV_MAX_TOTAL_BYTES,
+  USER_KV_MAX_TOTAL_ENTRIES,
+  USER_KV_MAX_VALUE_BYTES,
+  UserKvLimitError,
+} from '../core/user-kv';
+export type { UserKvLimitKind } from '../core/user-kv';
 export type {
   ActionCallEventPayload,
   AgentMiddleware,
@@ -49,8 +73,25 @@ export type {
   RouterEventPayload,
   RuntimeContext,
   SecretIndex,
+  SessionSurface,
   SharedAccessors,
   ToolCallEventPayload,
+  ToolPlane,
   UcanDelegation,
   UserContextData,
+  UserKvSurface,
+  UserKvWriteOptions,
 } from './types';
+export { defineDecision } from '@ixo/common/ai/decisions';
+export type {
+  DecisionAdapter,
+  DecisionAnswer,
+  DecisionDefinition,
+  DecisionEvaluateOptions,
+  DecisionEvaluation,
+  DecisionProviderResult,
+  DecisionQuestion,
+  DecisionRegistration,
+  DecisionRequest,
+  DefineDecisionOptions,
+} from '@ixo/common/ai/decisions';

package/src/plugin-api/oracle-plugin.ts

@@ -1,3 +1,8 @@
+import type { DecisionRegistration } from '@ixo/common/ai/decisions';
+import type {
+  RequestAdmissionContext,
+  RequestAdmissionResult,
+} from './request-admission';
 import type { z } from 'zod';
 import type { PluginRoute } from '../shell/app';
 import type {
@@ -53,6 +58,19 @@ export abstract class OraclePlugin {
   /** The agent's structured interface to this plugin. */
   abstract readonly manifest: PluginManifest;
 
+  /**
+   * How the agent should work with this plugin once it is in use: the
+   * plugin's working rules, as plain text (markdown, starting at a `###`
+   * heading). Never part of the manifest, the Tier-1 capability block or
+   * `list_capabilities`, so it costs nothing on turns that do not use the
+   * plugin. `load_capability` returns it (once per turn) when it loads the
+   * plugin or the capability router preloaded it for the turn, and the
+   * system prompt carries it on every turn that starts with the plugin
+   * loaded on the thread (or `always` visible) and usable by the user's
+   * delegation.
+   */
+  readonly operatingGuide?: string;
+
   /** Hard dependencies — boot fails if any is missing. */
   readonly dependsOn?: string[];
 
@@ -83,6 +101,13 @@ export abstract class OraclePlugin {
   /** Sub-agents the runtime auto-wraps as tools. */
   getSubAgents?(ctx: PluginContext): PluginSubAgent[];
 
+  /**
+   * Bounded semantic decisions contributed by this plugin. Decisions are
+   * side-effect-free and are never exposed to the generative agent unless a
+   * plugin explicitly wraps one in a tool.
+   */
+  getDecisions?(ctx: PluginContext): DecisionRegistration[];
+
   /**
    * Request-time tool contributions. Called once per `createMainAgent`
    * invocation with the full per-request `RuntimeContext`, so the plugin
@@ -110,6 +135,16 @@ export abstract class OraclePlugin {
    */
   getMiddlewares?(ctx: PluginContext): AgentMiddleware[];
 
+  /** Per-turn extensions for the ordinary agent; never cached across users. */
+  getRequestMiddlewares?(
+    ctx: RuntimeContext,
+  ): AgentMiddleware[] | Promise<AgentMiddleware[]>;
+
+  /** Runs before agent preparation. Only authorized deterministic reads may be handled. */
+  getRequestAdmission?(
+    ctx: RequestAdmissionContext,
+  ): RequestAdmissionResult | Promise<RequestAdmissionResult>;
+
   /**
    * Read-only accessors this plugin exposes to other plugins via `ctx.shared`.
    * Pattern: this plugin computes/owns some derived value from state; others

package/src/plugin-api/request-admission.ts

@@ -0,0 +1,41 @@
+import type { MergedConfig, RuntimeContext } from './types';
+
+/**
+ * Authenticated, request-local input. Deliberately exposes no model or tools.
+ *
+ * `config` is not the merged env: it carries the plugin's own `configSchema`
+ * keys and the core settings without credentials (no LLM provider key, no
+ * Matrix password or recovery phrase, no Cloudflare API token).
+ *
+ * The host only asks for admission on direct-room and Portal turns, never on
+ * a group-room turn (a direct read is posted into the room, where every
+ * member would see one user's authorized data) or a scheduled task run.
+ * `roomKind` is still passed so a handler can refuse anything it would not
+ * show to the whole room.
+ */
+export interface RequestAdmissionContext {
+  readonly config: MergedConfig;
+  readonly user: RuntimeContext['user'];
+  readonly session: RuntimeContext['session'] & {
+    /** Matrix turns: the room the turn arrived in is a direct or a group room. */
+    readonly roomKind?: 'direct' | 'group';
+    /** Matrix turns: the user's message event this turn answers. */
+    readonly eventId?: string;
+    /** Matrix turns: the thread root when the user replied inside a thread. */
+    readonly threadId?: string;
+  };
+  readonly message: string;
+  readonly metadata?: Record<string, unknown>;
+  /** Aborted when the turn is cancelled or the handler's time limit passes. */
+  readonly signal: AbortSignal;
+}
+
+export type RequestAdmissionResult =
+  | { kind: 'pass' }
+  | { kind: 'handled'; text: string; title: string };
+
+/** Persisted by the host, never accepted from a client. */
+export type RequestDisposition =
+  | { kind: 'admitting' }
+  | { kind: 'agent' }
+  | { kind: 'direct-read'; text: string; title: string; messageId: string };

package/src/plugin-api/tool-helper.ts

@@ -17,11 +17,20 @@ export interface ToolHelperOptions {
    * `manifest.visibility` setting.
    */
   visibility?: PluginTool['visibility'];
+  /**
+   * Privilege plane. Defaults to `orchestration`; `admin` marks a tool the
+   * user must explicitly delegate (`adminToolCapability`) before the model
+   * may see or run it — authority, credential or similar lifecycle
+   * operations. See `PluginTool.plane`.
+   */
+  plane?: PluginTool['plane'];
   /**
    * `'read'` for a tool with no external effect (safe to run again when a
    * turn resumes after a reset); omitted or `'write'` otherwise.
    */
   effect?: PluginTool['effect'];
+  /** Same arguments again is a new action (a UI step); see `PluginTool.repeatable`. */
+  repeatable?: PluginTool['repeatable'];
   /**
    * Billing gate marker, kept for source compatibility with the Node
    * runtime's plugin contract. The Workers runtime has no commerce lane, so
@@ -54,7 +63,16 @@ export function tool(
   if (!options || typeof options !== 'object') {
     throw new TypeError('tool(handler, options): `options` is required.');
   }
-  const { name, description, schema, visibility, billing, effect } = options;
+  const {
+    name,
+    description,
+    schema,
+    visibility,
+    plane,
+    billing,
+    effect,
+    repeatable,
+  } = options;
   if (!name || typeof name !== 'string') {
     throw new TypeError(
       'tool(handler, options): `options.name` must be a non-empty string.',
@@ -80,11 +98,17 @@ export function tool(
   if (visibility !== undefined) {
     pluginTool.visibility = visibility;
   }
+  if (plane !== undefined) {
+    pluginTool.plane = plane;
+  }
   if (billing !== undefined) {
     pluginTool.billing = billing;
   }
   if (effect !== undefined) {
     pluginTool.effect = effect;
   }
+  if (repeatable !== undefined) {
+    pluginTool.repeatable = repeatable;
+  }
   return pluginTool;
 }

package/src/plugin-api/tool-plane.ts

@@ -0,0 +1,92 @@
+import type { PluginTool, RuntimeContext, ToolPlane } from './types';
+
+/**
+ * The ability every admin-tool capability names. Namespaced because a UCAN
+ * ability must be `*` or `<ns>/<name>` (`@ixo/ucan` refuses to issue a bare
+ * `invoke`); a grant of `admin-tool/*` or `*` covers it too.
+ */
+export const ADMIN_TOOL_ACTION = 'admin-tool/invoke';
+
+/**
+ * Root of the admin-tool resources. One admin tool is
+ * `ixo:qiforge:admin-tool/<pluginName>/<toolName>`; under the runtime's
+ * resource rule (a grant covers itself and every `/` child, `*` covers
+ * everything) a grant on `ixo:qiforge:admin-tool/<pluginName>` covers all of
+ * that plugin's admin tools and one on this root covers every admin tool.
+ */
+export const ADMIN_TOOL_RESOURCE = 'ixo:qiforge:admin-tool';
+
+type ToolPlaneDescriptor = Pick<PluginTool, 'name' | 'plane'>;
+
+/** A tool's plane; undeclared is `orchestration`. */
+export function toolPlaneOf(tool: Pick<PluginTool, 'plane'>): ToolPlane {
+  return tool.plane ?? 'orchestration';
+}
+
+function segment(kind: string, value: string): string {
+  if (value.length === 0 || value.includes('/')) {
+    // A `/` would make one tool's resource the parent of another's (plugin
+    // `a` tool `b/c` vs plugin `a/b` tool `c`), so the grant rule could no
+    // longer tell them apart.
+    throw new TypeError(
+      `admin tool ${kind} must be a non-empty name without "/" (got "${value}")`,
+    );
+  }
+  return value;
+}
+
+/** `ixo:qiforge:admin-tool/<pluginName>/<toolName>`. */
+export function adminToolResource(
+  pluginName: string,
+  toolName: string,
+): string {
+  return `${ADMIN_TOOL_RESOURCE}/${segment('plugin name', pluginName)}/${segment('tool name', toolName)}`;
+}
+
+/** The capability the user's delegation must grant for this admin tool. */
+export function adminToolCapability(
+  pluginName: string,
+  toolName: string,
+): { resource: string; action: string } {
+  return {
+    resource: adminToolResource(pluginName, toolName),
+    action: ADMIN_TOOL_ACTION,
+  };
+}
+
+/**
+ * The capability `tool` requires of the turn's delegation, or `null` for an
+ * orchestration tool. This is the tool-level counterpart of a manifest's
+ * `requires`; every check (binding, discovery, the call itself) reads it.
+ */
+export function toolPlaneRequirement(
+  pluginName: string,
+  tool: ToolPlaneDescriptor,
+): { resource: string; action: string } | null {
+  return toolPlaneOf(tool) === 'admin'
+    ? adminToolCapability(pluginName, tool.name)
+    : null;
+}
+
+/** Whether the delegation behind `ctx` reaches `tool`. */
+export function canAccessToolPlane(
+  ctx: Pick<RuntimeContext, 'ucan'>,
+  pluginName: string,
+  tool: ToolPlaneDescriptor,
+): boolean {
+  const required = toolPlaneRequirement(pluginName, tool);
+  return (
+    required === null ||
+    ctx.ucan.hasCapability(required.resource, required.action)
+  );
+}
+
+/** Throws (`ctx.ucan.requireCapability`) unless the delegation behind `ctx` reaches `tool`. */
+export function requireToolPlane(
+  ctx: Pick<RuntimeContext, 'ucan'>,
+  pluginName: string,
+  tool: ToolPlaneDescriptor,
+): void {
+  const required = toolPlaneRequirement(pluginName, tool);
+  if (required) ctx.ucan.requireCapability(required.resource, required.action);
+}

package/src/plugin-api/types.ts

@@ -1,8 +1,15 @@
+import type { TaskExecutionProfile } from '../core/execution-profile';
+import type {
+  DecisionDefinition,
+  DecisionEvaluateOptions,
+  DecisionEvaluation,
+} from '@ixo/common/ai/decisions';
 import type { z } from 'zod';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { UserPreferences } from '../core/state';
 import type { AttachmentViewSurface } from '../attachments/view';
+import type { DeliveryConfig } from '../delivery/profile';
 
 /**
  * Route shape returned by `OraclePlugin.getAuthExcludedRoutes()`. Paths are
@@ -55,6 +62,13 @@ export interface UcanDelegation {
   readonly issuer?: string;
   readonly audience?: string;
   readonly capabilities?: ReadonlyArray<{ resource: string; action: string }>;
+  /**
+   * When the delegation stops granting anything (Unix seconds; the earliest
+   * expiry across its proof chain). Capability checks compare it with the
+   * clock at every check, so a delegation that lapses mid-turn grants
+   * nothing from then on.
+   */
+  readonly expiration?: number;
 }
 
 /** Per-room secret index. */
@@ -360,6 +374,16 @@ export interface PluginManifest {
 
   /** Stability hint surfaced to the agent (`experimental` → warning footnote). */
   stability?: 'stable' | 'beta' | 'experimental';
+
+  /**
+   * UCAN capabilities the user's delegation to this oracle must grant before
+   * the plugin may be used by that user (`ctx.ucan.hasCapability` semantics:
+   * the action may be `*`). While one is missing, `load_capability` refuses
+   * the plugin and names what is missing, `list_capabilities` marks it
+   * unavailable, and its tools are neither shown to nor run by the model —
+   * whatever its visibility. Omitted: no requirement.
+   */
+  requires?: ReadonlyArray<{ resource: string; action: string }>;
 }
 
 export interface ManifestExample {
@@ -424,6 +448,13 @@ export interface OracleConfig {
   description?: string;
   /** Optional prompt customization (opening, communicationStyle, capabilities). */
   prompt?: OraclePromptConfig;
+  /**
+   * Chat delivery (WhatsApp through IXO Channels, Matrix rooms): replies
+   * arrive as short messages with long content moved to artefacts. Matrix
+   * rooms use it only with `matrixChat: true` (or `MATRIX_CHAT_DELIVERY=true`,
+   * which wins when set); otherwise a room reply stays one message.
+   */
+  delivery?: DeliveryConfig;
 }
 
 /**
@@ -476,6 +507,11 @@ export interface MatrixPostOpts {
   txnId?: string;
 }
 
+/** `ctx.session.surface`: the delivery surface of the turn. */
+export type SessionSurface =
+  | { kind: 'stream' }
+  | { kind: 'chat'; surface: string; label: string };
+
 export interface RuntimeContext<TConfig = MergedConfig> {
   /** Authenticated user identity (validated by core auth middleware). */
   user: {
@@ -491,10 +527,16 @@ export interface RuntimeContext<TConfig = MergedConfig> {
   session: {
     /** = `thread_id`; thread root `eventId`. */
     id: string;
-    client: 'portal' | 'matrix' | 'slack';
+    client: 'portal' | 'matrix' | 'slack' | 'channel';
     wsId?: string;
     requestId: string;
     roomId?: string;
+    /**
+     * Where the reply lands. `stream` is the Portal; `chat` is a chat app
+     * (WhatsApp through IXO Channels, a Matrix room) where the reply arrives
+     * as short messages. Tools can keep their output compact on `chat`.
+     */
+    surface?: SessionSurface;
   };
 
   /** Read-only view over the graph state's history. */
@@ -520,6 +562,12 @@ export interface RuntimeContext<TConfig = MergedConfig> {
   secrets: {
     getIndex: () => Promise<SecretIndex>;
     getValues: (keys: string[]) => Promise<Record<string, string>>;
+    /**
+     * Values of every secret `getIndex` lists, read with one lookup of the
+     * room's secret index — use it instead of `getIndex` followed by
+     * `getValues` of every key. `{}` without a room.
+     */
+    getAll: () => Promise<Record<string, string>>;
   };
 
   /**
@@ -671,6 +719,23 @@ export interface RuntimeContext<TConfig = MergedConfig> {
     >;
   };
 
+  /**
+   * Bounded semantic decisions. A decision only returns structured judgment;
+   * policy, authority checks, and side effects remain outside this primitive.
+   */
+  decisions: {
+    evaluate<TSchema extends z.ZodType>(
+      definition: DecisionDefinition<TSchema>,
+      input: z.input<TSchema>,
+      options?: DecisionEvaluateOptions,
+    ): Promise<DecisionEvaluation>;
+    evaluateByName(
+      name: string,
+      input: unknown,
+      options?: DecisionEvaluateOptions,
+    ): Promise<DecisionEvaluation>;
+  };
+
   /** LLM provider. */
   llm: {
     get: (role: ModelRole, params?: ChatOpenAIFields) => BaseChatModel;
@@ -706,6 +771,15 @@ export interface RuntimeContext<TConfig = MergedConfig> {
    */
   preferences?: UserPreferencesSurface;
 
+  /**
+   * Host key-value rows in the user's OWN database, for plugin state that
+   * must outlive the in-memory plugin instance (on Workers the user's object
+   * is evicted when idle and restored from the owner copy; rows written here
+   * travel with that copy). Present when the host persists per-user state
+   * (the Workers runtime does); absent elsewhere.
+   */
+  kv?: UserKvSurface;
+
   /**
    * Host bridge to the user's browser over the realtime (socket.io) channel:
    * browser tools declared by the client (`state.browserTools`) and AG-UI
@@ -777,6 +851,7 @@ export type OracleTaskSchedule =
 
 /** Stored task record (persisted in the user's own database → owner file). */
 export interface OracleTaskRecord {
+  executionProfile?: TaskExecutionProfile;
   id: string;
   title: string;
   /** Markdown intent body — what the agent should do each run. */
@@ -799,6 +874,8 @@ export interface OracleTaskRecord {
 }
 
 export interface OracleTaskInput {
+  /** Host-only closed execution profile; never exposed by model task tools. */
+  executionProfile?: TaskExecutionProfile;
   title: string;
   intent: string;
   schedule: OracleTaskSchedule;
@@ -812,11 +889,14 @@ export interface OracleTaskInput {
 }
 
 /**
- * Bridge to the user's browser over the realtime channel. Both calls emit the
- * corresponding event (`browser_tool_call` / `action_call`) to the sockets
- * subscribed to `sessionId` and resolve with the browser's answer, rejecting
- * on the browser's `error`, an AG-UI `success: false`, or the timeout —
- * exactly the Node runtime's `callBrowserTool` / `callAgAction` contract.
+ * Bridge to the user's browser over the realtime channel. Each call is one
+ * invocation with its own id, sent (`browser_tool_call` / `action_call`) to
+ * ONE authenticated socket of `sessionId`; only that socket's answer settles
+ * it. It resolves with the browser's answer and rejects on the browser's
+ * `error`, an AG-UI `success: false`, or when no socket could take it. When
+ * the answer cannot arrive — the deadline passed or the socket went — it
+ * resolves with `FRONTEND_OUTCOME_UNKNOWN` (`@ixo/common/ai/frontend-bridge`):
+ * the browser may have performed the action, and it is never sent again.
  */
 export interface FrontendCallSurface {
   callBrowserTool(params: FrontendCallParams): Promise<unknown>;
@@ -827,11 +907,20 @@ export interface FrontendCallSurface {
 
 export interface FrontendCallParams {
   sessionId: string;
+  /** The caller's id; the invocation id the browser sees is `<toolCallId>:<uuid>`. */
   toolCallId: string;
   toolName: string;
   args: Record<string, unknown>;
   /** Default 15 s (browser tools) / 10 s (AG-UI actions), as on Node. */
   timeoutMs?: number;
+  /** Receives the invocation id once the call is registered (for diagnostics). */
+  onInvocation?: (invocationId: string) => void;
+  /**
+   * The turn's abort signal (`ctx.abortSignal`). Aborted before the call is
+   * sent, it rejects as not sent; after, it resolves with
+   * `FRONTEND_OUTCOME_UNKNOWN` at once — the browser may already have run it.
+   */
+  signal?: AbortSignal;
 }
 
 /**
@@ -861,6 +950,8 @@ export interface OracleTasksSurface {
   ): Promise<{ resolved: boolean }>;
 }
 
+export type ToolPlane = 'orchestration' | 'admin';
+
 export interface PluginTool {
   name: string;
   description: string;
@@ -868,6 +959,15 @@ export interface PluginTool {
   handler: (args: unknown, ctx: RuntimeContext) => Promise<unknown>;
   /** Override visibility — by default inherits from the plugin's `manifest.visibility`. */
   visibility?: 'always' | 'on-demand' | 'silent';
+  /**
+   * Privilege plane. `orchestration` is the default. An `admin` tool exists
+   * for a turn only when the user's delegation to the oracle grants
+   * `adminToolCapability(pluginName, name)`: otherwise it is never bound or
+   * listed, and the capability is checked again right before the handler.
+   * That grant is the user's consent, not operator authority — a user can
+   * issue it for themselves.
+   */
+  plane?: ToolPlane;
   /**
    * Whether calling the tool changes anything outside the conversation.
    * `'read'` tools may be executed again when a turn is resumed after a
@@ -876,6 +976,14 @@ export interface PluginTool {
    * outcome is unknown. See `core/middlewares/tool-marks.ts`.
    */
   effect?: 'read' | 'write';
+  /**
+   * `true` when calling the tool again with the same arguments is a new,
+   * intended action rather than a repeat — a step in the user's browser
+   * such as scrolling or paging. Within one turn the repetition guard lets
+   * such a tool run up to its read limit (5 identical calls) instead of once;
+   * `effect` still governs retries, write claims and resume.
+   */
+  repeatable?: boolean;
   /**
    * Billing gate. `'contracted'` marks a tool that performs paid contracted
    * work: the runtime binds it only while the turn runs inside an active work
@@ -924,3 +1032,83 @@ export interface UserPreferencesSurface {
     partial: Partial<UserPreferences>,
   ): Promise<UserPreferences>;
 }
+
+/**
+ * Bounds applied by a write to {@link UserKvSurface}. Both are optional; an
+ * entry written without `idleTtlMs` never expires, and a write without
+ * `maxEntries` evicts nothing. They come on top of the store's hard caps
+ * (see {@link UserKvSurface}), which no option lifts.
+ */
+export interface UserKvWriteOptions {
+  /**
+   * Idle lifetime: the entry expires once this long passes without a read or
+   * a write of it. Every hit slides the deadline.
+   */
+  idleTtlMs?: number;
+  /**
+   * After the write, drop the namespace's expired entries, then the least
+   * recently used ones until at most this many remain. At most
+   * `USER_KV_MAX_ENTRIES_PER_NAMESPACE` (10,000); a larger value is rejected
+   * with a `RangeError`, not clamped.
+   */
+  maxEntries?: number;
+}
+
+/**
+ * Key-value rows in the user's own database, grouped by namespace (a plugin
+ * uses its own name as the prefix, e.g. `pod-creator/blueprints`). Namespaces
+ * are a naming convention, not isolation: every plugin of the oracle sees the
+ * same surface and can read or write any namespace. Plugins are trusted code
+ * the operator chose to load; do not rely on namespaces to keep a plugin out
+ * of another's rows. Values are
+ * JSON: what goes in is serialised, what comes out is the parsed copy, so a
+ * caller never shares an object with the store. Reads and writes mark an
+ * entry most recently used and slide its idle deadline (LRU + idle TTL, the
+ * semantics of an in-memory bounded map, but durable).
+ *
+ * The rows share the user's file with their checkpoints, sessions and
+ * transcript, so the store enforces hard caps no plugin can opt out of:
+ *
+ * - one value: `USER_KV_MAX_VALUE_BYTES` (256 KiB) of UTF-8 JSON;
+ * - one namespace: `USER_KV_MAX_ENTRIES_PER_NAMESPACE` (10,000) entries;
+ * - all namespaces together: `USER_KV_MAX_TOTAL_ENTRIES` (50,000) entries
+ *   and `USER_KV_MAX_TOTAL_BYTES` (32 MiB), counting the UTF-8 bytes of
+ *   namespace, key and value JSON of every row.
+ *
+ * A `set` / `update` that would break one rejects with `UserKvLimitError`
+ * (`limit`, `max`, `actual`, `namespace`): nothing is written and nothing
+ * is evicted to make room — the previous value, if any, stays. Expired
+ * entries of every namespace are swept before a write is refused, and
+ * replacing an entry counts only the difference in size. Keep plugin state
+ * bounded with `idleTtlMs` / `maxEntries` rather than relying on the caps.
+ */
+export interface UserKvSurface {
+  /** The stored value, or `undefined` when absent or expired. */
+  get(namespace: string, key: string): Promise<unknown>;
+  /**
+   * Store a JSON-serialisable value. Rejects with `UserKvLimitError` when
+   * the write would break a hard cap.
+   */
+  set(
+    namespace: string,
+    key: string,
+    value: unknown,
+    options?: UserKvWriteOptions,
+  ): Promise<void>;
+  /**
+   * Atomic read-modify-write: `fn` receives the current value (`undefined`
+   * when absent or expired) and returns the new one; returning `undefined`
+   * deletes the entry. No other write to the store interleaves. `fn` must be
+   * synchronous and free of side effects — the host may run it again when a
+   * storage read has to be retried. Resolves with the value written; rejects
+   * with `UserKvLimitError` (the entry left as it was) when the new value
+   * would break a hard cap. Deleting is never refused.
+   */
+  update(
+    namespace: string,
+    key: string,
+    fn: (current: unknown) => unknown,
+    options?: UserKvWriteOptions,
+  ): Promise<unknown>;
+  delete(namespace: string, key: string): Promise<void>;
+}