@voltro/ai 0.63.0 → 0.65.0

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { EmbeddingModelV4 } from '@ai-sdk/provider';
 import { Experimental_VideoModelV4 } from '@ai-sdk/provider';
 import { extractReasoningMiddleware } from 'ai';
 import { GatewayLanguageModelEntry } from '@ai-sdk/gateway';
+import { Guards } from '@voltro/protocol';
 import { ImageModelV4 } from '@ai-sdk/provider';
 import { LanguageModelMiddleware } from 'ai';
 import { LanguageModelV4 } from '@ai-sdk/provider';
@@ -37,6 +38,31 @@ export declare const AGENT_MESSAGES_TABLE = "_voltro_agent_messages";
 /** Thread metadata table (one row per conversation). */
 export declare const AGENT_THREADS_TABLE = "_voltro_agent_threads";
 
+/**
+ * WHO MAY TALK TO an agent — the same three-state decision a mutation makes,
+ * applied to BOTH synthesized routes (`<name>.send` and `<name>.messages`).
+ *
+ * The two routes used to carry a hard-coded `openAccess`, honestly worded:
+ * "serves any session this app authenticates; defineAgent declares no per-agent
+ * guard vocabulary today". That sentence made every agent a free model-spend
+ * surface for anyone who could open the socket — anonymous included, since the
+ * routes never looked at the subject — and it made the boot gate's carve-out
+ * ("synthesized routes are not the app's to guard") true only because there
+ * was nothing on the descriptor to read. There is now, so the gate judges an
+ * agent like a workflow: one that declares neither refuses the boot under
+ * `security.defaultDeny`.
+ */
+export declare interface AgentAccessOptions {
+    /** A caller must hold a scope (`{ scope: 'support:chat' }`), or a
+     *  relationship to the thread (`{ action, resourceType, resource: (i) =>
+     *  i.threadId }`). Checked on every `send` and on every `messages` delivery. */
+    readonly guards?: Guards<AgentRouteInput>;
+    /** Anyone who can open the socket may talk to it — and WHY. A reason, not a
+     *  boolean. Note what it does NOT buy: an anonymous caller owns no thread, so
+     *  thread privacy (below) is only enforced for authenticated subjects. */
+    readonly openAccess?: string;
+}
+
 /** Stamp an agent-initiated call's actor with `via: 'agent'` so audit + trace
  *  + provenance (08) can distinguish "user X" from "user X via agent". The
  *  actor id stays the calling subject's — the agent never escalates identity. */
@@ -52,6 +78,9 @@ export declare interface AgentDescriptor<S extends Schema.Schema.Any = DefaultAg
     /** Input schema (default `{ prompt: string }`). The send route's wire input
      *  extends this with `{ threadId, order }`. */
     readonly input?: S;
+    /** WHO MAY TALK TO IT — see {@link AgentAccessOptions}. */
+    readonly guards?: Guards<AgentRouteInput>;
+    readonly openAccess?: string;
 }
 
 /** Error taxonomy. `retryable` on the event drives client/agent retry. */
@@ -201,7 +230,7 @@ export declare const agentMessagesTable: Table<typeof AGENT_MESSAGES_TABLE, Reco
 export declare const agentRouteDescriptors: (desc: AnyAgentDescriptor) => {
     send: ActionProcedureDescriptor<`${string}.send`, Schema.Schema.Any, Schema.Struct<{
         text: typeof Schema.String;
-    }>, typeof Schema.Never>;
+    }>, typeof AgentThreadAccessDenied>;
     messages: QueryProcedureDescriptor<`${string}.messages`, Schema.Struct<{
         threadId: typeof Schema.String;
     }>, Schema.Array$<Schema.Struct<{
@@ -218,17 +247,40 @@ export declare const agentRouteDescriptors: (desc: AnyAgentDescriptor) => {
             readonly key: typeof Schema.String;
             readonly value: typeof Schema.Unknown;
         }]>>;
-    }>>, typeof Schema.Never>;
+    }>>, typeof AgentThreadAccessDenied>;
 };
 
