@anuma/agent-runtime 6.33.1 → 6.34.0

package/dist/index.cjs

@@ -376,10 +376,6 @@ async function runAgentRequest(opts) {
     model: opts.agent.model.default,
     token: grant.bearer,
     tools,
-    // X-Anuma-Surface drives portal auth/grant keying (OAuth client_id + first-party
-    // grant surface) — keep it. X-Anuma-Feature is the provenance header the portal
-    // records into requests.feature (#1353); without it, agent-runtime LLM traffic
-    // lands feature=null and can't be told apart from chat/background in prod.
     headers: { "X-Anuma-Surface": "agent", "X-Anuma-Feature": "agent" },
     ...opts.portalBaseUrl ? { baseUrl: opts.portalBaseUrl } : void 0,
     ...opts.transport ? { transport: opts.transport } : void 0,

package/dist/index.d.mts

@@ -3,33 +3,18 @@ export { ConnectorTokenGetterOpts } from '@anuma/sdk/tools';
 import { LlmapiMessage } from '@anuma/sdk';
 import { ToolConfig, StreamingTransport, ApiType, AutoExecutedToolResult } from '@anuma/sdk/server';
 
-/**
- * Public types for `@anuma/agent-runtime`.
- *
- * Mirrors the contract in `.claude-docs/connecters/agent-runtime-spec.md`.
- * These types are the contract between the SDK / portal vault and any
- * server-side consumer (Haven, Sentinel, future SMS handler).
- */
-
-/**
- * Parsed result of an incoming bearer token. Returned by
- * {@link extractGrantContext}.
- */
+/** Parsed result of an incoming bearer token, returned by {@link extractGrantContext}. */
 interface GrantContext {
-    /** Wallet address — primary user identifier on the portal. */
+    /** Wallet address; the primary user identifier on the portal. */
     userAddress: string;
-    /** OAuth `client_id` that owns the bearer (e.g. `"haven_v1"`). */
+    /** OAuth `client_id` that owns the bearer, e.g. `"haven_v1"`. */
     clientId: string;
     /** Scopes the user granted to this client. */
     scopes: string[];
-    /** Bearer token verbatim — for relaying to the portal. */
+    /** Bearer token verbatim, for relaying to the portal. */
     bearer: string;
 }
-/**
- * Discriminated result of a mint call. Failures are returned, never
- * thrown — transport errors (5xx / network) raise from {@link PortalClient}
- * directly.
- */
+/** Result of a mint call; HTTP failures, including 5xx after retries, are returned and network errors throw; `expiresAt` is unix ms. */
 type MintResult = {
     ok: true;
     accessToken: string;
@@ -38,11 +23,9 @@ type MintResult = {
     ok: false;
     error: MintError;
 };
-/** Variants of `MintResult.error`. Re-exported from the SDK so consumers
- *  importing only `@anuma/agent-runtime` get the union without a second
- *  import. */
+/** Variants of `MintResult.error`, re-exported from `@anuma/sdk/tools`. */
 type MintError = ConnectorMintError;
-/** Returned by {@link PortalClient.listConnectors}. */
+/** Returned by {@link PortalClient.listConnectors}; `connectedAt` is unix ms. */
 interface ConnectorInfo {
     oauthApp: string;
     externalAccount?: string;
@@ -51,19 +34,13 @@ interface ConnectorInfo {
 }
 /** Argument shape for {@link PortalClient.createConnectTicket}. */
 interface ConnectTicketOpts {
-    /** Logical provider (e.g. `"gmail"`, `"github"`) — mapped to the portal
-     *  `oauth_app` internally and used to build the connect URL. */
+    /** Logical provider, e.g. `"gmail"` or `"github"`. */
     provider: string;
-    /**
-     * Scopes requested for the connect flow, passed VERBATIM upstream
-     * ("upstream-flavored"): Google needs full
-     * `https://www.googleapis.com/auth/...` URLs. An empty array falls back to
-     * the provider's default scope union on the portal side.
-     */
+    /** Scopes passed verbatim upstream (Google needs full `https://www.googleapis.com/auth/...` URLs); an empty array uses the provider's default scopes. */
     requestedScopes: string[];
     returnTo: string;
 }
-/** Result of a ticket-mint call. */
+/** Result of a ticket-mint call; `expiresAt` is unix ms. */
 interface ConnectTicket {
     ticketId: string;
     expiresAt: number;
@@ -71,28 +48,27 @@ interface ConnectTicket {
 }
 /** Typed wrapper over the portal HTTP API. */
 interface PortalClient {
-    /** Mint a fresh upstream access token for a logical provider. `access`
-     *  defaults to the provider's standard level (e.g. gmail `read`, github
-     *  `repo`). */
+    /** Mint an upstream access token for a logical provider; `access` defaults to the provider's standard level. */
     mintConnectorToken(provider: string, access?: string): Promise<MintResult>;
-    /** List the user's currently-connected connectors. */
+    /** List the user's connected connectors. */
     listConnectors(): Promise<ConnectorInfo[]>;
-    /** Mint a connect ticket so the user can be redirected to a connect flow. */
+    /** Mint a connect ticket for redirecting the user to a connect flow. */
     createConnectTicket(opts: ConnectTicketOpts): Promise<ConnectTicket>;
 }
+/** Options for {@link createPortalClient}. */
 interface PortalClientOpts {
-    /** Defaults to `process.env.ANUMA_PORTAL_URL` then the production portal. */
+    /** @defaultValue `process.env.ANUMA_PORTAL_URL`, then the production portal */
     baseUrl?: string;
-    /** Defaults to `globalThis.fetch`. */
+    /** @defaultValue `globalThis.fetch` */
     fetchImpl?: typeof fetch;
-    /** Per-request timeout. @default 5000 */
+    /** Per-request timeout. @defaultValue 5000 */
     timeoutMs?: number;
-    /** Max retry attempts on 5xx / network errors. @default 3 */
+    /** Max attempts on 5xx and network errors. @defaultValue 3 */
     maxRetries?: number;
-    /** Initial backoff before the second attempt. @default 100 */
+    /** Initial backoff before the second attempt. @defaultValue 100 */
     retryBaseMs?: number;
 }
-/** Structurally-typed incoming request. Any HTTP framework satisfies this. */
+/** Structurally typed incoming request; any HTTP framework satisfies it. */
 interface IncomingRequest {
     headers: {
         authorization?: string;
@@ -100,17 +76,7 @@ interface IncomingRequest {
         [key: string]: string | string[] | undefined;
     };
 }
-/**
- * Structured tool error lifted from a tool-result message after the loop
- * completes. Connector errors carry the canonical
- * `__anuma_connector_error_v1` payload; other tool failures may surface
- * here in the future.
- */
-/**
- * Open shape so future tool-execution errors can lift into the same union
- * without breaking consumers. Connector errors populate `provider`; other
- * errors carry a `message`.
- */
+/** Structured tool error; connector errors populate `provider`, others carry `message`. */
 interface ToolErrorInfo {
     code: string;
     provider?: string;
@@ -124,153 +90,68 @@ interface ToolError {
     error: ToolErrorInfo;
 }
 
-/**
- * Error subclasses thrown by `@anuma/agent-runtime`.
- *
- * - {@link AuthError} comes out of `extractGrantContext` when the bearer is
- *   missing, malformed, expired, or already revoked.
- */
 /** Discriminant for {@link AuthError}. */
 type AuthErrorSubtype = "missing_bearer" | "invalid_bearer" | "expired" | "revoked";
+/** Thrown by `extractGrantContext` when the bearer is missing, malformed, expired, or revoked. */
 declare class AuthError extends Error {
     readonly subtype: AuthErrorSubtype;
     constructor(subtype: AuthErrorSubtype, message?: string);
 }
 
-/**
- * Pull the bearer off an incoming request, validate it against the portal,
- * and return the parsed grant.
- *
- * In v1 the portal validates by exposing `GET /api/v1/me`, which returns
- * `{ user_address, client_id, scopes }`. A later portal version may switch
- * to issuing signed JWTs and let `extractGrantContext` do local decode —
- * the consumer signature stays the same.
- */
-
 type ExtractGrantContextOpts = Pick<PortalClientOpts, "baseUrl" | "fetchImpl" | "timeoutMs">;
+/** Validate the request's bearer against the portal and return the parsed grant. @throws {@link AuthError} when the bearer is missing, malformed, expired, or revoked. */
 declare function extractGrantContext(req: IncomingRequest, opts?: ExtractGrantContextOpts): Promise<GrantContext>;
 
-/**
- * Typed HTTP client over the portal API.
- *
- * Retries on 5xx / network errors with exponential backoff + jitter
- * (default 3 attempts, base 100ms). Never retries 4xx — those become
- * `MintResult.ok=false` (for mint) or thrown errors (for the bookkeeping
- * endpoints `listConnectors` / `createConnectTicket`).
- *
- * Surface is duck-typed against `PortalClient` so test stubs can satisfy
- * the same contract.
- */
-
+/** Create a {@link PortalClient} that retries 5xx and network errors with jittered exponential backoff and never retries 4xx. */
 declare function createPortalClient(bearer: string, opts?: PortalClientOpts): PortalClient;
 
-/**
- * Convenience wrapper that re-exports the SDK's
- * `createConnectorTokenGetter` with the same per-instance cache semantics.
- *
- * The wrapper exists so consumers importing only `@anuma/agent-runtime`
- * get the helper as part of a single import surface, without also
- * importing `@anuma/sdk/tools` directly. The behavior is identical.
- */
-
 declare function createConnectorTokenGetter(client: PortalClient, provider: string, opts?: ConnectorTokenGetterOpts): () => Promise<string | null>;
 
-/**
- * `runAgentRequest` — the single function a server-side agent host calls
- * per inbound request.
- *
- * Wires the four pieces together:
- *   extractGrantContext → createPortalClient → toolFactories → runToolLoop
- *
- * After the loop returns, walks the auto-executed tool results, lifts any
- * payload carrying the canonical `__anuma_connector_error_v1` marker into
- * `AgentResponse.toolErrors`. The marker shape is the load-bearing contract
- * — every connector tool factory uses `buildConnectorErrorResult` to emit
- * it, and the parser keys solely on that marker so it can't false-positive
- * on tools that legitimately return JSON.
- */
-
 /** Minimal slice of `AgentConfig` this runtime depends on. */
 interface AgentConfigLike {
-    /** Model selection — at least `default` must be present. */
     model: {
         default: string;
     };
-    /** System prompt threaded into the loop. */
     prompt: string;
 }
+/** Options for {@link runAgentRequest}. */
 interface AgentRequestOpts {
-    /** Inbound request — only `headers.authorization` is read. */
+    /** Inbound request; only `headers.authorization` is read. */
     request: IncomingRequest;
-    /** Agent configuration (haven, sentinel, …). */
     agent: AgentConfigLike;
-    /** Conversation history including the user turn. */
     messages: LlmapiMessage[];
-    /** Tool factories that receive the portal client and return `ToolConfig[]`. */
+    /** Factories that receive the portal client and return `ToolConfig[]`. */
     toolFactories?: Array<(portalClient: PortalClient) => ToolConfig[]>;
-    /** Override portal client opts (test injection). */
+    /** Overrides for the portal client, for test injection. */
     portalClientOpts?: PortalClientOpts;
-    /**
-     * Override the streaming transport runToolLoop uses to talk to the
-     * portal's chat completion API. Production code never sets this — it's
-     * the injection point e2e tests use to stub LLM behavior without a real
-     * portal in the loop. Forwarded verbatim to runToolLoop's
-     * `transport` option.
-     */
+    /** Streaming transport override forwarded to `runToolLoop`, for tests. */
     transport?: StreamingTransport;
-    /**
-     * Optional portal base URL forwarded to runToolLoop for chat completions.
-     * Defaults to runToolLoop's own default. Setting this without a stub
-     * `transport` will hit the real portal.
-     */
+    /** Portal base URL for chat completions; without a stub `transport` this hits the real portal. */
     portalBaseUrl?: string;
-    /**
-     * Optional override for the LLM API strategy ("responses" | "completions" | "auto").
-     * Production callers don't set this — the default ("auto") picks the right
-     * endpoint for the model. Tests use "completions" with the stub transport
-     * to feed OpenAI-style streaming chunks.
-     */
+    /** LLM API strategy. @defaultValue `"auto"` */
     apiType?: ApiType;
 }
-/** Minimal usage summary lifted off the LLM response. */
+/** Token usage lifted off the LLM response. */
 interface UsageSummary {
     inputTokens?: number;
     outputTokens?: number;
     totalTokens?: number;
 }
+/** Result of {@link runAgentRequest}. */
 interface AgentResponse {
-    /**
-     * Conversation messages after the loop completes: the input messages,
-     * followed by tool-result messages for each auto-executed tool, followed
-     * by the final assistant message. Synthesized — `runToolLoop` doesn't
-     * expose the full message history directly.
-     */
+    /** Input messages, then an assistant `tool_calls` message and tool-result messages when tools ran, then the final assistant message if present. */
     messages: LlmapiMessage[];
-    /** Structured tool errors lifted from the post-loop parser. */
+    /** Connector errors lifted from tool results. */
     toolErrors: ToolError[];
-    /** Token usage summary if the response carried one. */
     usage?: UsageSummary;
-    /** Grant context, surfaced for logging / multi-tenant context propagation. */
+    /** Grant context, for logging and tenant propagation. */
     grant: GrantContext;
 }
-/**
- * Walk the loop's tool results, lift entries that carry the
- * `__anuma_connector_error_v1` marker into structured `ToolError`s.
- *
- * Each `AutoExecutedToolResult.result` is what the executor returned.
- * Connector tool factories return the JSON string produced by
- * `buildConnectorErrorResult`, so we JSON.parse strings and inspect for
- * the marker. Non-string results (objects, arrays, errors) skip the
- * parser entirely — they can't be connector errors.
- */
+/** Lift tool results carrying the `__anuma_connector_error_v1` marker into structured `ToolError`s. */
 declare function extractConnectorToolErrors(toolResults: AutoExecutedToolResult[] | undefined): ToolError[];
-/**
- * Default `requestAccess` passed to connector tool factories from inside
- * `runAgentRequest`. Server agents cannot drive interactive OAuth — they
- * have no surface to bounce the user through. The factory falls back to
- * emitting the canonical connector error JSON when this throws.
- */
+/** Default `requestAccess` for server agents: always throws, since they cannot drive interactive OAuth. */
 declare function denyInteractive(): Promise<string | null>;
+/** Handle one inbound agent request: validate the bearer, build the portal client and tools, run `runToolLoop`, and lift connector errors. @throws Error when the tool loop fails at the transport level. */
 declare function runAgentRequest(opts: AgentRequestOpts): Promise<AgentResponse>;
 
 export { type AgentConfigLike, type AgentRequestOpts, type AgentResponse, AuthError, type AuthErrorSubtype, type ConnectTicket, type ConnectTicketOpts, type ConnectorInfo, type ExtractGrantContextOpts, type GrantContext, type IncomingRequest, type MintError, type MintResult, type PortalClient, type PortalClientOpts, type ToolError, type ToolErrorInfo, type UsageSummary, createConnectorTokenGetter, createPortalClient, denyInteractive, extractConnectorToolErrors, extractGrantContext, runAgentRequest };

package/dist/index.d.ts

@@ -3,33 +3,18 @@ export { ConnectorTokenGetterOpts } from '@anuma/sdk/tools';
 import { LlmapiMessage } from '@anuma/sdk';
 import { ToolConfig, StreamingTransport, ApiType, AutoExecutedToolResult } from '@anuma/sdk/server';
 
-/**
- * Public types for `@anuma/agent-runtime`.
- *
- * Mirrors the contract in `.claude-docs/connecters/agent-runtime-spec.md`.
- * These types are the contract between the SDK / portal vault and any
- * server-side consumer (Haven, Sentinel, future SMS handler).
- */
-
-/**
- * Parsed result of an incoming bearer token. Returned by
- * {@link extractGrantContext}.
- */
+/** Parsed result of an incoming bearer token, returned by {@link extractGrantContext}. */
 interface GrantContext {
-    /** Wallet address — primary user identifier on the portal. */
+    /** Wallet address; the primary user identifier on the portal. */
     userAddress: string;
-    /** OAuth `client_id` that owns the bearer (e.g. `"haven_v1"`). */
+    /** OAuth `client_id` that owns the bearer, e.g. `"haven_v1"`. */
     clientId: string;
     /** Scopes the user granted to this client. */
     scopes: string[];
-    /** Bearer token verbatim — for relaying to the portal. */
+    /** Bearer token verbatim, for relaying to the portal. */
     bearer: string;
 }
-/**
- * Discriminated result of a mint call. Failures are returned, never
- * thrown — transport errors (5xx / network) raise from {@link PortalClient}
- * directly.
- */
+/** Result of a mint call; HTTP failures, including 5xx after retries, are returned and network errors throw; `expiresAt` is unix ms. */
 type MintResult = {
     ok: true;
     accessToken: string;
@@ -38,11 +23,9 @@ type MintResult = {
     ok: false;
     error: MintError;
 };
-/** Variants of `MintResult.error`. Re-exported from the SDK so consumers
- *  importing only `@anuma/agent-runtime` get the union without a second
- *  import. */
+/** Variants of `MintResult.error`, re-exported from `@anuma/sdk/tools`. */
 type MintError = ConnectorMintError;
-/** Returned by {@link PortalClient.listConnectors}. */
+/** Returned by {@link PortalClient.listConnectors}; `connectedAt` is unix ms. */
 interface ConnectorInfo {
     oauthApp: string;
     externalAccount?: string;
@@ -51,19 +34,13 @@ interface ConnectorInfo {
 }
 /** Argument shape for {@link PortalClient.createConnectTicket}. */
 interface ConnectTicketOpts {
-    /** Logical provider (e.g. `"gmail"`, `"github"`) — mapped to the portal
-     *  `oauth_app` internally and used to build the connect URL. */
+    /** Logical provider, e.g. `"gmail"` or `"github"`. */
     provider: string;
-    /**
-     * Scopes requested for the connect flow, passed VERBATIM upstream
-     * ("upstream-flavored"): Google needs full
-     * `https://www.googleapis.com/auth/...` URLs. An empty array falls back to
-     * the provider's default scope union on the portal side.
-     */
+    /** Scopes passed verbatim upstream (Google needs full `https://www.googleapis.com/auth/...` URLs); an empty array uses the provider's default scopes. */
     requestedScopes: string[];
     returnTo: string;
 }
-/** Result of a ticket-mint call. */
+/** Result of a ticket-mint call; `expiresAt` is unix ms. */
 interface ConnectTicket {
     ticketId: string;
     expiresAt: number;
@@ -71,28 +48,27 @@ interface ConnectTicket {
 }
 /** Typed wrapper over the portal HTTP API. */
 interface PortalClient {
-    /** Mint a fresh upstream access token for a logical provider. `access`
-     *  defaults to the provider's standard level (e.g. gmail `read`, github
-     *  `repo`). */
+    /** Mint an upstream access token for a logical provider; `access` defaults to the provider's standard level. */
     mintConnectorToken(provider: string, access?: string): Promise<MintResult>;
-    /** List the user's currently-connected connectors. */
+    /** List the user's connected connectors. */
     listConnectors(): Promise<ConnectorInfo[]>;
-    /** Mint a connect ticket so the user can be redirected to a connect flow. */
+    /** Mint a connect ticket for redirecting the user to a connect flow. */
     createConnectTicket(opts: ConnectTicketOpts): Promise<ConnectTicket>;
 }
+/** Options for {@link createPortalClient}. */
 interface PortalClientOpts {
-    /** Defaults to `process.env.ANUMA_PORTAL_URL` then the production portal. */
+    /** @defaultValue `process.env.ANUMA_PORTAL_URL`, then the production portal */
     baseUrl?: string;
-    /** Defaults to `globalThis.fetch`. */
+    /** @defaultValue `globalThis.fetch` */
     fetchImpl?: typeof fetch;
-    /** Per-request timeout. @default 5000 */
+    /** Per-request timeout. @defaultValue 5000 */
     timeoutMs?: number;
-    /** Max retry attempts on 5xx / network errors. @default 3 */
+    /** Max attempts on 5xx and network errors. @defaultValue 3 */
     maxRetries?: number;
-    /** Initial backoff before the second attempt. @default 100 */
+    /** Initial backoff before the second attempt. @defaultValue 100 */
     retryBaseMs?: number;
 }
-/** Structurally-typed incoming request. Any HTTP framework satisfies this. */
+/** Structurally typed incoming request; any HTTP framework satisfies it. */
 interface IncomingRequest {
     headers: {
         authorization?: string;
@@ -100,17 +76,7 @@ interface IncomingRequest {
         [key: string]: string | string[] | undefined;
     };
 }
-/**
- * Structured tool error lifted from a tool-result message after the loop
- * completes. Connector errors carry the canonical
- * `__anuma_connector_error_v1` payload; other tool failures may surface
- * here in the future.
- */
-/**
- * Open shape so future tool-execution errors can lift into the same union
- * without breaking consumers. Connector errors populate `provider`; other
- * errors carry a `message`.
- */
+/** Structured tool error; connector errors populate `provider`, others carry `message`. */
 interface ToolErrorInfo {
     code: string;
     provider?: string;
@@ -124,153 +90,68 @@ interface ToolError {
     error: ToolErrorInfo;
 }
 
-/**
- * Error subclasses thrown by `@anuma/agent-runtime`.
- *
- * - {@link AuthError} comes out of `extractGrantContext` when the bearer is
- *   missing, malformed, expired, or already revoked.
- */
 /** Discriminant for {@link AuthError}. */
 type AuthErrorSubtype = "missing_bearer" | "invalid_bearer" | "expired" | "revoked";
+/** Thrown by `extractGrantContext` when the bearer is missing, malformed, expired, or revoked. */
 declare class AuthError extends Error {
     readonly subtype: AuthErrorSubtype;
     constructor(subtype: AuthErrorSubtype, message?: string);
 }
 
-/**
- * Pull the bearer off an incoming request, validate it against the portal,
- * and return the parsed grant.
- *
- * In v1 the portal validates by exposing `GET /api/v1/me`, which returns
- * `{ user_address, client_id, scopes }`. A later portal version may switch
- * to issuing signed JWTs and let `extractGrantContext` do local decode —
- * the consumer signature stays the same.
- */
-
 type ExtractGrantContextOpts = Pick<PortalClientOpts, "baseUrl" | "fetchImpl" | "timeoutMs">;
+/** Validate the request's bearer against the portal and return the parsed grant. @throws {@link AuthError} when the bearer is missing, malformed, expired, or revoked. */
 declare function extractGrantContext(req: IncomingRequest, opts?: ExtractGrantContextOpts): Promise<GrantContext>;
 
-/**
- * Typed HTTP client over the portal API.
- *
- * Retries on 5xx / network errors with exponential backoff + jitter
- * (default 3 attempts, base 100ms). Never retries 4xx — those become
- * `MintResult.ok=false` (for mint) or thrown errors (for the bookkeeping
- * endpoints `listConnectors` / `createConnectTicket`).
- *
- * Surface is duck-typed against `PortalClient` so test stubs can satisfy
- * the same contract.
- */
-
+/** Create a {@link PortalClient} that retries 5xx and network errors with jittered exponential backoff and never retries 4xx. */
 declare function createPortalClient(bearer: string, opts?: PortalClientOpts): PortalClient;
 
-/**
- * Convenience wrapper that re-exports the SDK's
- * `createConnectorTokenGetter` with the same per-instance cache semantics.
- *
- * The wrapper exists so consumers importing only `@anuma/agent-runtime`
- * get the helper as part of a single import surface, without also
- * importing `@anuma/sdk/tools` directly. The behavior is identical.
- */
-
 declare function createConnectorTokenGetter(client: PortalClient, provider: string, opts?: ConnectorTokenGetterOpts): () => Promise<string | null>;
 
-/**
- * `runAgentRequest` — the single function a server-side agent host calls
- * per inbound request.
- *
- * Wires the four pieces together:
- *   extractGrantContext → createPortalClient → toolFactories → runToolLoop
- *
- * After the loop returns, walks the auto-executed tool results, lifts any
- * payload carrying the canonical `__anuma_connector_error_v1` marker into
- * `AgentResponse.toolErrors`. The marker shape is the load-bearing contract
- * — every connector tool factory uses `buildConnectorErrorResult` to emit
- * it, and the parser keys solely on that marker so it can't false-positive
- * on tools that legitimately return JSON.
- */
-
 /** Minimal slice of `AgentConfig` this runtime depends on. */
 interface AgentConfigLike {
-    /** Model selection — at least `default` must be present. */
     model: {
         default: string;
     };
-    /** System prompt threaded into the loop. */
     prompt: string;
 }
+/** Options for {@link runAgentRequest}. */
 interface AgentRequestOpts {
-    /** Inbound request — only `headers.authorization` is read. */
+    /** Inbound request; only `headers.authorization` is read. */
     request: IncomingRequest;
-    /** Agent configuration (haven, sentinel, …). */
     agent: AgentConfigLike;
-    /** Conversation history including the user turn. */
     messages: LlmapiMessage[];
-    /** Tool factories that receive the portal client and return `ToolConfig[]`. */
+    /** Factories that receive the portal client and return `ToolConfig[]`. */
     toolFactories?: Array<(portalClient: PortalClient) => ToolConfig[]>;
-    /** Override portal client opts (test injection). */
+    /** Overrides for the portal client, for test injection. */
     portalClientOpts?: PortalClientOpts;
-    /**
-     * Override the streaming transport runToolLoop uses to talk to the
-     * portal's chat completion API. Production code never sets this — it's
-     * the injection point e2e tests use to stub LLM behavior without a real
-     * portal in the loop. Forwarded verbatim to runToolLoop's
-     * `transport` option.
-     */
+    /** Streaming transport override forwarded to `runToolLoop`, for tests. */
     transport?: StreamingTransport;
-    /**
-     * Optional portal base URL forwarded to runToolLoop for chat completions.
-     * Defaults to runToolLoop's own default. Setting this without a stub
-     * `transport` will hit the real portal.
-     */
+    /** Portal base URL for chat completions; without a stub `transport` this hits the real portal. */
     portalBaseUrl?: string;
-    /**
-     * Optional override for the LLM API strategy ("responses" | "completions" | "auto").
-     * Production callers don't set this — the default ("auto") picks the right
-     * endpoint for the model. Tests use "completions" with the stub transport
-     * to feed OpenAI-style streaming chunks.
-     */
+    /** LLM API strategy. @defaultValue `"auto"` */
     apiType?: ApiType;
 }
-/** Minimal usage summary lifted off the LLM response. */
+/** Token usage lifted off the LLM response. */
 interface UsageSummary {
     inputTokens?: number;
     outputTokens?: number;
     totalTokens?: number;
 }
+/** Result of {@link runAgentRequest}. */
 interface AgentResponse {
-    /**
-     * Conversation messages after the loop completes: the input messages,
-     * followed by tool-result messages for each auto-executed tool, followed
-     * by the final assistant message. Synthesized — `runToolLoop` doesn't
-     * expose the full message history directly.
-     */
+    /** Input messages, then an assistant `tool_calls` message and tool-result messages when tools ran, then the final assistant message if present. */
     messages: LlmapiMessage[];
-    /** Structured tool errors lifted from the post-loop parser. */
+    /** Connector errors lifted from tool results. */
     toolErrors: ToolError[];
-    /** Token usage summary if the response carried one. */
     usage?: UsageSummary;
-    /** Grant context, surfaced for logging / multi-tenant context propagation. */
+    /** Grant context, for logging and tenant propagation. */
     grant: GrantContext;
 }
-/**
- * Walk the loop's tool results, lift entries that carry the
- * `__anuma_connector_error_v1` marker into structured `ToolError`s.
- *
- * Each `AutoExecutedToolResult.result` is what the executor returned.
- * Connector tool factories return the JSON string produced by
- * `buildConnectorErrorResult`, so we JSON.parse strings and inspect for
- * the marker. Non-string results (objects, arrays, errors) skip the
- * parser entirely — they can't be connector errors.
- */
+/** Lift tool results carrying the `__anuma_connector_error_v1` marker into structured `ToolError`s. */
 declare function extractConnectorToolErrors(toolResults: AutoExecutedToolResult[] | undefined): ToolError[];
-/**
- * Default `requestAccess` passed to connector tool factories from inside
- * `runAgentRequest`. Server agents cannot drive interactive OAuth — they
- * have no surface to bounce the user through. The factory falls back to
- * emitting the canonical connector error JSON when this throws.
- */
+/** Default `requestAccess` for server agents: always throws, since they cannot drive interactive OAuth. */
 declare function denyInteractive(): Promise<string | null>;
+/** Handle one inbound agent request: validate the bearer, build the portal client and tools, run `runToolLoop`, and lift connector errors. @throws Error when the tool loop fails at the transport level. */
 declare function runAgentRequest(opts: AgentRequestOpts): Promise<AgentResponse>;
 
 export { type AgentConfigLike, type AgentRequestOpts, type AgentResponse, AuthError, type AuthErrorSubtype, type ConnectTicket, type ConnectTicketOpts, type ConnectorInfo, type ExtractGrantContextOpts, type GrantContext, type IncomingRequest, type MintError, type MintResult, type PortalClient, type PortalClientOpts, type ToolError, type ToolErrorInfo, type UsageSummary, createConnectorTokenGetter, createPortalClient, denyInteractive, extractConnectorToolErrors, extractGrantContext, runAgentRequest };

package/dist/index.mjs

@@ -348,10 +348,6 @@ async function runAgentRequest(opts) {
     model: opts.agent.model.default,
     token: grant.bearer,
     tools,
-    // X-Anuma-Surface drives portal auth/grant keying (OAuth client_id + first-party
-    // grant surface) — keep it. X-Anuma-Feature is the provenance header the portal
-    // records into requests.feature (#1353); without it, agent-runtime LLM traffic
-    // lands feature=null and can't be told apart from chat/background in prod.
     headers: { "X-Anuma-Surface": "agent", "X-Anuma-Feature": "agent" },
     ...opts.portalBaseUrl ? { baseUrl: opts.portalBaseUrl } : void 0,
     ...opts.transport ? { transport: opts.transport } : void 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anuma/agent-runtime",
-  "version": "6.33.1",
+  "version": "6.34.0",
   "description": "Server-side runtime contract for Anuma agents — extractGrantContext, PortalClient, runAgentRequest.",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -30,13 +30,13 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@anuma/sdk": "6.33.1"
+    "@anuma/sdk": "6.34.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
-    "@anuma/sdk": "6.33.1"
+    "@anuma/sdk": "6.34.0"
   },
   "scripts": {
     "build": "tsup",