feat: support BYOC tunnel bindings for MCP requests

CHANGELOG.md

@@ -7,6 +7,8 @@ existing `0.1.0` release; earlier development prereleases are not listed.
 
 ### Added
 
+- Bind a Managed Session to a BYOC MCP tunnel with `tunnel_id` at creation. On Forward, set the tunnel on a Template for its sessions to inherit. Managed Deployments also accept and return the binding. Template and Deployment updates can replace or clear it.
+
 - Add typed Forward Session budgets across create/update responses and events, including omission, explicit null clearing and decimal-string limits.
 - Add Forward Session `config.model` overrides and model `speed` configuration, plus optional approval evaluation details, Outcome/status event fields and cumulative top-level Credits on `session.usage`.
 - Add `startup_script` to Forward/Managed Environment models and Managed cloud/self-hosted parameters. It runs on sandbox start/resume; the external worker controls self-hosted execution.

docs/api/forward/interfaces/Template.md

@@ -138,6 +138,14 @@ Template 名称。
 
 ***
 
+### tunnel\_id?
+
+> `optional` **tunnel\_id?**: `string`
+
+BYOC tunnel configured for this template, when bound.
+
+***
+
 ### type
 
 > **type**: `string`

docs/api/forward/interfaces/TemplateNewParams.md

@@ -142,6 +142,14 @@ System Prompt，最多 100,000 个字符。
 
 ***
 
+### tunnel\_id?
+
+> `optional` **tunnel\_id?**: `string`
+
+BYOC tunnel inherited by sessions created from this template.
+
+***
+
 ### vaults?
 
 > `optional` **vaults?**: `Record`\<`string`, [`ResourceBindingParam`](ResourceBindingParam.md)\> \| `null`

docs/api/forward/interfaces/TemplateUpdateParams.md

@@ -142,6 +142,14 @@ Positive maximum tool-call rounds per Turn. Omit to preserve the limit; null cle
 
 ***
 
+### tunnel\_id?
+
+> `optional` **tunnel\_id?**: `string` \| `null`
+
+Omit to keep the current tunnel, or pass null to clear the binding.
+
+***
+
 ### vaults?
 
 > `optional` **vaults?**: `Record`\<`string`, [`ResourceBindingParam`](ResourceBindingParam.md)\> \| `null`

docs/api/managed/interfaces/DeploymentNewParams.md

@@ -102,6 +102,14 @@ timezone.
 
 ***
 
+### tunnel\_id?
+
+> `optional` **tunnel\_id?**: `string`
+
+BYOC tunnel for MCP requests from sessions created by this deployment.
+
+***
+
 ### vault\_ids?
 
 > `optional` **vault\_ids?**: `string`[] \| `null`

docs/api/managed/interfaces/DeploymentUpdateParams.md

@@ -102,6 +102,14 @@ timezone.
 
 ***
 
+### tunnel\_id?
+
+> `optional` **tunnel\_id?**: `string` \| `null`
+
+Omit to preserve the tunnel binding, set an ID to replace it, or pass null to clear it.
+
+***
+
 ### vault\_ids?
 
 > `optional` **vault\_ids?**: `string`[] \| `null`

docs/api/managed/interfaces/ManagedAgentsDeployment.md

@@ -134,6 +134,14 @@ Any of "active", "paused".
 
 ***
 
+### tunnel\_id?
+
+> `optional` **tunnel\_id?**: `string`
+
+BYOC tunnel bound to this deployment, when configured.
+
+***
+
 ### type
 
 > **type**: `"deployment"`

docs/api/managed/interfaces/SessionNewParams.md

@@ -82,6 +82,14 @@ Human-readable session title.
 
 ***
 
+### tunnel\_id?
+
+> `optional` **tunnel\_id?**: `string`
+
+BYOC tunnel used for MCP requests from this session.
+
+***
+
 ### vault\_ids?
 
 > `optional` **vault\_ids?**: `string`[] \| `null`

src/forward/types.ts

