@mitralab.io/functions-sdk 0.2.3-beta.0 → 0.2.4-beta.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project are documented in this file.
 
+## 0.2.4-beta.0
+
+- Depend on `@mitralab.io/sdk-core@0.2.9-beta.1`, which takes the chat's direct channel to its box
+  as the Agent session transport. Sessions ask the Copilot for the channel and send to the box:
+  over its WebSocket, or over its HTTP routes (POST to send, SSE to read) on a runtime without
+  one. The Copilot SSE and `POST /inputs` stay as the fallback, announced by a `channelDeclined`
+  raw event. Only an agent chat, a task with an `agentId`, goes to the box, also when opened by
+  `taskId`; a chat without `agentId` stays on the Copilot and never asks for the channel. New agent
+  chats are created with `runtime: "T3"` unless the session names a runtime.
+- Wire the channel to the client's API URL. The box routes use `globalThis.fetch`, never the
+  client's `fetch`, so a custom fetch that adds `Authorization` cannot send the token to the box.
+  `auto` uses the box WebSocket when the runtime has one and HTTP otherwise, which is the case of
+  the Serverless Functions runtime on Node 20. No WebSocket dependency is added.
+- Accept an optional `WebSocket` implementation, such as `ws`, in the client configuration.
+- `transport: "websocket"` no longer rejects: it now means the box socket, and falls back to the
+  Copilot SSE with `channelDeclined` when no WebSocket is available.
+- The new `accepted` session event fires when the box admits the turn, so a Function can send,
+  await it, and return. `sendAndWait` is unchanged.
+- Pin the SDK-PARITY-001 corpus to Core `0.2.9-beta.1` with its digest and immutable source commit.
+
+## 0.2.3
+
+Stable release of the 0.2.2-beta.0 and 0.2.3-beta.0 line. This release only moves the Core
+dependency. The module layer forwards inputs verbatim, so no runtime behavior in this package
+changes.
+
+- Depend on `@mitralab.io/sdk-core@0.2.8`, the stable release of the 0.2.8-beta.0 surface: the
+  credential scope, the person's custom providers on connections and credentials, the runtime on
+  task creation, and no `model` field on Agent task creation or on the message send.
+- Pin the SDK-PARITY-001 corpus to Core `0.2.8` with its digest and immutable source commit.
+
 ## 0.2.3-beta.0
 
 This release only moves the Core dependency. The module layer forwards inputs verbatim, so no

package/README.md

@@ -227,17 +227,22 @@ single-Function methods for composed scheduling.
 The native SDK deliberately has no separate schedule lifecycle methods. Create, patch, get, and
 list keep Function state and its composed cron fields in one contract.
 
-### Live Agent sessions over HTTP
+### Live Agent sessions
 
-`agentTasks.session()` adds the Core session state machine to the native Copilot task module. The
-Functions adapter uses the direct HTTP channel because Server Functions do not provide a browser
-WebSocket runtime:
+`agentTasks.session()` adds the Core session state machine to the native Copilot task module.
+Core also owns the direct channel to the chat's box: the session asks the Copilot where the chat
+is served (`POST /copilot/api/v1/tasks/{taskId}/channel`) and then talks to that box, which runs
+the turn. This package only wires the channel to the client's API URL and WebSocket.
+
+Only an agent chat, a task with an `agentId`, goes to the box, whether the session creates it or
+opens it with `session({ taskId })`. A chat without `agentId` keeps the Copilot stream and inputs
+as before and never asks for the channel.
 
 ```typescript
 const session = mitra.agentTasks.session({
   create: true,
+  agentId: "agent-id",
   agentType: "CODEX",
-  transport: "http",
 })
 
 session.on("delta", ({ delta, kind }) => {
@@ -249,17 +254,74 @@ console.log(result.content)
 session.close()
 ```
 
