@anuma/agent-runtime 1.0.0-next.20260602215959

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ZetaChain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,381 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthError: () => AuthError,
+  createConnectorTokenGetter: () => createConnectorTokenGetter,
+  createPortalClient: () => createPortalClient,
+  denyInteractive: () => denyInteractive,
+  extractConnectorToolErrors: () => extractConnectorToolErrors,
+  extractGrantContext: () => extractGrantContext,
+  runAgentRequest: () => runAgentRequest
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var AuthError = class _AuthError extends Error {
+  constructor(subtype, message) {
+    super(message ?? subtype);
+    this.name = "AuthError";
+    this.subtype = subtype;
+    Object.setPrototypeOf(this, _AuthError.prototype);
+  }
+};
+
+// src/extractGrantContext.ts
+var DEFAULT_PORTAL_URL = "https://portal.anuma.ai";
+var DEFAULT_TIMEOUT_MS = 5e3;
+function readBearer(req) {
+  const headerValue = req.headers.authorization ?? req.headers.Authorization;
+  if (!headerValue) {
+    throw new AuthError("missing_bearer");
+  }
+  const value = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+  if (!value) throw new AuthError("missing_bearer");
+  const [scheme, token] = value.split(" ");
+  if (!scheme || scheme.toLowerCase() !== "bearer" || !token) {
+    throw new AuthError("invalid_bearer", "Authorization header must use the Bearer scheme");
+  }
+  return token;
+}
+async function extractGrantContext(req, opts = {}) {
+  const bearer = readBearer(req);
+  const baseUrl = opts.baseUrl ?? process.env.ANUMA_PORTAL_URL ?? DEFAULT_PORTAL_URL;
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetchImpl(`${baseUrl}/api/v1/me`, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${bearer}`
+      },
+      signal: controller.signal
+    });
+  } catch (err) {
+    if (err.name === "AbortError") {
+      throw new Error(`portal /api/v1/me timed out after ${timeoutMs}ms`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+  if (response.status === 401) {
+    throw new AuthError("expired", "portal /api/v1/me returned 401");
+  }
+  if (response.status === 403) {
+    throw new AuthError("revoked", "portal /api/v1/me returned 403");
+  }
+  if (!response.ok) {
+    throw new Error(`portal /api/v1/me returned ${response.status}`);
+  }
+  const me = await response.json();
+  if (!me.user_address || !me.client_id) {
+    throw new AuthError("invalid_bearer", "portal /api/v1/me missing user_address or client_id");
+  }
+  return {
+    userAddress: me.user_address,
+    clientId: me.client_id,
+    scopes: me.scopes ?? [],
+    bearer
+  };
+}
+
+// src/createPortalClient.ts
+var DEFAULT_PORTAL_URL2 = "https://portal.anuma.ai";
+var DEFAULT_TIMEOUT_MS2 = 5e3;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RETRY_BASE_MS = 100;
+function jitter(baseMs, attempt) {
+  const exp = baseMs * Math.pow(2, attempt);
+  return Math.floor(Math.random() * exp);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseMintError(status, body) {
+  const code = body.code ?? body.error;
+  if (status === 412 || status === 403) {
+    if (code === "connector_not_connected") {
+      return {
+        code: "connector_not_connected",
+        provider: body.provider ?? "unknown",
+        connectUrl: body.connect_url ?? ""
+      };
+    }
+    if (code === "scope_not_covered") {
+      return {
+        code: "scope_not_covered",
+        provider: body.provider ?? "unknown",
+        missingScopes: body.missing_scopes ?? [],
+        connectUrl: body.connect_url ?? ""
+      };
+    }
+    if (code === "insufficient_scope") {
+      return {
+        code: "insufficient_scope",
+        required: body.required ?? ""
+      };
+    }
+  }
+  return {
+    code: "unknown",
+    message: body.message ?? `mint failed with status ${status}`
+  };
+}
+function createPortalClient(bearer, opts = {}) {
+  const baseUrl = opts.baseUrl ?? process.env.ANUMA_PORTAL_URL ?? DEFAULT_PORTAL_URL2;
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+  const maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const retryBaseMs = opts.retryBaseMs ?? DEFAULT_RETRY_BASE_MS;
+  async function requestWithRetry(path, init) {
+    let lastErr;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetchImpl(`${baseUrl}${path}`, {
+          ...init,
+          signal: controller.signal,
+          headers: {
+            Authorization: `Bearer ${bearer}`,
+            ...init.headers
+          }
+        });
+        clearTimeout(timer);
+        if (response.status >= 500) {
+          lastErr = new Error(`portal ${path} returned ${response.status}`);
+          if (attempt < maxRetries - 1) {
+            await sleep(jitter(retryBaseMs, attempt));
+            continue;
+          }
+          return response;
+        }
+        return response;
+      } catch (err) {
+        clearTimeout(timer);
+        lastErr = err;
+        if (attempt < maxRetries - 1) {
+          await sleep(jitter(retryBaseMs, attempt));
+          continue;
+        }
+        throw lastErr;
+      }
+    }
+    throw lastErr ?? new Error(`portal ${path} failed`);
+  }
+  return {
+    async mintConnectorToken(provider) {
+      const response = await requestWithRetry(`/api/v1/connector-tokens/${provider}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" }
+      });
+      if (response.ok) {
+        const body2 = await response.json();
+        return {
+          ok: true,
+          accessToken: body2.access_token,
+          expiresAt: Date.now() + body2.expires_in * 1e3
+        };
+      }
+      if (response.status >= 500) {
+        return {
+          ok: false,
+          error: { code: "upstream_unavailable" }
+        };
+      }
+      let body = {};
+      try {
+        body = await response.json();
+      } catch {
+        body = {};
+      }
+      return { ok: false, error: parseMintError(response.status, body) };
+    },
+    async listConnectors() {
+      const response = await requestWithRetry("/api/v1/connectors", { method: "GET" });
+      if (!response.ok) {
+        throw new Error(`portal /api/v1/connectors returned ${response.status}`);
+      }
+      const body = await response.json();
+      return body.connectors.map((c) => ({
+        oauthApp: c.oauth_app,
+        externalAccount: c.external_account,
+        grantedScopes: c.granted_scopes ?? [],
+        connectedAt: c.connected_at ?? 0
+      }));
+    },
+    async createConnectTicket(opts2) {
+      const response = await requestWithRetry("/api/v1/connect-tickets", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          oauth_app: opts2.oauthApp,
+          requested_scopes: opts2.requestedScopes,
+          return_to: opts2.returnTo
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`portal /api/v1/connect-tickets returned ${response.status}`);
+      }
+      const body = await response.json();
+      return {
+        ticketId: body.ticket_id,
+        expiresAt: body.expires_at,
+        connectUrl: body.connect_url
+      };
+    }
+  };
+}
+
+// src/createConnectorTokenGetter.ts
+var import_tools = require("@anuma/sdk/tools");
+function createConnectorTokenGetter(client, provider, opts) {
+  return (0, import_tools.createConnectorTokenGetter)(client, provider, opts);
+}
+
+// src/runAgentRequest.ts
+var import_server = require("@anuma/sdk/server");
+var import_tools2 = require("@anuma/sdk/tools");
+function isConnectorErrorPayload(value) {
+  if (!value || typeof value !== "object") return false;
+  return value[import_tools2.CONNECTOR_ERROR_MARKER] === true;
+}
+function extractConnectorToolErrors(toolResults) {
+  if (!toolResults) return [];
+  const errors = [];
+  for (let idx = 0; idx < toolResults.length; idx++) {
+    const entry = toolResults[idx];
+    if (typeof entry.result !== "string") continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(entry.result);
+    } catch {
+      continue;
+    }
+    if (!isConnectorErrorPayload(parsed)) continue;
+    errors.push({
+      toolName: entry.name,
+      callId: `call_${idx}`,
+      error: {
+        code: parsed.code,
+        provider: parsed.provider,
+        connectUrl: parsed.connect_url,
+        missingScopes: parsed.missing_scopes,
+        required: parsed.required
+      }
+    });
+  }
+  return errors;
+}
+function extractUsage(data) {
+  if (!data || typeof data !== "object") return void 0;
+  const usage = data.usage;
+  if (!usage) return void 0;
+  const input = typeof usage.prompt_tokens === "number" ? usage.prompt_tokens : typeof usage.input_tokens === "number" ? usage.input_tokens : void 0;
+  const output = typeof usage.completion_tokens === "number" ? usage.completion_tokens : typeof usage.output_tokens === "number" ? usage.output_tokens : void 0;
+  const total = typeof usage.total_tokens === "number" ? usage.total_tokens : void 0;
+  if (input === void 0 && output === void 0 && total === void 0) return void 0;
+  return { inputTokens: input, outputTokens: output, totalTokens: total };
+}
+function finalAssistantMessage(data) {
+  if (!data || typeof data !== "object") return void 0;
+  const chatLike = data;
+  const chatMsg = chatLike.choices?.[0]?.message;
+  if (chatMsg) return chatMsg;
+  const resp = data;
+  const output = resp.output;
+  if (Array.isArray(output)) {
+    for (const item of output) {
+      const message = item.message;
+      if (message) return message;
+    }
+  }
+  return void 0;
+}
+function buildResponseMessages(inputMessages, toolResults, finalMessage) {
+  const out = [...inputMessages];
+  if (toolResults && toolResults.length > 0) {
+    out.push({
+      role: "assistant",
+      tool_calls: toolResults.map((tr, idx) => ({
+        id: `call_${idx}`,
+        type: "function",
+        function: { name: tr.name, arguments: "{}" }
+      }))
+    });
+    for (let idx = 0; idx < toolResults.length; idx++) {
+      const tr = toolResults[idx];
+      const content = typeof tr.result === "string" ? tr.result : JSON.stringify(tr.result) ?? "";
+      out.push({
+        role: "tool",
+        tool_call_id: `call_${idx}`,
+        content: [{ type: "text", text: content }]
+      });
+    }
+  }
+  if (finalMessage) out.push(finalMessage);
+  return out;
+}
+async function denyInteractive() {
+  throw new Error("server agent cannot initiate OAuth; user must connect via portal");
+}
+async function runAgentRequest(opts) {
+  const grant = await extractGrantContext(opts.request, opts.portalClientOpts);
+  const portal = createPortalClient(grant.bearer, opts.portalClientOpts);
+  const tools = (opts.toolFactories ?? []).flatMap((factory) => factory(portal));
+  const loopMessages = [
+    { role: "system", content: [{ type: "text", text: opts.agent.prompt }] },
+    ...opts.messages
+  ];
+  const loopResult = await (0, import_server.runToolLoop)({
+    messages: loopMessages,
+    model: opts.agent.model.default,
+    token: grant.bearer,
+    tools,
+    headers: { "X-Anuma-Surface": "agent" },
+    ...opts.portalBaseUrl ? { baseUrl: opts.portalBaseUrl } : void 0,
+    ...opts.transport ? { transport: opts.transport } : void 0,
+    ...opts.apiType ? { apiType: opts.apiType } : void 0
+  });
+  if (loopResult.error !== null) {
+    throw new Error(loopResult.error);
+  }
+  const finalMessage = finalAssistantMessage(loopResult.data);
+  const autoResults = loopResult.autoExecutedToolResults;
+  const messages = buildResponseMessages(opts.messages, autoResults, finalMessage);
+  const toolErrors = extractConnectorToolErrors(autoResults);
+  const usage = extractUsage(loopResult.data);
+  return { messages, toolErrors, usage, grant };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthError,
+  createConnectorTokenGetter,
+  createPortalClient,
+  denyInteractive,
+  extractConnectorToolErrors,
+  extractGrantContext,
+  runAgentRequest
+});