@@ -2929,6 +2929,8 @@ export interface TemplateNewParams {
    * 创建 Session 时默认使用的 Environment ID。
    */
   environment_id: string;
+  /** BYOC tunnel inherited by sessions created from this template. */
+  tunnel_id?: string;
   /**
    * Template 描述，最多 2048 个字符。
    */
@@ -3026,6 +3028,8 @@ export interface TemplateUpdateParams {
    * 替换默认 Environment ID；`null` 或空字符串表示清空。
    */
   environment_id?: string | null;
+  /** Omit to keep the current tunnel, or pass null to clear the binding. */
+  tunnel_id?: string | null;
   /**
    * 整体替换默认 Vault 配置；按 Vault ID 组织，`null` 表示清空。
    */
@@ -3117,6 +3121,8 @@ export interface Template {
    * 默认 Environment ID。
    */
   environment_id: string;
+  /** BYOC tunnel configured for this template, when bound. */
+  tunnel_id?: string;
   vaults: Record<string, ResourceBinding>;
   files: Record<string, ResourceBinding>;
   github_repositories: Record<string, GitHubRepository>;

src/managed/types.ts

@@ -1578,6 +1578,8 @@ export interface ManagedAgentsDeployment {
    * ID of the `environment` where sessions run.
    */
   environment_id: string;
+  /** BYOC tunnel bound to this deployment, when configured. */
+  tunnel_id?: string;
   /**
    * Events sent to each session immediately after creation.
    */
@@ -2100,6 +2102,8 @@ export interface DeploymentNewParams {
    * created from this deployment.
    */
   environment_id: string;
+  /** BYOC tunnel for MCP requests from sessions created by this deployment. */
+  tunnel_id?: string;
   /**
    * Events to send to each session immediately after creation. At least 1,
    * maximum 50.
@@ -2167,6 +2171,8 @@ export interface DeploymentUpdateParams {
    * ID of the `environment` where sessions run. Omit to preserve. Cannot be cleared.
    */
   environment_id?: string;
+  /** Omit to preserve the tunnel binding, set an ID to replace it, or pass null to clear it. */
+  tunnel_id?: string | null;
   /**
    * Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.
    */
@@ -7262,6 +7268,8 @@ export interface SessionNewParams {
    * ID of the `environment` defining the container configuration for this session.
    */
   environment_id: string;
+  /** BYOC tunnel used for MCP requests from this session. */
+  tunnel_id?: string;
   /**
    * Human-readable session title.
    */

tests/byoc-tunnel.test.mjs

@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { testClient, response } from './helpers.mjs';
+
+test('BYOC tunnel bindings use a top-level tunnel_id', async () => {
+  let body;
+  const capture = async request => {
+    body = await request.json();
+    return response(body.tunnel_id ? { tunnel_id: body.tunnel_id } : {});
+  };
+  const managed = testClient('managed', capture);
+  const forward = testClient('forward', capture);
+  for (const binding of [{}, { tunnel_id: 'tnl_test' }]) {
+    await managed.sessions.create({ agent: 'agent_test', environment_id: 'env_test', ...binding });
+    assert.deepEqual(body, { agent: 'agent_test', environment_id: 'env_test', metadata: body.metadata, ...binding });
+    const params = { name: 'demo', model: 'auto', environment_id: 'env_test', ...binding };
+    const template = await forward.templates.create(params);
+    assert.deepEqual(body, params);
+    assert.equal(template.tunnel_id, binding.tunnel_id);
+    const deploymentParams = {
+      name: 'demo', agent: 'agent_test', environment_id: 'env_test',
+      initial_events: [{ type: 'user.message', content: [{ type: 'text', text: 'hello' }] }], ...binding,
+    };
+    const deployment = await managed.deployments.create(deploymentParams);
+    assert.deepEqual(body, deploymentParams);
+    assert.equal(deployment.tunnel_id, binding.tunnel_id);
+  }
+  for (const patch of [{}, { tunnel_id: 'tnl_other' }, { tunnel_id: null }]) {
+    await forward.templates.update('tmpl_test', patch);
+    assert.deepEqual(body, patch);
+    await managed.deployments.update('dep_test', patch);
+    assert.deepEqual(body, patch);
+  }
+});

tests/types-official-alignment.ts

@@ -52,3 +52,18 @@ const memoryVersion: Pick<M.ManagedAgentsMemory,'version'> = {version:2};
 const redactedVersion: Pick<M.ManagedAgentsMemoryVersion,'operation'|'redacted'> = {operation:'updated',redacted:true};
 const vaultCredentials: Pick<M.ManagedAgentsVault,'credentials'> = {credentials:[]};
 void [forwardBudget,sessionCreate,sessionClear,modelRead,speedRead,badBudget,badCreateModel,approval,permission,approvalReason,usageEvent,credits,outcomeIteration,budgetEvent,startupForward,startupManaged,startupSelfHosted,nestedThreadModel,nestedCoordinatorModel,memoryVersion,redactedVersion,vaultCredentials];
+
+declare const managedCreateWithTunnel: M.SessionCreateParams;
+declare const templateWithTunnel: F.Template;
+const sessionTunnel: string | undefined = managedCreateWithTunnel.tunnel_id;
+const templateTunnel: string | undefined = templateWithTunnel.tunnel_id;
+// @ts-expect-error A tunnel ID must be a string.
+const invalidTunnel: Pick<F.TemplateCreateParams, 'tunnel_id'> = { tunnel_id: 123 };
+const clearTunnel: Pick<F.TemplateUpdateParams, 'tunnel_id'> = { tunnel_id: null };
+void [sessionTunnel, templateTunnel, invalidTunnel, clearTunnel];
+declare const deploymentWithTunnel: M.ManagedAgentsDeployment;
+const deploymentTunnel: string | undefined = deploymentWithTunnel.tunnel_id;
+// @ts-expect-error Only updates can clear a deployment tunnel.
+const invalidDeploymentTunnel: Pick<M.DeploymentCreateParams, 'tunnel_id'> = { tunnel_id: null };
+const clearDeploymentTunnel: Pick<M.DeploymentUpdateParams, 'tunnel_id'> = { tunnel_id: null };
+void [deploymentTunnel, invalidDeploymentTunnel, clearDeploymentTunnel];