-Existing tasks use `mitra.agentTasks.session({ taskId })`. The adapter opens
-`GET /copilot/api/v1/tasks/{taskId}/events` as a Server-Sent Events (SSE) stream before it sends
-input to `POST /inputs`. Both calls use the fixed runtime token in `Authorization` plus
-`X-App-Id`; credentials are never placed in the URL. `transport: "auto"` and `"http"` use this
-channel, while `"websocket"` rejects locally.
+Existing tasks use `mitra.agentTasks.session({ taskId })`. A new agent chat is created on the
+box runtime (`runtime: "T3"`) unless the session names another runtime.
+
+`transport` picks how the session tries to reach the box:
+
+- `auto`, the default, uses the box WebSocket when the runtime has one and the box HTTP routes
+  otherwise: a `POST` per message and a Server-Sent Events (SSE) stream for events.
+- `http` uses the box HTTP routes.
+- `websocket` uses the box WebSocket.
+
+Until the box offers the route the session asks for, the session falls back to the Copilot and
+says so with `channelDeclined` (see below). The transport is a preference, not a guarantee.
+
+The Serverless Functions runtime runs Node 20, which has no global `WebSocket`, so sessions
+there reach the box over HTTP. Node 22 and newer have one. To use the socket on a runtime without
+it, pass an implementation such as `ws` when you create the client; this package does not depend
+on one:
+
+```typescript
+import WebSocket from "ws"
+
+const mitra = createClient({ WebSocket })
+```
+
+The box is reached through the channel URL the Copilot returns, which carries a short-lived
+grant; the runtime token is never sent to the box. The box routes use `globalThis.fetch`, not the
+`fetch` given to the client, so a custom fetch that adds `Authorization` cannot leak the token
+there. Core follows only a channel on the configured
+API host or a Mitra box host. When the Copilot offers no channel, or the offer cannot be followed
+(for example a `websocket` session with no WebSocket available), the session stays on the
+Copilot: it opens `GET /copilot/api/v1/tasks/{taskId}/events` as an SSE stream with the runtime
+token in `Authorization` plus `X-App-Id`, and sends input to `POST /inputs`. That fallback is
+never silent: the session first emits a `raw` event of type `channelDeclined` with the reason.
+
+`timeoutMs` also bounds `POST /channel`, which the Copilot holds open while the box boots. A
+short `timeoutMs` can abort that request, and the session then falls back to the Copilot with
+`channelDeclined` reason `unavailable`; leave it unset, or above the box boot time, for agent
+chats. On the Copilot stream, `timeoutMs` applies only while waiting for the SSE response
+headers. The parser ignores `hello` and `ping` keepalives, and a stream silent for 60 seconds counts
+as a disconnect; Core then reconnects once and reconciles persisted messages. The box channel has
+its own handshake, silence, redial, and admission deadlines in Core.
+
+#### Send and return
+
+A Function does not have to wait for the whole turn. Once the box admits the message, the turn
+runs and is recorded without the Function, so it can send, wait for `accepted`, and return:
+
+```typescript
+export async function handler(input: { taskId: string; prompt: string }) {
+  const session = mitra.agentTasks.session({ taskId: input.taskId })
+  try {
+    await new Promise<void>((resolve, reject) => {
+      session.on("accepted", () => resolve())
+      session.on("error", ({ code, error }) =>
+        reject(new Error(code ? `${code}: ${error}` : error)),
+      )
+      session.send(input.prompt)
+    })
+    return { accepted: true }
+  } finally {
+    session.close()
+  }
+}
+```
 
-When `timeoutMs` is configured, it applies only while waiting for the SSE response headers. Once
-the handshake succeeds, the body remains open until the session closes, its abort signal fires, or
-the server disconnects. The parser ignores `hello` and `ping` keepalives and forwards `message`
-events to the Core session manager. Core performs one reconnect and reconciles persisted messages
-after an unexpected disconnect.
+`accepted` fires when the box starts the admitted turn, or after the Copilot's `202` on the
+fallback. A refusal fires `error` instead, and a box that does not answer fails the send after
+35 seconds. Returning before `accepted` may lose the message.
 
 ### App-scoped Code Studio access
 
@@ -383,8 +445,7 @@ part of this package. Every re-export is the legacy binding itself, unchanged, a
 `@deprecated` with the new equivalent when one exists. Native raw SQL is available through `sql`;
 app authoring and Agent runtime modules cover most builder and Agent SDK operations. Builder-specific
 Git and direct-S3 flows have no one-to-one replacement and remain supported through the legacy
-exports. Live Agent sessions have a native HTTP and SSE replacement through
-`agentTasks.session()`.
+exports. Live Agent sessions have a native replacement through `agentTasks.session()`.
 
 `getGitConfigMitra` remains legacy-only because credential minting is an internal Sandbox POST
 authenticated between services and is not published for app tokens. The Sandbox already owns Git

package/contracts/sdk-core-v0.2.8.manifest.json

@@ -0,0 +1,15 @@
+{
+  "contract": "SDK-PARITY-001",
+  "version": "0.2.8",
+  "dependency": {
+    "package": "@mitralab.io/sdk-core",
+    "version": "0.2.8",
+    "contractPath": "contracts/v0.2.8/sdk-parity.json"
+  },
+  "sha256": "85f48fa684d2f0bf44ab818d69f53c1802b6699b78cf49ab0c64c442891354cf",
+  "source": {
+    "repository": "https://github.com/mitralab-dev/mitra-core-sdk",
+    "commit": "303ed917cf134ceb6020d49b2896518a357c748a",
+    "path": "contracts/v0.2.8/sdk-parity.json"
+  }
+}

package/contracts/sdk-core-v0.2.9-beta.1.manifest.json

