@anuma/agent-runtime 6.33.0 → 6.33.2

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,12 @@ 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}.
- */
 interface GrantContext {
-    /** Wallet address — primary user identifier on the portal. */
     userAddress: string;
-    /** 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: string;
 }
-/**
- * Discriminated result of a mint call. Failures are returned, never
- * thrown — transport errors (5xx / network) raise from {@link PortalClient}
- * directly.
- */
 type MintResult = {
     ok: true;
     accessToken: string;
@@ -38,61 +17,35 @@ 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. */
 type MintError = ConnectorMintError;
-/** Returned by {@link PortalClient.listConnectors}. */
 interface ConnectorInfo {
     oauthApp: string;
     externalAccount?: string;
     grantedScopes: string[];
     connectedAt: number;
 }
-/** 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. */
     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.
-     */
     requestedScopes: string[];
     returnTo: string;
 }
-/** Result of a ticket-mint call. */
 interface ConnectTicket {
     ticketId: string;
     expiresAt: number;
     connectUrl: string;
 }
-/** 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`). */
     mintConnectorToken(provider: string, access?: string): Promise<MintResult>;
-    /** List the user's currently-connected connectors. */
     listConnectors(): Promise<ConnectorInfo[]>;
-    /** Mint a connect ticket so the user can be redirected to a connect flow. */
     createConnectTicket(opts: ConnectTicketOpts): Promise<ConnectTicket>;
 }
 interface PortalClientOpts {
-    /** Defaults to `process.env.ANUMA_PORTAL_URL` then the production portal. */
     baseUrl?: string;
-    /** Defaults to `globalThis.fetch`. */
     fetchImpl?: typeof fetch;
-    /** Per-request timeout. @default 5000 */
     timeoutMs?: number;
-    /** Max retry attempts on 5xx / network errors. @default 3 */
     maxRetries?: number;
-    /** Initial backoff before the second attempt. @default 100 */
     retryBaseMs?: number;
 }
-/** Structurally-typed incoming request. Any HTTP framework satisfies this. */
 interface IncomingRequest {
     headers: {
         authorization?: string;
@@ -100,17 +53,6 @@ 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`.
- */
 interface ToolErrorInfo {
     code: string;
     provider?: string;
@@ -124,152 +66,47 @@ 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";
 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">;
 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.
- */
-
 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;
 }
 interface AgentRequestOpts {
-    /** 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[]`. */
     toolFactories?: Array<(portalClient: PortalClient) => ToolConfig[]>;
-    /** Override portal client opts (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.
-     */
     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.
-     */
     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.
-     */
     apiType?: ApiType;
 }
-/** Minimal usage summary lifted off the LLM response. */
 interface UsageSummary {
     inputTokens?: number;
     outputTokens?: number;
     totalTokens?: number;
 }
 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.
-     */
     messages: LlmapiMessage[];
-    /** Structured tool errors lifted from the post-loop parser. */
     toolErrors: ToolError[];
-    /** Token usage summary if the response carried one. */
     usage?: UsageSummary;
-    /** Grant context, surfaced for logging / multi-tenant context 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.
- */
 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.
- */
 declare function denyInteractive(): Promise<string | null>;
 declare function runAgentRequest(opts: AgentRequestOpts): Promise<AgentResponse>;
 

package/dist/index.d.ts

@@ -3,33 +3,12 @@ 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}.
- */
 interface GrantContext {
-    /** Wallet address — primary user identifier on the portal. */
     userAddress: string;
-    /** 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: string;
 }
-/**
- * Discriminated result of a mint call. Failures are returned, never
- * thrown — transport errors (5xx / network) raise from {@link PortalClient}
- * directly.
- */
 type MintResult = {
     ok: true;
     accessToken: string;
@@ -38,61 +17,35 @@ 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. */
 type MintError = ConnectorMintError;
-/** Returned by {@link PortalClient.listConnectors}. */
 interface ConnectorInfo {
     oauthApp: string;
     externalAccount?: string;
     grantedScopes: string[];
     connectedAt: number;
 }
-/** 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. */
     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.
-     */
     requestedScopes: string[];
     returnTo: string;
 }
-/** Result of a ticket-mint call. */
 interface ConnectTicket {
     ticketId: string;
     expiresAt: number;
     connectUrl: string;
 }
-/** 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`). */
     mintConnectorToken(provider: string, access?: string): Promise<MintResult>;
-    /** List the user's currently-connected connectors. */
     listConnectors(): Promise<ConnectorInfo[]>;
-    /** Mint a connect ticket so the user can be redirected to a connect flow. */
     createConnectTicket(opts: ConnectTicketOpts): Promise<ConnectTicket>;
 }
 interface PortalClientOpts {
-    /** Defaults to `process.env.ANUMA_PORTAL_URL` then the production portal. */
     baseUrl?: string;
-    /** Defaults to `globalThis.fetch`. */
     fetchImpl?: typeof fetch;
-    /** Per-request timeout. @default 5000 */
     timeoutMs?: number;
-    /** Max retry attempts on 5xx / network errors. @default 3 */
     maxRetries?: number;
-    /** Initial backoff before the second attempt. @default 100 */
     retryBaseMs?: number;
 }
-/** Structurally-typed incoming request. Any HTTP framework satisfies this. */
 interface IncomingRequest {
     headers: {
         authorization?: string;
@@ -100,17 +53,6 @@ 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`.
- */
 interface ToolErrorInfo {
     code: string;
     provider?: string;
@@ -124,152 +66,47 @@ 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";
 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">;
 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.
- */
-
 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;
 }
 interface AgentRequestOpts {
-    /** 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[]`. */
     toolFactories?: Array<(portalClient: PortalClient) => ToolConfig[]>;
-    /** Override portal client opts (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.
-     */
     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.
-     */
     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.
-     */
     apiType?: ApiType;
 }
-/** Minimal usage summary lifted off the LLM response. */
 interface UsageSummary {
     inputTokens?: number;
     outputTokens?: number;
     totalTokens?: number;
 }
 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.
-     */
     messages: LlmapiMessage[];
-    /** Structured tool errors lifted from the post-loop parser. */
     toolErrors: ToolError[];
-    /** Token usage summary if the response carried one. */
     usage?: UsageSummary;
-    /** Grant context, surfaced for logging / multi-tenant context 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.
- */
 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.
- */
 declare function denyInteractive(): Promise<string | null>;
 declare function runAgentRequest(opts: AgentRequestOpts): Promise<AgentResponse>;
 

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.0",
+  "version": "6.33.2",
   "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.0"
+    "@anuma/sdk": "6.33.2"
   },
   "devDependencies": {
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
-    "@anuma/sdk": "6.33.0"
+    "@anuma/sdk": "6.33.2"
   },
   "scripts": {
     "build": "tsup",