package/dist/index.d.mts

@@ -0,0 +1,267 @@
+import { ConnectorMintError, ConnectorTokenGetterOpts } from '@anuma/sdk/tools';
+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;
+    expiresAt: number;
+} | {
+    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 {
+    oauthApp: string;
+    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. */
+    mintConnectorToken(provider: 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;
+        Authorization?: string;
+        [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` +
+ * `connectUrl`; other errors carry a `message`.
+ */
+interface ToolErrorInfo {
+    code: string;
+    provider?: string;
+    connectUrl?: string;
+    missingScopes?: string[];
+    required?: string;
+    message?: string;
+}
+interface ToolError {
+    toolName: string;
+    callId: string;
+    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>;
+
+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

@@ -0,0 +1,267 @@
+import { ConnectorMintError, ConnectorTokenGetterOpts } from '@anuma/sdk/tools';
+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;
+    expiresAt: number;
+} | {
+    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 {
+    oauthApp: string;
+    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. */
+    mintConnectorToken(provider: 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;
+        Authorization?: string;
+        [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` +
+ * `connectUrl`; other errors carry a `message`.
+ */
+interface ToolErrorInfo {
+    code: string;
+    provider?: string;
+    connectUrl?: string;
+    missingScopes?: string[];
+    required?: string;
+    message?: string;
+}
+interface ToolError {
+    toolName: string;
+    callId: string;
+    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>;
+
+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

@@ -0,0 +1,352 @@
+// src/errors.ts
+var AuthError = class _AuthError extends Error {
+  constructor(subtype, message) {
+    super(message ?? subtype);
+    this.name = "AuthError";
+    this.subtype = subtype;
+    Object.setPrototypeOf(this, _AuthError.prototype);
+  }
+};
+
+// src/extractGrantContext.ts
+var DEFAULT_PORTAL_URL = "https://portal.anuma.ai";
+var DEFAULT_TIMEOUT_MS = 5e3;
+function readBearer(req) {
+  const headerValue = req.headers.authorization ?? req.headers.Authorization;
+  if (!headerValue) {
+    throw new AuthError("missing_bearer");
+  }
+  const value = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+  if (!value) throw new AuthError("missing_bearer");
+  const [scheme, token] = value.split(" ");
+  if (!scheme || scheme.toLowerCase() !== "bearer" || !token) {
+    throw new AuthError("invalid_bearer", "Authorization header must use the Bearer scheme");
+  }
+  return token;
+}
+async function extractGrantContext(req, opts = {}) {
+  const bearer = readBearer(req);
+  const baseUrl = opts.baseUrl ?? process.env.ANUMA_PORTAL_URL ?? DEFAULT_PORTAL_URL;
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetchImpl(`${baseUrl}/api/v1/me`, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${bearer}`
+      },
+      signal: controller.signal
+    });
+  } catch (err) {
+    if (err.name === "AbortError") {
+      throw new Error(`portal /api/v1/me timed out after ${timeoutMs}ms`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+  if (response.status === 401) {
+    throw new AuthError("expired", "portal /api/v1/me returned 401");
+  }
+  if (response.status === 403) {
+    throw new AuthError("revoked", "portal /api/v1/me returned 403");
+  }
+  if (!response.ok) {
+    throw new Error(`portal /api/v1/me returned ${response.status}`);
+  }
+  const me = await response.json();
+  if (!me.user_address || !me.client_id) {
+    throw new AuthError("invalid_bearer", "portal /api/v1/me missing user_address or client_id");
+  }
+  return {
+    userAddress: me.user_address,
+    clientId: me.client_id,
+    scopes: me.scopes ?? [],
+    bearer
+  };
+}
+
+// src/createPortalClient.ts
+var DEFAULT_PORTAL_URL2 = "https://portal.anuma.ai";
+var DEFAULT_TIMEOUT_MS2 = 5e3;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RETRY_BASE_MS = 100;
+function jitter(baseMs, attempt) {
+  const exp = baseMs * Math.pow(2, attempt);
+  return Math.floor(Math.random() * exp);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseMintError(status, body) {
+  const code = body.code ?? body.error;
+  if (status === 412 || status === 403) {
+    if (code === "connector_not_connected") {
+      return {
+        code: "connector_not_connected",
+        provider: body.provider ?? "unknown",
+        connectUrl: body.connect_url ?? ""
+      };
+    }
+    if (code === "scope_not_covered") {
+      return {
+        code: "scope_not_covered",
+        provider: body.provider ?? "unknown",
+        missingScopes: body.missing_scopes ?? [],
+        connectUrl: body.connect_url ?? ""
+      };
+    }
+    if (code === "insufficient_scope") {
+      return {
+        code: "insufficient_scope",
+        required: body.required ?? ""
+      };
+    }
+  }
+  return {
+    code: "unknown",
+    message: body.message ?? `mint failed with status ${status}`
+  };
+}
+function createPortalClient(bearer, opts = {}) {
+  const baseUrl = opts.baseUrl ?? process.env.ANUMA_PORTAL_URL ?? DEFAULT_PORTAL_URL2;
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+  const maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const retryBaseMs = opts.retryBaseMs ?? DEFAULT_RETRY_BASE_MS;
+  async function requestWithRetry(path, init) {
+    let lastErr;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetchImpl(`${baseUrl}${path}`, {
+          ...init,
+          signal: controller.signal,
+          headers: {
+            Authorization: `Bearer ${bearer}`,
+            ...init.headers
+          }
+        });
+        clearTimeout(timer);
+        if (response.status >= 500) {
+          lastErr = new Error(`portal ${path} returned ${response.status}`);
+          if (attempt < maxRetries - 1) {
+            await sleep(jitter(retryBaseMs, attempt));
+            continue;
+          }
+          return response;
+        }
+        return response;
+      } catch (err) {
+        clearTimeout(timer);
+        lastErr = err;
+        if (attempt < maxRetries - 1) {
+          await sleep(jitter(retryBaseMs, attempt));
+          continue;
+        }
+        throw lastErr;
+      }
+    }
+    throw lastErr ?? new Error(`portal ${path} failed`);
+  }
+  return {
+    async mintConnectorToken(provider) {
+      const response = await requestWithRetry(`/api/v1/connector-tokens/${provider}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" }
+      });
+      if (response.ok) {
+        const body2 = await response.json();
+        return {
+          ok: true,
+          accessToken: body2.access_token,
+          expiresAt: Date.now() + body2.expires_in * 1e3
+        };
+      }
+      if (response.status >= 500) {
+        return {
+          ok: false,
+          error: { code: "upstream_unavailable" }
+        };
+      }
+      let body = {};
+      try {
+        body = await response.json();
+      } catch {
+        body = {};
+      }
+      return { ok: false, error: parseMintError(response.status, body) };
+    },
+    async listConnectors() {
+      const response = await requestWithRetry("/api/v1/connectors", { method: "GET" });
+      if (!response.ok) {
+        throw new Error(`portal /api/v1/connectors returned ${response.status}`);
+      }
+      const body = await response.json();
+      return body.connectors.map((c) => ({
+        oauthApp: c.oauth_app,
+        externalAccount: c.external_account,
+        grantedScopes: c.granted_scopes ?? [],
+        connectedAt: c.connected_at ?? 0
+      }));
+    },
+    async createConnectTicket(opts2) {
+      const response = await requestWithRetry("/api/v1/connect-tickets", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          oauth_app: opts2.oauthApp,
+          requested_scopes: opts2.requestedScopes,
+          return_to: opts2.returnTo
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`portal /api/v1/connect-tickets returned ${response.status}`);
+      }
+      const body = await response.json();
+      return {
+        ticketId: body.ticket_id,
+        expiresAt: body.expires_at,
+        connectUrl: body.connect_url
+      };
+    }
+  };
+}
+
+// src/createConnectorTokenGetter.ts
+import {
+  createConnectorTokenGetter as sdkCreateConnectorTokenGetter
+} from "@anuma/sdk/tools";
+function createConnectorTokenGetter(client, provider, opts) {
+  return sdkCreateConnectorTokenGetter(client, provider, opts);
+}
+
+// src/runAgentRequest.ts
+import {
+  runToolLoop
+} from "@anuma/sdk/server";
+import { CONNECTOR_ERROR_MARKER } from "@anuma/sdk/tools";
+function isConnectorErrorPayload(value) {
+  if (!value || typeof value !== "object") return false;
+  return value[CONNECTOR_ERROR_MARKER] === true;
+}
+function extractConnectorToolErrors(toolResults) {
+  if (!toolResults) return [];
+  const errors = [];
+  for (let idx = 0; idx < toolResults.length; idx++) {
+    const entry = toolResults[idx];
+    if (typeof entry.result !== "string") continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(entry.result);
+    } catch {
+      continue;
+    }
+    if (!isConnectorErrorPayload(parsed)) continue;
+    errors.push({
+      toolName: entry.name,
+      callId: `call_${idx}`,
+      error: {
+        code: parsed.code,
+        provider: parsed.provider,
+        connectUrl: parsed.connect_url,
+        missingScopes: parsed.missing_scopes,
+        required: parsed.required
+      }
+    });
+  }
+  return errors;
+}
+function extractUsage(data) {
+  if (!data || typeof data !== "object") return void 0;
+  const usage = data.usage;
+  if (!usage) return void 0;
+  const input = typeof usage.prompt_tokens === "number" ? usage.prompt_tokens : typeof usage.input_tokens === "number" ? usage.input_tokens : void 0;
+  const output = typeof usage.completion_tokens === "number" ? usage.completion_tokens : typeof usage.output_tokens === "number" ? usage.output_tokens : void 0;
+  const total = typeof usage.total_tokens === "number" ? usage.total_tokens : void 0;
+  if (input === void 0 && output === void 0 && total === void 0) return void 0;
+  return { inputTokens: input, outputTokens: output, totalTokens: total };
+}
+function finalAssistantMessage(data) {
+  if (!data || typeof data !== "object") return void 0;
+  const chatLike = data;
+  const chatMsg = chatLike.choices?.[0]?.message;
+  if (chatMsg) return chatMsg;
+  const resp = data;
+  const output = resp.output;
+  if (Array.isArray(output)) {
+    for (const item of output) {
+      const message = item.message;
+      if (message) return message;
+    }
+  }
+  return void 0;
+}
+function buildResponseMessages(inputMessages, toolResults, finalMessage) {
+  const out = [...inputMessages];
+  if (toolResults && toolResults.length > 0) {
+    out.push({
+      role: "assistant",
+      tool_calls: toolResults.map((tr, idx) => ({
+        id: `call_${idx}`,
+        type: "function",
+        function: { name: tr.name, arguments: "{}" }
+      }))
+    });
+    for (let idx = 0; idx < toolResults.length; idx++) {
+      const tr = toolResults[idx];
+      const content = typeof tr.result === "string" ? tr.result : JSON.stringify(tr.result) ?? "";
+      out.push({
+        role: "tool",
+        tool_call_id: `call_${idx}`,
+        content: [{ type: "text", text: content }]
+      });
+    }
+  }
+  if (finalMessage) out.push(finalMessage);
+  return out;
+}
+async function denyInteractive() {
+  throw new Error("server agent cannot initiate OAuth; user must connect via portal");
+}
+async function runAgentRequest(opts) {
+  const grant = await extractGrantContext(opts.request, opts.portalClientOpts);
+  const portal = createPortalClient(grant.bearer, opts.portalClientOpts);
+  const tools = (opts.toolFactories ?? []).flatMap((factory) => factory(portal));
+  const loopMessages = [
+    { role: "system", content: [{ type: "text", text: opts.agent.prompt }] },
+    ...opts.messages
+  ];
+  const loopResult = await runToolLoop({
+    messages: loopMessages,
+    model: opts.agent.model.default,
+    token: grant.bearer,
+    tools,
+    headers: { "X-Anuma-Surface": "agent" },
+    ...opts.portalBaseUrl ? { baseUrl: opts.portalBaseUrl } : void 0,
+    ...opts.transport ? { transport: opts.transport } : void 0,
+    ...opts.apiType ? { apiType: opts.apiType } : void 0
+  });
+  if (loopResult.error !== null) {
+    throw new Error(loopResult.error);
+  }
+  const finalMessage = finalAssistantMessage(loopResult.data);
+  const autoResults = loopResult.autoExecutedToolResults;
+  const messages = buildResponseMessages(opts.messages, autoResults, finalMessage);
+  const toolErrors = extractConnectorToolErrors(autoResults);
+  const usage = extractUsage(loopResult.data);
+  return { messages, toolErrors, usage, grant };
+}
+export {
+  AuthError,
+  createConnectorTokenGetter,
+  createPortalClient,
+  denyInteractive,
+  extractConnectorToolErrors,
+  extractGrantContext,
+  runAgentRequest
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@anuma/agent-runtime",
+  "version": "1.0.0-next.20260602215959",
+  "description": "Server-side runtime contract for Anuma agents — extractGrantContext, PortalClient, runAgentRequest.",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anuma-ai/sdk.git",
+    "directory": "packages/agents/runtime"
+  },
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/anuma-ai/sdk/issues"
+  },
+  "homepage": "https://github.com/anuma-ai/sdk#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@anuma/sdk": "1.0.0-next.20260602215959"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.14",
+    "@anuma/sdk": "1.0.0-next.20260602215959"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}