+/** The one field both synthesized routes share on the wire — what a
+ *  resource-scoped agent guard may read its id from. */
+export declare interface AgentRouteInput {
+    readonly threadId: string;
+}
+
 export declare interface AgentThread {
     readonly id: string;
     readonly tenantId: string | null;
+    readonly subjectId: string | null;
     readonly title: string | null;
     readonly createdAt: Date;
     readonly updatedAt: Date;
 }
 
+/**
+ * A thread belongs to the subject that opened it. Raised by `<name>.send` and
+ * `<name>.messages` when an authenticated caller addresses a thread another
+ * subject created — the isolation the old `openAccess` sentence said it could
+ * not claim. In the routes' error union, so it reaches the client typed.
+ */
+export declare class AgentThreadAccessDenied extends AgentThreadAccessDenied_base {
+    get message(): string;
+}
+
+declare const AgentThreadAccessDenied_base: Schema.TaggedErrorClass<AgentThreadAccessDenied, "AgentThreadAccessDenied", {
+    readonly _tag: Schema.tag<"AgentThreadAccessDenied">;
+} & {
+    threadId: typeof Schema.String;
+}>;
+
 export declare const agentThreadsTable: Table<typeof AGENT_THREADS_TABLE, Record<string, ColumnDefinition<unknown>>, true>;
 
 export declare const AI_BUDGET_TABLE = "_voltro_ai_budget";
@@ -745,6 +797,7 @@ export declare interface CostBreakdown {
 /** Open a new thread (the store generates the id). */
 export declare const createThread: (store: DataStore, input?: {
     readonly tenantId?: string | null;
+    readonly subjectId?: string | null;
     readonly title?: string | null;
 }) => Effect.Effect<AgentThread>;
 
@@ -880,7 +933,7 @@ export { defaultSettingsMiddleware }
 export declare const defineAgent: <S extends Schema.Schema.Any = DefaultAgentInputSchema>(config: {
     readonly name: string;
     readonly input?: S;
-}) => AgentDescriptor<S>;
+} & AgentAccessOptions) => AgentDescriptor<S>;
 
 /**
  * Bind a server executor to its descriptor. Default-export the result from
@@ -1018,6 +1071,24 @@ export declare type EmbeddingProviderName = 'mock' | 'openai' | 'voyage' | 'cohe
  */
 export declare const embedMany: (texts: ReadonlyArray<string>, config?: EmbeddingProviderConfig) => Effect.Effect<ReadonlyArray<ReadonlyArray<number>>, AiError>;
 
+/**
+ * The ownership rule, in one place for both synthesized routes.
+ *
+ * `threadId` is caller-supplied, so the first message on an id is what opens
+ * the thread: the row is created then, owned by the caller. Every later call
+ * on that id compares owners — a thread with an owner refuses every OTHER
+ * authenticated subject with `AgentThreadAccessDenied`; a thread with none
+ * (opened anonymously, or before ownership existed) admits anyone, because a
+ * row that records no owner cannot honestly claim one.
+ *
+ * Returns the thread. Never a silent `null`: a refusal is the typed error.
+ */
+export declare const ensureThreadOwned: (store: DataStore, input: {
+    readonly threadId: string;
+    readonly subjectId: string | null;
+    readonly tenantId?: string | null;
+}) => Effect.Effect<AgentThread, AgentThreadAccessDenied>;
+
 /**
  * Derive a USD cost from a token `usage` tally + a model price. An
  * unknown model (or the `mock` provider) resolves to zero cost rather
@@ -1462,6 +1533,14 @@ export declare interface GenerateSpeechResult {
 export declare const generateText: (options: GenerateTextOptions) => Effect.Effect<GenerateTextResult, AiError>;
 
 export declare interface GenerateTextOptions {
+    /** Tools the model may call on the way to its answer — the same tool-loop
+     *  `generateObjectWithTools` runs, for a TEXT result. With tools, `usage` is
+     *  the SUM over every step, so a usage row records the whole loop. */
+    readonly tools?: Record<string, AnyTool>;
+    /** Max LLM↔tool round-trips before the model must answer. Default 8. */
+    readonly maxSteps?: number;
+    /** Request context threaded into the tool executors. */
+    readonly toolContext?: ToolContext;
     /** The user prompt. The SDK auto-wraps it as the single user message. */
     readonly prompt: string;
     /** Optional system message. Steers the model independently of the prompt. */
