@gethelio/proxy 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -113,6 +113,7 @@ declare const helioConfigSchema: z.ZodObject<{
         connect_timeout: z.ZodDefault<z.ZodString>;
         request_timeout: z.ZodDefault<z.ZodString>;
         forward_headers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strip>;
     listen: z.ZodPrefault<z.ZodObject<{
         port: z.ZodDefault<z.ZodNumber>;
@@ -483,8 +484,7 @@ declare function startServer(app: Hono, config: HelioConfig): ServerHandle;
  */
 declare function startSidebandServer(app: Hono, port: number, host?: string): ServerHandle;
 
-/** Options for constructing an UpstreamForwarder. */
-interface UpstreamForwarderOptions {
+interface StreamableHttpForwarderOptions {
     /** The upstream MCP server URL (e.g. "http://localhost:8080/mcp"). */
     url: string;
     /** Static headers to include on every upstream request (e.g. API keys). */
@@ -493,17 +493,44 @@ interface UpstreamForwarderOptions {
     requestTimeoutMs?: number;
 }
 /**
- * Forward MCP requests to an upstream server via HTTP.
+ * Spec-compliant upstream MCP Streamable HTTP client.
  *
- * Sends JSON-RPC POST requests to the configured URL, passes through
- * session IDs and per-request headers, and captures request timing.
+ * Parses both `application/json` and `text/event-stream` POST responses, sends
+ * the negotiated protocol version, relays the upstream session id back
+ * downstream, and — for Helio-internal requests with no downstream session —
+ * borrows an internally-managed session established via `initialize`.
  */
-declare class UpstreamForwarder implements McpForwarder {
+declare class StreamableHttpForwarder implements McpForwarder {
     private readonly url;
     private readonly staticHeaders;
     private readonly requestTimeoutMs;
-    constructor(options: UpstreamForwarderOptions);
+    private readonly sessions;
+    constructor(options: StreamableHttpForwarderOptions);
+    /** Lifecycle parity with sse/stdio. No eager connect — sessions are lazy. */
+    connect(): Promise<void>;
+    /** Lifecycle parity with sse/stdio. */
+    close(): Promise<void>;
     forward(request: McpRequest): Promise<ForwardResult>;
+    /**
+     * Helio-internal execution path (startup prime / internal maintenance) that
+     * may borrow the proxy-managed internal session.
+     */
+    forwardInternal(request: McpRequest): Promise<ForwardResult>;
+    private send;
+}
+
+/** Options for constructing an UpstreamForwarder. */
+type UpstreamForwarderOptions = StreamableHttpForwarderOptions;
+/**
+ * @deprecated Use `StreamableHttpForwarder` directly for new code.
+ *
+ * Backward-compatible alias for older integrations that imported
+ * `UpstreamForwarder`. Kept to avoid a breaking API change.
+ *
+ * Behavior matches `StreamableHttpForwarder` (including Streamable HTTP SSE
+ * response parsing and managed internal session support).
+ */
+declare class UpstreamForwarder extends StreamableHttpForwarder {
 }
 
 /** Options for constructing an SseUpstreamForwarder. */
@@ -1582,6 +1609,11 @@ declare class GovernedForwarder implements McpForwarder {
      *
      * This path is intended for startup warm-up and intentionally bypasses policy
      * and audit handling. Runtime tools/list requests still flow through forward().
+     *
+     * When the inner forwarder exposes `forwardInternal` (duck-typed), the prime
+     * request is routed through it so session-enforcing servers (e.g. Streamable
+     * HTTP upstreams) receive the request on the managed internal session rather
+     * than as a sessionless call that they would reject with HTTP 400.
      */
     primeAnnotationCache(): Promise<AnnotationCachePrimeResult>;
     forward(request: McpRequest): Promise<ForwardResult>;
@@ -1871,4 +1903,4 @@ interface DashboardAppOptions {
  */
 declare function createDashboardApp(deps: DashboardAppDeps, options?: DashboardAppOptions): Hono;
 
-export { type ApprovalAppOptions, type ApprovalChannel, type ApprovalOutcome, ApprovalQueue, type ApprovalQueueOptions, ApprovalRouter, type ApprovalRouterOptions, type ApprovalStatus, type ApprovalTicket, type AuditAggregateStats, type AuditListResult, type AuditPaginationOptions, type AuditQueryFilters, type AuditRecord, AuditStore, type AuditStoreOptions, type AuditTimeBucket, AuditWriter, type AuditWriterOptions, type CompilePoliciesResult, type CompiledPolicy, type CompiledPolicyRule, ConfigError, type CreateAppOptions, type DashboardAppDeps, type DashboardAppOptions, DashboardEventBus, type DashboardEventType, type DashboardEvents, type EvidenceEntry, EvidenceStore, type EvidenceStoreOptions, GovernedForwarder, type GovernedForwarderOptions, type HelioConfig, type MatchContext, type PolicyDecision, PolicyParseError, QueueChannel, type RateLimitCheckParams, type RateLimitKeyState, type RateLimitResult, RateLimiter, type RateLimiterOptions, type ServerHandle, type SessionState, type SlackActionAppOptions, SlackChannel, type SlackChannelOptions, type SpendLimitCheckParams, type SpendLimitKeyState, type SpendLimitResult, SpendLimiter, type SpendLimiterOptions, SseUpstreamForwarder, type SseUpstreamForwarderOptions, StdioForwarder, type StdioForwarderOptions, UpstreamForwarder, type UpstreamForwarderOptions, VERSION, WebhookChannel, type WebhookChannelOptions, compilePolicies, createApp, createApprovalApp, createChannels, createDashboardApp, createSidebandApp, createSlackActionApp, evaluatePolicy, loadConfig, matchRule, startServer, startSidebandServer };
+export { type ApprovalAppOptions, type ApprovalChannel, type ApprovalOutcome, ApprovalQueue, type ApprovalQueueOptions, ApprovalRouter, type ApprovalRouterOptions, type ApprovalStatus, type ApprovalTicket, type AuditAggregateStats, type AuditListResult, type AuditPaginationOptions, type AuditQueryFilters, type AuditRecord, AuditStore, type AuditStoreOptions, type AuditTimeBucket, AuditWriter, type AuditWriterOptions, type CompilePoliciesResult, type CompiledPolicy, type CompiledPolicyRule, ConfigError, type CreateAppOptions, type DashboardAppDeps, type DashboardAppOptions, DashboardEventBus, type DashboardEventType, type DashboardEvents, type EvidenceEntry, EvidenceStore, type EvidenceStoreOptions, GovernedForwarder, type GovernedForwarderOptions, type HelioConfig, type MatchContext, type PolicyDecision, PolicyParseError, QueueChannel, type RateLimitCheckParams, type RateLimitKeyState, type RateLimitResult, RateLimiter, type RateLimiterOptions, type ServerHandle, type SessionState, type SlackActionAppOptions, SlackChannel, type SlackChannelOptions, type SpendLimitCheckParams, type SpendLimitKeyState, type SpendLimitResult, SpendLimiter, type SpendLimiterOptions, SseUpstreamForwarder, type SseUpstreamForwarderOptions, StdioForwarder, type StdioForwarderOptions, StreamableHttpForwarder, type StreamableHttpForwarderOptions, UpstreamForwarder, type UpstreamForwarderOptions, VERSION, WebhookChannel, type WebhookChannelOptions, compilePolicies, createApp, createApprovalApp, createChannels, createDashboardApp, createSidebandApp, createSlackActionApp, evaluatePolicy, loadConfig, matchRule, startServer, startSidebandServer };