@@ -0,0 +1,15 @@
+{
+  "contract": "SDK-PARITY-001",
+  "version": "0.2.9-beta.1",
+  "dependency": {
+    "package": "@mitralab.io/sdk-core",
+    "version": "0.2.9-beta.1",
+    "contractPath": "contracts/v0.2.9-beta.1/sdk-parity.json"
+  },
+  "sha256": "f0ec4130c399f7102ad20b6dc54ed50da957003d19d3ab811d013ce89b5cde06",
+  "source": {
+    "repository": "https://github.com/mitralab-dev/mitra-core-sdk",
+    "commit": "e16503d5b9055a1ad759ebc061a4f80a1be62ed2",
+    "path": "contracts/v0.2.9-beta.1/sdk-parity.json"
+  }
+}

package/dist/index.cjs

@@ -363,12 +363,7 @@ var AgentTaskSseEventSource = class {
   constructor(config) {
     this.config = config;
   }
-  async open(taskId, observer, signal, transport) {
-    if (transport === "websocket") {
-      throw new MitraConfigurationError(
-        "WebSocket Agent sessions are not available in the Functions runtime"
-      );
-    }
+  async open(taskId, observer, signal) {
     if (signal?.aborted) throw signal.reason ?? new Error("Agent event stream was aborted");
     const controller = new AbortController();
     let handshakeTimedOut = false;
@@ -748,7 +743,8 @@ function resolveConfig(config = {}, environment = readDefaultEnvironment()) {
     appId,
     ...dataSourceId === void 0 ? {} : { dataSourceId: dataSourceId.trim() },
     ...timeoutMs === void 0 ? {} : { timeoutMs },
-    fetch: fetchImplementation
+    fetch: fetchImplementation,
+    ...config.WebSocket === void 0 ? {} : { WebSocket: config.WebSocket }
   };
 }
 
@@ -829,27 +825,28 @@ var DefaultMitraClient = class {
     this.agentConnections = core.agentConnections;
     this.agentCredentials = core.agentCredentials;
     this.agents = core.agents;
-    const agentSessionManager = (0, import_sdk_core3.createAgentTaskSessionManager)({
-      tasks: core.agentTasks,
-      eventSource: new AgentTaskSseEventSource({
-        baseUrl: `${config.apiUrl}/copilot`,
-        accessToken: config.accessToken,
-        appId: config.appId,
-        ...config.timeoutMs === void 0 ? {} : { timeoutMs: config.timeoutMs },
-        fetch: config.fetch,
-        errors: coreErrors
-      })
-    });
-    this.agentTasks = (0, import_sdk_core3.withAgentTaskSessions)(core.agentTasks, {
-      session: (options) => {
-        if (options.transport === "websocket") {
-          throw new MitraConfigurationError(
-            "WebSocket Agent sessions are not available in the Functions runtime; use http or auto"
-          );
+    this.agentTasks = (0, import_sdk_core3.withAgentTaskSessions)(
+      core.agentTasks,
+      (0, import_sdk_core3.createAgentTaskSessionManager)({
+        tasks: core.agentTasks,
+        eventSource: new AgentTaskSseEventSource({
+          baseUrl: `${config.apiUrl}/copilot`,
+          accessToken: config.accessToken,
+          appId: config.appId,
+          ...config.timeoutMs === void 0 ? {} : { timeoutMs: config.timeoutMs },
+          fetch: config.fetch,
+          errors: coreErrors
+        }),
+        // Core owns the channel to the box. Without a WebSocket, as in the Functions runtime on
+        // Node 20, `auto` reaches the box over HTTP. The box routes use the global fetch, never
+        // `config.fetch`: the grant in the channel URL is the box credential, and a custom fetch
+        // that adds `Authorization` would send the Function token to the box.
+        directChannel: {
+          apiUrl: config.apiUrl,
+          ...config.WebSocket === void 0 ? {} : { WebSocket: config.WebSocket }
         }
-        return agentSessionManager.session(options);
-      }
-    });
+      })
+    );
     this.apps = appModules.apps;
     this.auth = core.auth;
     this.context = core.context;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { AppsModule, AppGetOptions, AppDefinition, AppUpdateInput, AppFiles, AppDeploy, AppPublishOptions, PageOptions, Page, AppVersion, SdkCore, AgentTasksWithSessions, AuthModule } from '@mitralab.io/sdk-core';
-export { AgentBulkDeleteResult, AgentConnectionCreateInput, AgentConnectionsModule, AgentCredentialsModule, AgentDefinition, AgentInput, AgentQueueItem, AgentSendAndWaitOptions, AgentSendOptions, AgentSessionTransport, AgentTask, AgentTaskCreateInput, AgentTaskEvent, AgentTaskEventConnection, AgentTaskEventObserver, AgentTaskEventSource, AgentTaskInput, AgentTaskListOptions, AgentTaskTurnError, AgentTasksModule, AgentTasksWithSessions, AgentTurnResult, AgentUpdateItem, AgentsModule, AppColor, AppContext, AppCreateInput, AppDefinition, AppDeploy, AppDomain, AppFiles, AppGetOptions, AppListOptions, AppMember, AppPublishOptions, AppSummary, AppUpdateInput, AppVersion, AppVersionStatus, AppsModule, AuthModule, AuthenticationResult, BatchExecution, BatchStatementResult, BulkUnsubscribeResult, ColumnInput, ConnectionConfig, ConnectionTestResult, ContextModule, CopilotProvider, AgentConnection as CoreAgentConnection, AgentMessage as CoreAgentMessage, AgentModel as CoreAgentModel, AgentTaskSession as CoreAgentTaskSession, AgentTaskSessionEventMap as CoreAgentTaskSessionEventMap, AgentTaskSessionOptions as CoreAgentTaskSessionOptions, AgentTaskSessionStatus as CoreAgentTaskSessionStatus, AgentTimelineItem as CoreAgentTimelineItem, AgentToolEvent as CoreAgentToolEvent, ListTablesOptions as CoreListTablesOptions, CredentialStatus, CustomQueriesModule, CustomQueryDefinition, CustomQueryInput, CustomQuerySummary, CustomQueryUpdateInput, DataSourceBulkItemResult, DataSourceBulkResult, DataSourceCreateInput, DataSourceDbType, DataSourceDefinition, DataSourceInstanceType, DataSourceUpdateInput, DataSourcesModule, DdlStatement, DeviceAuthorization, DmlStatement, EmptyFunctionInput, EntitiesModule, EntitiesProxy, EntityListOptions, EntityTable, ExistingAgentTaskSessionOptions, FunctionBulkCreateInput, FunctionBulkDeleteInput, FunctionBulkDeleteResult, FunctionBulkPatchInput, FunctionBulkPatchItem, FunctionBulkUpdateItem, FunctionCreateInput, FunctionDefinition, FunctionExecution, FunctionListOptions, FunctionPatchInput, FunctionRuntime, FunctionSecrets, FunctionSummary, FunctionUpdateInput, FunctionVersion, FunctionVersionListOptions, FunctionVisibility, FunctionsAdminModule, FunctionsModule, ImportColumnMapping, ImportDefinition, ImportExecution, ImportExecutionListOptions, ImportInput, ImportProcessing, ImportSchedule, ImportSource, ImportTarget, ImportsModule, IntegrationAdminModule, IntegrationConnectionStatus, IntegrationCredentialRule, IntegrationExecution, IntegrationFieldSchema, IntegrationFieldSchemaInput, IntegrationLoginConfig, IntegrationModule, IntegrationProxyMode, IntegrationRequestConfig, IntegrationResource, IntegrationResourceInput, IntegrationResourceParam, IntegrationResourceSummary, IntegrationResourceUpdateInput, IntegrationResourcesModule, IntegrationTemplate, IntegrationTemplateSummary, IntegrationTemplateType, IntegrationTemplatesModule, IntegrationTokenExtraction, InviteAppUserInput, InvocationType, JsonValue, ListTemplateConfigsOptions, MembersModule, MessengerModule, NewAgentTaskSessionOptions, OAuthExchangeInput, OAuthStartResult, Page, PageOptions, PlanPrice, ProviderCredentialStatus, ProxyInput, ProxyResult, PublicFunctionAsyncResult, PublicFunctionResult, PublicFunctionsModule, QueriesModule, QueryResult, SchemaModule, SchemaScope, SchemaTables, SqlModule, TableColumn, TableDefinition, TableForeignKey, TemplateConfig, TemplateConfigBulkItemResult, TemplateConfigBulkResult, TemplateConfigCreateInput, TemplateConfigPage, TemplateConfigSummary, TemplateConfigUpdateInput, Tenant, TestCredentialsInput, User, UserPlan, WorkflowDefinition, WorkflowExecution, WorkflowInput, WorkflowSummary, WorkflowsModule } from '@mitralab.io/sdk-core';
+import { AppsModule, AppGetOptions, AppDefinition, AppUpdateInput, AppFiles, AppDeploy, AppPublishOptions, PageOptions, Page, AppVersion, AgentWebSocketConstructor, SdkCore, AgentTasksWithSessions, AuthModule } from '@mitralab.io/sdk-core';
+export { AgentBulkDeleteResult, AgentConnectionCreateInput, AgentConnectionsModule, AgentCredentialsModule, AgentDefinition, AgentInput, AgentQueueItem, AgentSendAndWaitOptions, AgentSendOptions, AgentSessionTransport, AgentTask, AgentTaskCreateInput, AgentTaskEvent, AgentTaskEventConnection, AgentTaskEventObserver, AgentTaskEventSource, AgentTaskInput, AgentTaskListOptions, AgentTaskTurnError, AgentTasksModule, AgentTasksWithSessions, AgentTurnResult, AgentUpdateItem, AgentWebSocket, AgentWebSocketConstructor, AgentsModule, AppColor, AppContext, AppCreateInput, AppDefinition, AppDeploy, AppDomain, AppFiles, AppGetOptions, AppListOptions, AppMember, AppPublishOptions, AppSummary, AppUpdateInput, AppVersion, AppVersionStatus, AppsModule, AuthModule, AuthenticationResult, BatchExecution, BatchStatementResult, BulkUnsubscribeResult, ColumnInput, ConnectionConfig, ConnectionTestResult, ContextModule, CopilotProvider, AgentConnection as CoreAgentConnection, AgentMessage as CoreAgentMessage, AgentModel as CoreAgentModel, AgentTaskSession as CoreAgentTaskSession, AgentTaskSessionEventMap as CoreAgentTaskSessionEventMap, AgentTaskSessionOptions as CoreAgentTaskSessionOptions, AgentTaskSessionStatus as CoreAgentTaskSessionStatus, AgentTimelineItem as CoreAgentTimelineItem, AgentToolEvent as CoreAgentToolEvent, ListTablesOptions as CoreListTablesOptions, CredentialStatus, CustomQueriesModule, CustomQueryDefinition, CustomQueryInput, CustomQuerySummary, CustomQueryUpdateInput, DataSourceBulkItemResult, DataSourceBulkResult, DataSourceCreateInput, DataSourceDbType, DataSourceDefinition, DataSourceInstanceType, DataSourceUpdateInput, DataSourcesModule, DdlStatement, DeviceAuthorization, DmlStatement, EmptyFunctionInput, EntitiesModule, EntitiesProxy, EntityListOptions, EntityTable, ExistingAgentTaskSessionOptions, FunctionBulkCreateInput, FunctionBulkDeleteInput, FunctionBulkDeleteResult, FunctionBulkPatchInput, FunctionBulkPatchItem, FunctionBulkUpdateItem, FunctionCreateInput, FunctionDefinition, FunctionExecution, FunctionListOptions, FunctionPatchInput, FunctionRuntime, FunctionSecrets, FunctionSummary, FunctionUpdateInput, FunctionVersion, FunctionVersionListOptions, FunctionVisibility, FunctionsAdminModule, FunctionsModule, ImportColumnMapping, ImportDefinition, ImportExecution, ImportExecutionListOptions, ImportInput, ImportProcessing, ImportSchedule, ImportSource, ImportTarget, ImportsModule, IntegrationAdminModule, IntegrationConnectionStatus, IntegrationCredentialRule, IntegrationExecution, IntegrationFieldSchema, IntegrationFieldSchemaInput, IntegrationLoginConfig, IntegrationModule, IntegrationProxyMode, IntegrationRequestConfig, IntegrationResource, IntegrationResourceInput, IntegrationResourceParam, IntegrationResourceSummary, IntegrationResourceUpdateInput, IntegrationResourcesModule, IntegrationTemplate, IntegrationTemplateSummary, IntegrationTemplateType, IntegrationTemplatesModule, IntegrationTokenExtraction, InviteAppUserInput, InvocationType, JsonValue, ListTemplateConfigsOptions, MembersModule, MessengerModule, NewAgentTaskSessionOptions, OAuthExchangeInput, OAuthStartResult, Page, PageOptions, PlanPrice, ProviderCredentialStatus, ProxyInput, ProxyResult, PublicFunctionAsyncResult, PublicFunctionResult, PublicFunctionsModule, QueriesModule, QueryResult, SchemaModule, SchemaScope, SchemaTables, SqlModule, TableColumn, TableDefinition, TableForeignKey, TemplateConfig, TemplateConfigBulkItemResult, TemplateConfigBulkResult, TemplateConfigCreateInput, TemplateConfigPage, TemplateConfigSummary, TemplateConfigUpdateInput, Tenant, TestCredentialsInput, User, UserPlan, WorkflowDefinition, WorkflowExecution, WorkflowInput, WorkflowSummary, WorkflowsModule } from '@mitralab.io/sdk-core';
 import * as legacy from 'mitra-sdk';
 
 type AppScopedAppsModule = AppsModule;
@@ -50,7 +50,17 @@ interface MitraClientConfig {
     dataSourceId?: string;
     /** Optional request deadline. By default, the Functions runtime owns operation time limits. */
     timeoutMs?: number;
+    /**
+     * fetch for the Mitra API calls, which carry the access token. The Agent box routes never use
+     * it: they take `globalThis.fetch`, so a fetch that adds `Authorization` cannot hand the token
+     * to the box.
+     */
     fetch?: Fetch;
+    /**
+     * WebSocket implementation for Agent sessions, such as `ws`, when the runtime has no global one.
+     * Without either, Agent sessions reach the box over HTTP.
+     */
+    WebSocket?: AgentWebSocketConstructor;
 }
 
 interface MitraClient {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { AppsModule, AppGetOptions, AppDefinition, AppUpdateInput, AppFiles, AppDeploy, AppPublishOptions, PageOptions, Page, AppVersion, SdkCore, AgentTasksWithSessions, AuthModule } from '@mitralab.io/sdk-core';
-export { AgentBulkDeleteResult, AgentConnectionCreateInput, AgentConnectionsModule, AgentCredentialsModule, AgentDefinition, AgentInput, AgentQueueItem, AgentSendAndWaitOptions, AgentSendOptions, AgentSessionTransport, AgentTask, AgentTaskCreateInput, AgentTaskEvent, AgentTaskEventConnection, AgentTaskEventObserver, AgentTaskEventSource, AgentTaskInput, AgentTaskListOptions, AgentTaskTurnError, AgentTasksModule, AgentTasksWithSessions, AgentTurnResult, AgentUpdateItem, AgentsModule, AppColor, AppContext, AppCreateInput, AppDefinition, AppDeploy, AppDomain, AppFiles, AppGetOptions, AppListOptions, AppMember, AppPublishOptions, AppSummary, AppUpdateInput, AppVersion, AppVersionStatus, AppsModule, AuthModule, AuthenticationResult, BatchExecution, BatchStatementResult, BulkUnsubscribeResult, ColumnInput, ConnectionConfig, ConnectionTestResult, ContextModule, CopilotProvider, AgentConnection as CoreAgentConnection, AgentMessage as CoreAgentMessage, AgentModel as CoreAgentModel, AgentTaskSession as CoreAgentTaskSession, AgentTaskSessionEventMap as CoreAgentTaskSessionEventMap, AgentTaskSessionOptions as CoreAgentTaskSessionOptions, AgentTaskSessionStatus as CoreAgentTaskSessionStatus, AgentTimelineItem as CoreAgentTimelineItem, AgentToolEvent as CoreAgentToolEvent, ListTablesOptions as CoreListTablesOptions, CredentialStatus, CustomQueriesModule, CustomQueryDefinition, CustomQueryInput, CustomQuerySummary, CustomQueryUpdateInput, DataSourceBulkItemResult, DataSourceBulkResult, DataSourceCreateInput, DataSourceDbType, DataSourceDefinition, DataSourceInstanceType, DataSourceUpdateInput, DataSourcesModule, DdlStatement, DeviceAuthorization, DmlStatement, EmptyFunctionInput, EntitiesModule, EntitiesProxy, EntityListOptions, EntityTable, ExistingAgentTaskSessionOptions, FunctionBulkCreateInput, FunctionBulkDeleteInput, FunctionBulkDeleteResult, FunctionBulkPatchInput, FunctionBulkPatchItem, FunctionBulkUpdateItem, FunctionCreateInput, FunctionDefinition, FunctionExecution, FunctionListOptions, FunctionPatchInput, FunctionRuntime, FunctionSecrets, FunctionSummary, FunctionUpdateInput, FunctionVersion, FunctionVersionListOptions, FunctionVisibility, FunctionsAdminModule, FunctionsModule, ImportColumnMapping, ImportDefinition, ImportExecution, ImportExecutionListOptions, ImportInput, ImportProcessing, ImportSchedule, ImportSource, ImportTarget, ImportsModule, IntegrationAdminModule, IntegrationConnectionStatus, IntegrationCredentialRule, IntegrationExecution, IntegrationFieldSchema, IntegrationFieldSchemaInput, IntegrationLoginConfig, IntegrationModule, IntegrationProxyMode, IntegrationRequestConfig, IntegrationResource, IntegrationResourceInput, IntegrationResourceParam, IntegrationResourceSummary, IntegrationResourceUpdateInput, IntegrationResourcesModule, IntegrationTemplate, IntegrationTemplateSummary, IntegrationTemplateType, IntegrationTemplatesModule, IntegrationTokenExtraction, InviteAppUserInput, InvocationType, JsonValue, ListTemplateConfigsOptions, MembersModule, MessengerModule, NewAgentTaskSessionOptions, OAuthExchangeInput, OAuthStartResult, Page, PageOptions, PlanPrice, ProviderCredentialStatus, ProxyInput, ProxyResult, PublicFunctionAsyncResult, PublicFunctionResult, PublicFunctionsModule, QueriesModule, QueryResult, SchemaModule, SchemaScope, SchemaTables, SqlModule, TableColumn, TableDefinition, TableForeignKey, TemplateConfig, TemplateConfigBulkItemResult, TemplateConfigBulkResult, TemplateConfigCreateInput, TemplateConfigPage, TemplateConfigSummary, TemplateConfigUpdateInput, Tenant, TestCredentialsInput, User, UserPlan, WorkflowDefinition, WorkflowExecution, WorkflowInput, WorkflowSummary, WorkflowsModule } from '@mitralab.io/sdk-core';
+import { AppsModule, AppGetOptions, AppDefinition, AppUpdateInput, AppFiles, AppDeploy, AppPublishOptions, PageOptions, Page, AppVersion, AgentWebSocketConstructor, SdkCore, AgentTasksWithSessions, AuthModule } from '@mitralab.io/sdk-core';
+export { AgentBulkDeleteResult, AgentConnectionCreateInput, AgentConnectionsModule, AgentCredentialsModule, AgentDefinition, AgentInput, AgentQueueItem, AgentSendAndWaitOptions, AgentSendOptions, AgentSessionTransport, AgentTask, AgentTaskCreateInput, AgentTaskEvent, AgentTaskEventConnection, AgentTaskEventObserver, AgentTaskEventSource, AgentTaskInput, AgentTaskListOptions, AgentTaskTurnError, AgentTasksModule, AgentTasksWithSessions, AgentTurnResult, AgentUpdateItem, AgentWebSocket, AgentWebSocketConstructor, AgentsModule, AppColor, AppContext, AppCreateInput, AppDefinition, AppDeploy, AppDomain, AppFiles, AppGetOptions, AppListOptions, AppMember, AppPublishOptions, AppSummary, AppUpdateInput, AppVersion, AppVersionStatus, AppsModule, AuthModule, AuthenticationResult, BatchExecution, BatchStatementResult, BulkUnsubscribeResult, ColumnInput, ConnectionConfig, ConnectionTestResult, ContextModule, CopilotProvider, AgentConnection as CoreAgentConnection, AgentMessage as CoreAgentMessage, AgentModel as CoreAgentModel, AgentTaskSession as CoreAgentTaskSession, AgentTaskSessionEventMap as CoreAgentTaskSessionEventMap, AgentTaskSessionOptions as CoreAgentTaskSessionOptions, AgentTaskSessionStatus as CoreAgentTaskSessionStatus, AgentTimelineItem as CoreAgentTimelineItem, AgentToolEvent as CoreAgentToolEvent, ListTablesOptions as CoreListTablesOptions, CredentialStatus, CustomQueriesModule, CustomQueryDefinition, CustomQueryInput, CustomQuerySummary, CustomQueryUpdateInput, DataSourceBulkItemResult, DataSourceBulkResult, DataSourceCreateInput, DataSourceDbType, DataSourceDefinition, DataSourceInstanceType, DataSourceUpdateInput, DataSourcesModule, DdlStatement, DeviceAuthorization, DmlStatement, EmptyFunctionInput, EntitiesModule, EntitiesProxy, EntityListOptions, EntityTable, ExistingAgentTaskSessionOptions, FunctionBulkCreateInput, FunctionBulkDeleteInput, FunctionBulkDeleteResult, FunctionBulkPatchInput, FunctionBulkPatchItem, FunctionBulkUpdateItem, FunctionCreateInput, FunctionDefinition, FunctionExecution, FunctionListOptions, FunctionPatchInput, FunctionRuntime, FunctionSecrets, FunctionSummary, FunctionUpdateInput, FunctionVersion, FunctionVersionListOptions, FunctionVisibility, FunctionsAdminModule, FunctionsModule, ImportColumnMapping, ImportDefinition, ImportExecution, ImportExecutionListOptions, ImportInput, ImportProcessing, ImportSchedule, ImportSource, ImportTarget, ImportsModule, IntegrationAdminModule, IntegrationConnectionStatus, IntegrationCredentialRule, IntegrationExecution, IntegrationFieldSchema, IntegrationFieldSchemaInput, IntegrationLoginConfig, IntegrationModule, IntegrationProxyMode, IntegrationRequestConfig, IntegrationResource, IntegrationResourceInput, IntegrationResourceParam, IntegrationResourceSummary, IntegrationResourceUpdateInput, IntegrationResourcesModule, IntegrationTemplate, IntegrationTemplateSummary, IntegrationTemplateType, IntegrationTemplatesModule, IntegrationTokenExtraction, InviteAppUserInput, InvocationType, JsonValue, ListTemplateConfigsOptions, MembersModule, MessengerModule, NewAgentTaskSessionOptions, OAuthExchangeInput, OAuthStartResult, Page, PageOptions, PlanPrice, ProviderCredentialStatus, ProxyInput, ProxyResult, PublicFunctionAsyncResult, PublicFunctionResult, PublicFunctionsModule, QueriesModule, QueryResult, SchemaModule, SchemaScope, SchemaTables, SqlModule, TableColumn, TableDefinition, TableForeignKey, TemplateConfig, TemplateConfigBulkItemResult, TemplateConfigBulkResult, TemplateConfigCreateInput, TemplateConfigPage, TemplateConfigSummary, TemplateConfigUpdateInput, Tenant, TestCredentialsInput, User, UserPlan, WorkflowDefinition, WorkflowExecution, WorkflowInput, WorkflowSummary, WorkflowsModule } from '@mitralab.io/sdk-core';
 import * as legacy from 'mitra-sdk';
 
 type AppScopedAppsModule = AppsModule;
@@ -50,7 +50,17 @@ interface MitraClientConfig {
     dataSourceId?: string;
     /** Optional request deadline. By default, the Functions runtime owns operation time limits. */
     timeoutMs?: number;
+    /**
+     * fetch for the Mitra API calls, which carry the access token. The Agent box routes never use
+     * it: they take `globalThis.fetch`, so a fetch that adds `Authorization` cannot hand the token
+     * to the box.
+     */
     fetch?: Fetch;
+    /**
+     * WebSocket implementation for Agent sessions, such as `ws`, when the runtime has no global one.
+     * Without either, Agent sessions reach the box over HTTP.
+     */
+    WebSocket?: AgentWebSocketConstructor;
 }
 
 interface MitraClient {

package/dist/index.js

@@ -269,12 +269,7 @@ var AgentTaskSseEventSource = class {
   constructor(config) {
     this.config = config;
   }
-  async open(taskId, observer, signal, transport) {
-    if (transport === "websocket") {
-      throw new MitraConfigurationError(
-        "WebSocket Agent sessions are not available in the Functions runtime"
-      );
-    }
+  async open(taskId, observer, signal) {
     if (signal?.aborted) throw signal.reason ?? new Error("Agent event stream was aborted");
     const controller = new AbortController();
     let handshakeTimedOut = false;
@@ -654,7 +649,8 @@ function resolveConfig(config = {}, environment = readDefaultEnvironment()) {
     appId,
     ...dataSourceId === void 0 ? {} : { dataSourceId: dataSourceId.trim() },
     ...timeoutMs === void 0 ? {} : { timeoutMs },
-    fetch: fetchImplementation
+    fetch: fetchImplementation,
+    ...config.WebSocket === void 0 ? {} : { WebSocket: config.WebSocket }
   };
 }
 
@@ -735,27 +731,28 @@ var DefaultMitraClient = class {
     this.agentConnections = core.agentConnections;
     this.agentCredentials = core.agentCredentials;
     this.agents = core.agents;
-    const agentSessionManager = createAgentTaskSessionManager({
-      tasks: core.agentTasks,
-      eventSource: new AgentTaskSseEventSource({
-        baseUrl: `${config.apiUrl}/copilot`,
-        accessToken: config.accessToken,
-        appId: config.appId,
-        ...config.timeoutMs === void 0 ? {} : { timeoutMs: config.timeoutMs },
-        fetch: config.fetch,
-        errors: coreErrors
-      })
-    });
-    this.agentTasks = withAgentTaskSessions(core.agentTasks, {
-      session: (options) => {
-        if (options.transport === "websocket") {
-          throw new MitraConfigurationError(
-            "WebSocket Agent sessions are not available in the Functions runtime; use http or auto"
-          );
+    this.agentTasks = withAgentTaskSessions(
+      core.agentTasks,
+      createAgentTaskSessionManager({
+        tasks: core.agentTasks,
+        eventSource: new AgentTaskSseEventSource({
+          baseUrl: `${config.apiUrl}/copilot`,
+          accessToken: config.accessToken,
+          appId: config.appId,
+          ...config.timeoutMs === void 0 ? {} : { timeoutMs: config.timeoutMs },
+          fetch: config.fetch,
+          errors: coreErrors
+        }),
+        // Core owns the channel to the box. Without a WebSocket, as in the Functions runtime on
+        // Node 20, `auto` reaches the box over HTTP. The box routes use the global fetch, never
+        // `config.fetch`: the grant in the channel URL is the box credential, and a custom fetch
+        // that adds `Authorization` would send the Function token to the box.
+        directChannel: {
+          apiUrl: config.apiUrl,
+          ...config.WebSocket === void 0 ? {} : { WebSocket: config.WebSocket }
         }
-        return agentSessionManager.session(options);
-      }
-    });
+      })
+    );
     this.apps = appModules.apps;
     this.auth = core.auth;
     this.context = core.context;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mitralab.io/functions-sdk",
-  "version": "0.2.3-beta.0",
+  "version": "0.2.4-beta.0",
   "description": "JavaScript and TypeScript SDK for Mitra Server Functions",
   "type": "module",
   "sideEffects": false,
@@ -67,7 +67,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@mitralab.io/sdk-core": "0.2.8-beta.0",
+    "@mitralab.io/sdk-core": "0.2.9-beta.1",
     "mitra-sdk": "1.0.63-beta.42"
   },
   "devDependencies": {