@@ -1746,8 +1825,14 @@ export declare const knowledgeCutoffOf: (raw: RawGatewayModel) => string | undef
  */
 export declare const llmJudge: EvalJudge;
 
-/** The synthesized `<name>.messages` body — load the thread's messages. */
-export declare const loadAgentMessages: (store: DataStore, threadId: string) => Effect.Effect<ReadonlyArray<AgentMessage>>;
+/**
+ * The synthesized `<name>.messages` body — load the thread's messages, for the
+ * subject that owns the thread. Same rule as `send`: an owned thread refuses
+ * every other authenticated subject; an unknown or unowned thread reads as
+ * its rows (empty, for an id nobody has written to). Re-checked on every
+ * reactive delivery, since the query re-runs its executor.
+ */
+export declare const loadAgentMessages: (store: DataStore, threadId: string, subjectId?: string | null) => Effect.Effect<ReadonlyArray<AgentMessage>, AgentThreadAccessDenied>;
 
 /**
  * A middleware that logs every generate/stream call's model (and token usage
@@ -2490,18 +2575,14 @@ export declare type ProviderConfig = {
  */
 export declare type ProviderFallbacks = ReadonlyArray<ProviderConfig>;
 
+export declare const providerFromEnv: (env?: Record<string, string | undefined>) => ProviderConfig;
+
 /**
- * Read the provider config. The process-global override (set by `useMockAi`)
- * wins over env. Otherwise honours:
- *   AI_PROVIDER=mock|anthropic|openai|gateway   (default: mock)
- *   AI_MODEL=<model-id>   (default per provider: 'claude-opus-4-8' for
- *                          anthropic, 'gpt-5.5' for openai, 'mock' for mock;
- *                          REQUIRED for gateway — a `creator/model` id)
- *
- * Provider keys are read by the underlying AI SDK packages from their standard
- * env vars: ANTHROPIC_API_KEY, OPENAI_API_KEY, AI_GATEWAY_API_KEY.
+ * The env var a provider's SDK reads its key from — `undefined` for `mock`,
+ * which needs none. ONE map, exported, so the boot gate that checks a key is
+ * present cannot drift from the provider that reads it.
  */
-export declare const providerFromEnv: (env?: Record<string, string | undefined>) => ProviderConfig;
+export declare const providerKeyEnvVar: (name: string) => string | undefined;
 
 export declare type ProviderName = 'mock' | 'anthropic' | 'openai' | 'gateway';
 
@@ -2989,11 +3070,15 @@ export declare const runAgentTurn: (exec: AnyAgentExecutor, store: DataStore, ar
     readonly threadId: string;
     readonly input: unknown;
     readonly tenantId?: string | null;
+    /** The caller — `null` for an anonymous subject. Opens the thread on its
+     *  first message and is checked against the thread's owner on every later
+     *  one (`ensureThreadOwned`). Omitted ⇒ treated as anonymous. */
+    readonly subjectId?: string | null;
     readonly order: number;
     readonly toolContext?: ToolContext;
     readonly throttleMs?: number;
     readonly promptOf?: (input: unknown) => string;
-}) => Effect.Effect<string, Error>;
+}) => Effect.Effect<string, Error | AgentThreadAccessDenied>;
 
 /**
  * Drive a streaming assistant turn end-to-end against the persisted row.
@@ -3028,6 +3113,18 @@ export declare interface RunAssistantInput {
     readonly order: number;
     /** Throttle window for the live `parts` patch. Default 100ms. */
     readonly throttleMs?: number;
+    /** The agent this turn belongs to — stamped onto the usage ledger row so
+     *  spend is attributable per agent. The synthesized send passes its name. */
+    readonly agent?: string;
+    /**
+     * Record the turn's token usage into `_voltro_ai_usage` (default `true`).
+     * A tool loop is a model call like any other, and this was the one path
+     * that spent without recording: `aiStep` records, and the agent turn — which
+     * owns a store by construction — wrote nothing, so an app whose model sites
+     * are mostly tool loops could show zero spend. `false` for a caller that
+     * records elsewhere.
+     */
+    readonly recordUsage?: boolean;
 }
 
 /**