@gethelio/proxy 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -81,6 +81,11 @@ declare const policiesSchema: z.ZodObject<{
             suggestion: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>>>;
+    on_tool_drift: z.ZodOptional<z.ZodEnum<{
+        require_approval: "require_approval";
+        log: "log";
+        block: "block";
+    }>>;
     hot_reload: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 declare const approvalChannelSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -204,6 +209,11 @@ declare const helioConfigSchema: z.ZodObject<{
                 suggestion: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
         }, z.core.$strict>>>;
+        on_tool_drift: z.ZodOptional<z.ZodEnum<{
+            require_approval: "require_approval";
+            log: "log";
+            block: "block";
+        }>>;
         hot_reload: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     approval: z.ZodPrefault<z.ZodObject<{
@@ -366,6 +376,11 @@ interface CompiledPolicy {
     readonly defaultAction: 'allow' | 'deny';
     readonly flagDestructive?: 'log' | 'require_approval';
     readonly dryRun?: boolean;
+    /**
+     * Response to tool definition drift (issue #25). Undefined means "block"
+     * at the use site — conservative by default.
+     */
+    readonly onToolDrift?: 'block' | 'require_approval' | 'log';
     readonly rules: readonly CompiledPolicyRule[];
 }
 /** A non-fatal warning produced during policy compilation. */
@@ -484,8 +499,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). */
@@ -494,17 +508,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. */
@@ -1583,9 +1624,23 @@ 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>;
+    /**
+     * Apply a tools/list response to the definition cache and surface any
+     * drift: console warning + immediate audit record per event. Single entry
+     * point for both runtime tools/list responses and startup priming, so the
+     * cache is updated exactly once per response.
+     */
+    private applyToolDefinitionUpdate;
+    /** Write an immediate audit record for a drift event (not a tool call). */
+    private writeDriftAuditRecord;
     private handleToolsCall;
     private handleApproval;
     private handleRateLimit;
@@ -1600,6 +1655,7 @@ declare class GovernedForwarder implements McpForwarder {
     /** Determine if the request was actually forwarded to the upstream MCP server. */
     private wasForwardedUpstream;
     private writeAuditRecord;
+    private makeDriftBlockResult;
     private makeDenyResult;
     private makePolicyMisconfiguredResult;
     private makeUnsupportedResult;
@@ -1872,4 +1928,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 };