@gea-ai/agent-sdk 0.1.260910-alpha.0 → 0.1.260910-alpha.2

package/dist/agent-worker.js

@@ -8,6 +8,7 @@ import { trace, SpanStatusCode } from "@opentelemetry/api";
 import { agentSessionControlIdentitySchema } from "@gea-ai/contract/agent-session";
 import { agentModelCallSchema, } from "@gea-ai/contract/agent-usage";
 import { createAgentContextRuntime } from "./context-runtime.js";
+import { studioExternalUserPrincipalSchema } from "@gea-ai/contract";
 import { replaceInputFiles, withTurnImages } from "./agent-worker-attachments.js";
 import { handleHostedAgentHttp } from "./agent-http.js";
 import { MAX_AGENT_ARTIFACT_IMAGES, MAX_AGENT_ARTIFACT_IMAGE_BYTES, studioArtifactInputFileSchema, studioArtifactCreateUploadSchema, studioArtifactListSchema, } from "@gea-ai/contract/studio-artifacts";
@@ -22,17 +23,24 @@ import { createAnthropic } from "@ai-sdk/anthropic";
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { AGENT_MODEL_PROXY_PROTOCOL_VERSION, AGENT_MODEL_PROXY_TRANSPORT, agentCoreModelDescriptorSchema, decodeAgentModelProxyValue, encodeAgentModelProxyValue, } from "@gea-ai/contract/agent-model-proxy";
 import { AGENT_APPLICATION_CHAT_ID_HEADER, AGENT_APPLICATION_MESSAGE_ID_HEADER, AGENT_APPLICATION_RUN_ID_HEADER, agentApplicationKeySchema, agentApplicationRunRequestSchema, } from "@gea-ai/contract";
-import { agentSessionGetModelContextResultSchema, agentSessionAttemptIdentitySchema, agentSessionExecutionStartResultSchema, agentSessionExecutionMutationResultSchema, agentSessionPutModelContextResultSchema, } from "@gea-ai/contract/agent-session";
+import { AGENT_CHANNEL_EXECUTION_TIMEOUT_MS, agentChannelInvocationContextSchema, agentChannelAddressSchema, agentChannelHttpMessageRequestSchema, agentChannelOpaqueIdSchema, agentChannelProjectTerminalCommandSchema, agentChannelRunTerminalCallbackSchema, agentChannelStartRunCommandSchema, } from "@gea-ai/contract/agent-channels";
+import { agentSessionClaimChannelRunResultSchema, agentSessionCompleteChannelRunResultSchema, agentSessionGetMessageResultSchema, agentSessionGetModelContextResultSchema, agentSessionAttemptIdentitySchema, agentSessionExecutionStartResultSchema, agentSessionExecutionMutationResultSchema, agentSessionPutModelContextResultSchema, } from "@gea-ai/contract/agent-session";
 import { convertToModelMessages, createUIMessageStreamResponse, createUIMessageStream, asSchema, jsonSchema, stepCountIs, streamText, wrapLanguageModel, tool, } from "ai";
 import { agentWorkerConnectionDeleteOutputSchema, agentWorkerConnectionGetOutputSchema, agentWorkerConnectionSetOutputSchema, agentWorkerToolInitializationSchema, MAX_AGENT_WORKER_TOOLS, } from "@gea-ai/contract/agent-worker-tools";
 import { agentToolIdentitySchema, } from "@gea-ai/contract/agent-packages";
 import { z } from "zod";
+import { agentChannelReceiverControlSchema } from "@gea-ai/contract/agent-channel-receivers";
+export { AgentChannelReceiver } from "./agent-channel-receiver.js";
+import { agentChannelRuntimeCommandSchema, agentChannelRuntimeResolveSchema, agentChannelJsonSchema, } from "@gea-ai/contract/agent-channel-runtime";
+import { createChannelRouteContext, executeChannelBehavior, openChannelWebSocket, } from "./agent-channel-author-runtime.js";
 import { createAgentHookRuntimeDefinition, createAgentPackageSnapshot, createAgentToolRuntimeDefinition, } from "./index.js";
 import { addAgentWorkerUsage, assembleAgentWorkerContext, } from "./agent-worker-context.js";
 import { addCacheControlToMessages, addCacheControlToToolList, addCacheControlToTools, } from "./cache-control.js";
 import { agentComputerToolDefaultDescriptions } from "./computer-tools.js";
 import { createAgentSkillTool } from "./skill-tool.js";
 import { agentModelTelemetry, recordExecutionFailure, traceWorkerRequest, } from "./tracing.js";
+import { createAgentChannelStableId, } from "./agent-channel-worker.js";
+export { handleAgentChannelAddressAlarm, handleAgentChannelAddressRequest, } from "./agent-channel-worker.js";
 const HOST_PATH = "/internal/agent-worker-host/v1";
 const modelDescriptorSchema = z.union([
     agentCoreModelDescriptorSchema,
@@ -104,6 +112,20 @@ async function isPrivateAgentInvocation(environment, session) {
         control.agentKey === session.agentKey &&
         control.chatId === session.chatId);
 }
+const agentChannelPlatformIdentitySchema = agentApplicationPlatformIdentitySchema.extend({
+    channel: agentChannelInvocationContextSchema,
+});
+const agentChannelReplyMessageSchema = z
+    .object({
+    id: z.string().trim().min(1).max(256),
+    parts: z.array(z
+        .object({
+        text: z.string().optional(),
+        type: z.string().trim().min(1),
+    })
+        .passthrough()),
+})
+    .passthrough();
 function prepareAgentRuntime(entry) {
     const snapshot = createAgentPackageSnapshot(entry.definition);
     const computer = entry.definition.agent.computer;
@@ -113,6 +135,7 @@ function prepareAgentRuntime(entry) {
         ? computer.filesystem.scope
         : undefined;
     return {
+        channels: entry.definition.channels.filter((channel) => channel.provider === "custom"),
         durableObjectBindingNames: Object.keys(entry.definition.agent.durableObjects ?? {}),
         scopeResolver,
         artifactScopeResolver: entry.definition.agent.artifacts?.scope,
@@ -196,7 +219,7 @@ async function runPreparedConnectorAuthorization(input, environment) {
     });
     return Response.json({ completed: true }, { headers: { "cache-control": "no-store" } });
 }
-async function runPreparedAgent(runtime, agentKey, request, environment) {
+async function runPreparedAgent(runtime, agentKey, request, environment, identifiers) {
     const body = await request.json().catch(() => null);
     const parsed = agentApplicationRunRequestSchema.safeParse(body);
     if (!parsed.success ||
@@ -210,14 +233,18 @@ async function runPreparedAgent(runtime, agentKey, request, environment) {
         (platformIdentity.agentSession.runId !== platformIdentity.run?.id ||
             parsed.data.chatId !== platformIdentity.chat?.id))
         throw new Error("Managed Session invocation identity mismatch.");
-    const chatId = parsed.data.chatId ?? platformIdentity.chat?.id ?? crypto.randomUUID();
-    const runId = platformIdentity.run?.id ?? crypto.randomUUID();
-    const responseMessageId = platformIdentity.responseMessage?.id ??
+    const chatId = identifiers?.chatId ??
+        parsed.data.chatId ??
+        platformIdentity.chat?.id ??
+        crypto.randomUUID();
+    const runId = identifiers?.runId ?? platformIdentity.run?.id ?? crypto.randomUUID();
+    const responseMessageId = identifiers?.responseMessageId ??
+        platformIdentity.responseMessage?.id ??
         (typeof parsed.data.message !== "string" &&
             parsed.data.message.role === "assistant"
             ? parsed.data.message.id
             : crypto.randomUUID());
-    const userMessageId = crypto.randomUUID();
+    const userMessageId = identifiers?.userMessageId ?? crypto.randomUUID();
     const workerIdentity = platformIdentity.worker?.id ?? "worker";
     const identity = agentToolIdentitySchema.parse({
         agent: platformIdentity.agent ?? {
@@ -238,15 +265,17 @@ async function runPreparedAgent(runtime, agentKey, request, environment) {
         get: (id) => environment.AGENT_SESSIONS.get(id),
         idFromName: (name) => environment.AGENT_SESSIONS.idFromName(`${agentKey}:${name}`),
     };
-    let message = typeof parsed.data.message === "string"
-        ? {
-            id: userMessageId,
-            role: "user",
-            parts: [{ type: "text", text: parsed.data.message }],
-        }
-        : parsed.data.message.role === "user"
-            ? { ...parsed.data.message, id: userMessageId }
-            : parsed.data.message;
+    let message = identifiers?.message
+        ? { id: userMessageId, ...identifiers.message }
+        : typeof parsed.data.message === "string"
+            ? {
+                id: userMessageId,
+                role: "user",
+                parts: [{ type: "text", text: parsed.data.message }],
+            }
+            : parsed.data.message.role === "user"
+                ? { ...parsed.data.message, id: userMessageId }
+                : parsed.data.message;
     if (message.role === "assistant" && !platformIdentity.agentSession) {
         const resumed = await sessionNamespace
             .get(sessionNamespace.idFromName(chatId))
@@ -273,7 +302,7 @@ async function runPreparedAgent(runtime, agentKey, request, environment) {
             cacheControlProvider: null,
             chatId,
             contextArtifactRootPath: `/.gea/chats/${encodeURIComponent(chatId)}/context`,
-            currentTurn,
+            currentTurn: encodeAgentModelProxyValue(currentTurn),
             metadata: parsed.data.metadata ?? {},
             environment: {},
             instructions: runtime.instructions.trim()
@@ -318,6 +347,7 @@ async function runPreparedAgent(runtime, agentKey, request, environment) {
         context: runtime.context,
         engine: runtime.engine,
         hookRuntime: runtime.hookRuntime,
+        channelJournal: identifiers?.journal,
         request: internalRequest,
         sessionNamespace,
         sessionExecution: platformIdentity.agentSession,
@@ -545,6 +575,798 @@ export function createAgentApplicationFetch(input) {
         return new Response("Agent protocol route not found", { status: 404 });
     };
 }
+class AgentChannelTargetMismatch extends Error {
+}
+class AgentChannelInstallationDisabled extends Error {
+}
+function channelError(code, status, message, retryable = false) {
+    return Response.json({ error: { code, message, retryable } }, { headers: { "cache-control": "no-store" }, status });
+}
+function scopedAgentSessionNamespace(environment, agentKey) {
+    return {
+        get: (id) => environment.CHANNEL_SESSIONS.get(id),
+        idFromName: (name) => environment.CHANNEL_SESSIONS.idFromName(`${agentKey}:${name}`),
+    };
+}
+async function readAgentChannelIdentity(environment) {
+    return agentChannelPlatformIdentitySchema.parse(await requireHostJson(environment.IDENTITY, "/context"));
+}
+async function createChannelAddressInput(input) {
+    const context = input.identity.channel;
+    const address = {
+        agentKey: input.channel.agentKey,
+        channelKey: input.channel.channel.key,
+        environment: context.environment,
+        installationId: context.installationId,
+        providerLocalKey: input.message.conversationId,
+        principalId: input.message.principal.principalId,
+        schemaVersion: "gea.channel-address/v1",
+        studioAgentId: context.studioAgentId,
+        workspaceId: context.workspaceId,
+    };
+    const executionTarget = {
+        channelDefinitionVersion: await input.channel.definitionVersion,
+        schemaVersion: "gea.channel-execution-target/v1",
+        sessionId: await createAgentChannelStableId("session", address),
+        stateVersion: input.channel.channel.stateVersion,
+        studioAgentVersionId: context.studioAgentVersionId,
+        workerDeploymentId: context.workerDeploymentId,
+        workerId: context.workerId,
+    };
+    return { address, executionTarget };
+}
+async function forwardChannelAddressRequest(input) {
+    const addressId = await createAgentChannelStableId("address", input.address);
+    const namespace = input.environment.CHANNEL_ADDRESSES;
+    return await namespace
+        .get(namespace.idFromName(addressId))
+        .fetch(new Request(`http://channel-address.internal${input.path}`, input.init));
+}
+async function assertPinnedChannelCommand(input) {
+    const { channel: context } = input.identity;
+    const { address, executionTarget } = input.command;
+    const expectedAddressId = await createAgentChannelStableId("address", address);
+    const expectedSessionId = await createAgentChannelStableId("session", address);
+    if (context.mode !== "internal" ||
+        context.environment !== address.environment ||
+        context.agentKey !== input.channel.agentKey ||
+        context.channelKey !== input.channel.channel.key ||
+        context.installationId !== address.installationId ||
+        context.studioAgentId !== address.studioAgentId ||
+        context.workspaceId !== address.workspaceId ||
+        context.workerId !== executionTarget.workerId ||
+        context.workerDeploymentId !== executionTarget.workerDeploymentId ||
+        context.studioAgentVersionId !== executionTarget.studioAgentVersionId ||
+        input.command.addressId !== expectedAddressId ||
+        executionTarget.sessionId !== expectedSessionId ||
+        executionTarget.channelDefinitionVersion !==
+            (await input.channel.definitionVersion) ||
+        executionTarget.stateVersion !== input.channel.channel.stateVersion) {
+        throw new AgentChannelTargetMismatch("Agent Channel execution target does not match.");
+    }
+}
+async function sendChannelTerminalCallback(input) {
+    const callback = agentChannelRunTerminalCallbackSchema.parse({
+        address: input.command.address,
+        addressId: input.command.addressId,
+        commandId: await createAgentChannelStableId("callback", input.command.addressId, input.command.operationId),
+        executionTarget: input.command.executionTarget,
+        kind: "run_terminal_callback",
+        operationId: input.command.operationId,
+        protocolVersion: "gea.channel-command/v1",
+        runId: input.command.runId,
+        terminal: input.terminal,
+    });
+    const response = await forwardChannelAddressRequest({
+        address: input.command.address,
+        environment: input.environment,
+        init: {
+            body: JSON.stringify(callback),
+            headers: { "content-type": "application/json" },
+            method: "POST",
+        },
+        path: "/v1/callback",
+    });
+    if (!response.ok) {
+        throw new Error("ChannelAddress rejected the terminal callback.");
+    }
+}
+async function completeChannelRun(input) {
+    return await requestSessionJson({
+        body: {
+            commandId: input.command.commandId,
+            executionEpoch: input.executionEpoch,
+            terminal: input.terminal,
+        },
+        chatId: input.command.executionTarget.sessionId,
+        method: "POST",
+        namespace: scopedAgentSessionNamespace(input.environment, input.command.address.agentKey),
+        path: "/v1/channel-runs/complete",
+        schema: agentSessionCompleteChannelRunResultSchema,
+    });
+}
+function deferChannelTerminalCallback(context, callback) {
+    if (context === null ||
+        typeof context !== "object" ||
+        !("waitUntil" in context) ||
+        typeof context.waitUntil !== "function") {
+        throw new Error("Agent Channel execution context cannot defer work.");
+    }
+    context.waitUntil(callback());
+}
+export function extractChannelReply(messageValue, responseMessageId) {
+    const message = agentChannelReplyMessageSchema.parse(messageValue);
+    if (message.id !== responseMessageId) {
+        throw new Error("Agent Channel reply message identity does not match.");
+    }
+    let text = message.parts
+        .filter((part) => part.type === "text" && part.text !== undefined)
+        .map((part) => part.text)
+        .join("");
+    // The terminal reply is the durable delivery payload, even when the model omits a Tool's authorization link.
+    for (const part of message.parts) {
+        if (!(part.type.startsWith("tool-") || part.type === "dynamic-tool") ||
+            part.state !== "output-available")
+            continue;
+        const authorization = z
+            .object({ status: z.literal("authorization_required"), url: z.url() })
+            .safeParse(part.output);
+        if (authorization.success && !text.includes(authorization.data.url))
+            text += `${text ? "\n\n" : ""}${authorization.data.url}`;
+    }
+    return { messageId: responseMessageId, text };
+}
+async function startPinnedChannelRun(input) {
+    await assertPinnedChannelCommand(input);
+    if (input.command.input.principal.principalId !==
+        input.command.address.principalId ||
+        input.command.input.conversationId !==
+            input.command.address.providerLocalKey) {
+        throw new Error("Agent Channel conversation does not match its address.");
+    }
+    const context = input.identity.channel;
+    const executionDeadline = context.environment === "local" ? undefined : context.executionDeadline;
+    if (context.environment !== "local" &&
+        (executionDeadline === undefined ||
+            executionDeadline <= Date.now() ||
+            executionDeadline > Date.now() + AGENT_CHANNEL_EXECUTION_TIMEOUT_MS)) {
+        throw new AgentChannelTargetMismatch("A bounded production execution deadline is required.");
+    }
+    const sessionNamespace = scopedAgentSessionNamespace(input.environment, input.channel.agentKey);
+    const claim = await requestSessionJson({
+        body: {
+            allowExecution: true,
+            commandId: input.command.commandId,
+            executionEpoch: context.executionEpoch,
+            ...(executionDeadline === undefined ? {} : { executionDeadline }),
+            packageVersionId: input.command.executionTarget.studioAgentVersionId,
+            responseMessageId: input.command.responseMessageId,
+            runId: input.command.runId,
+            userMessageId: input.command.userMessageId,
+            workerDeploymentId: input.command.executionTarget.workerDeploymentId,
+        },
+        chatId: input.command.executionTarget.sessionId,
+        method: "POST",
+        namespace: sessionNamespace,
+        path: "/v1/channel-runs/claim",
+        schema: agentSessionClaimChannelRunResultSchema,
+    });
+    if (claim.action === "disabled")
+        throw new AgentChannelInstallationDisabled();
+    if (claim.action === "terminal") {
+        deferChannelTerminalCallback(input.context, async () => await sendChannelTerminalCallback({
+            command: input.command,
+            environment: input.environment,
+            terminal: claim.command.terminal,
+        }));
+        return {
+            callbackAccepted: true,
+            kind: "start_run",
+            runId: input.command.runId,
+        };
+    }
+    if (claim.action === "running") {
+        throw new Error("Agent Channel command is still running.");
+    }
+    let terminal;
+    const executionAbort = new AbortController();
+    const executionTimeout = executionDeadline === undefined
+        ? undefined
+        : setTimeout(() => executionAbort.abort(new Error("Agent Channel execution deadline exceeded.")), Math.max(0, executionDeadline - Date.now()));
+    const executionSignal = AbortSignal.any([
+        input.request.signal,
+        executionAbort.signal,
+    ]);
+    try {
+        const runResponse = await runPreparedAgent(input.channel.runtime, input.channel.agentKey, new Request(input.request.url, {
+            body: JSON.stringify({
+                chatId: input.command.executionTarget.sessionId,
+                message: input.command.input.message.text,
+            }),
+            headers: { "content-type": "application/json" },
+            method: "POST",
+            signal: executionSignal,
+        }), {
+            ...input.environment,
+            AGENT_SESSIONS: input.environment.CHANNEL_SESSIONS,
+        }, {
+            chatId: input.command.executionTarget.sessionId,
+            responseMessageId: input.command.responseMessageId,
+            runId: input.command.runId,
+            userMessageId: input.command.userMessageId,
+        });
+        if (!runResponse.ok)
+            throw new Error("Agent Run was rejected.");
+        await runResponse.arrayBuffer();
+        executionSignal.throwIfAborted();
+        const storedMessage = await requestSessionJson({
+            chatId: input.command.executionTarget.sessionId,
+            method: "GET",
+            namespace: sessionNamespace,
+            path: `/v1/messages/${encodeURIComponent(input.command.responseMessageId)}`,
+            schema: agentSessionGetMessageResultSchema,
+        });
+        terminal = {
+            reply: extractChannelReply(storedMessage.message, input.command.responseMessageId),
+            status: "succeeded",
+        };
+    }
+    catch {
+        terminal = {
+            error: {
+                code: executionAbort.signal.aborted
+                    ? "execution_deadline_exceeded"
+                    : "run_failed",
+                message: executionAbort.signal.aborted
+                    ? "Agent Channel execution exceeded its time limit."
+                    : "Agent Run failed.",
+                retryable: false,
+            },
+            status: "failed",
+        };
+    }
+    finally {
+        if (executionTimeout !== undefined)
+            clearTimeout(executionTimeout);
+    }
+    await completeChannelRun({
+        command: input.command,
+        environment: input.environment,
+        executionEpoch: context.executionEpoch,
+        terminal,
+    });
+    deferChannelTerminalCallback(input.context, async () => await sendChannelTerminalCallback({
+        command: input.command,
+        environment: input.environment,
+        terminal,
+    }));
+    return {
+        callbackAccepted: true,
+        kind: "start_run",
+        runId: input.command.runId,
+    };
+}
+async function startCustomChannelRun(input) {
+    await assertPinnedChannelCommand(input);
+    const { command, environment } = input;
+    if (command.input.principal.principalId !== command.address.principalId ||
+        command.executionEpoch !== input.identity.channel.executionEpoch ||
+        command.executionDeadline !== input.identity.channel.executionDeadline ||
+        command.executionDeadline <= Date.now() ||
+        command.executionDeadline > Date.now() + AGENT_CHANNEL_EXECUTION_TIMEOUT_MS)
+        throw new AgentChannelTargetMismatch("Channel command execution lease does not match its invocation.");
+    const namespace = scopedAgentSessionNamespace(environment, command.address.agentKey);
+    const claim = await requestSessionJson({
+        namespace,
+        chatId: command.executionTarget.sessionId,
+        path: "/v1/channel-runs/claim",
+        method: "POST",
+        schema: agentSessionClaimChannelRunResultSchema,
+        body: {
+            allowExecution: true,
+            commandId: command.commandId,
+            executionEpoch: command.executionEpoch,
+            executionDeadline: command.executionDeadline,
+            packageVersionId: command.executionTarget.studioAgentVersionId,
+            responseMessageId: command.responseMessageId,
+            runId: command.runId,
+            userMessageId: command.userMessageId,
+            workerDeploymentId: command.executionTarget.workerDeploymentId,
+        },
+    });
+    if (claim.action === "disabled")
+        throw new AgentChannelInstallationDisabled();
+    const receipt = {
+        accepted: true,
+        commandId: command.commandId,
+        executionEpoch: command.executionEpoch,
+        runId: command.runId,
+    };
+    const encoder = new TextEncoder();
+    const encode = (value) => encoder.encode(`${JSON.stringify(value)}\n`);
+    if (claim.action !== "execute")
+        return new Response(encode(receipt), {
+            headers: { "content-type": "application/x-ndjson" },
+        });
+    const journal = {
+        commandId: command.commandId,
+        executionEpoch: command.executionEpoch,
+        operationId: command.operationId,
+        runId: command.runId,
+        attempt: claim.command.attempt,
+    };
+    await appendSessionValue({
+        namespace,
+        chatId: command.executionTarget.sessionId,
+        path: "/v1/messages",
+        body: { message: { id: command.userMessageId, ...command.input.message } },
+    });
+    await appendSessionValue({
+        namespace,
+        chatId: command.executionTarget.sessionId,
+        path: "/v2/events",
+        body: {
+            ...journal,
+            id: `${command.runId}:${journal.attempt}:started`,
+            type: "run.started",
+            data: {},
+        },
+    });
+    const abort = new AbortController();
+    const timer = setTimeout(() => abort.abort(new Error("Channel execution deadline exceeded.")), Math.max(0, command.executionDeadline - Date.now()));
+    const signal = AbortSignal.any([abort.signal, input.request.signal]);
+    const body = new ReadableStream({
+        start(controller) {
+            controller.enqueue(encode(receipt));
+            // The open response owns this invocation through completion. The Host drains it
+            // independently after returning the first, durably accepted receipt to AddressDO.
+            const execute = async () => {
+                let terminal;
+                try {
+                    const response = await runPreparedAgent(input.channel.runtime, input.channel.agentKey, new Request(input.request.url, {
+                        method: "POST",
+                        headers: { "content-type": "application/json" },
+                        body: JSON.stringify({
+                            chatId: command.executionTarget.sessionId,
+                            message: "Channel input",
+                        }),
+                        signal,
+                    }), { ...environment, AGENT_SESSIONS: environment.CHANNEL_SESSIONS }, {
+                        chatId: command.executionTarget.sessionId,
+                        responseMessageId: command.responseMessageId,
+                        runId: command.runId,
+                        userMessageId: command.userMessageId,
+                        message: command.input.message,
+                        journal,
+                    });
+                    if (!response.ok)
+                        throw new Error("Agent execution was rejected.");
+                    // Drain, rather than buffer, the model's potentially long stream.
+                    const reader = response.body?.getReader();
+                    if (reader)
+                        try {
+                            while (!(await reader.read()).done)
+                                signal.throwIfAborted();
+                        }
+                        finally {
+                            reader.releaseLock();
+                        }
+                    signal.throwIfAborted();
+                    const stored = await requestSessionJson({
+                        namespace,
+                        chatId: command.executionTarget.sessionId,
+                        path: `/v1/messages/${encodeURIComponent(command.responseMessageId)}`,
+                        method: "GET",
+                        schema: agentSessionGetMessageResultSchema,
+                    });
+                    terminal = {
+                        status: "succeeded",
+                        reply: extractChannelReply(stored.message, command.responseMessageId),
+                    };
+                }
+                catch {
+                    terminal = {
+                        status: "failed",
+                        error: {
+                            code: signal.aborted
+                                ? "execution_deadline_exceeded"
+                                : "run_failed",
+                            message: signal.aborted
+                                ? "Channel execution exceeded its deadline."
+                                : "Agent execution failed.",
+                            retryable: false,
+                        },
+                    };
+                }
+                await requestSessionJson({
+                    namespace,
+                    chatId: command.executionTarget.sessionId,
+                    path: "/v2/channel-runs/complete",
+                    method: "POST",
+                    schema: agentSessionCompleteChannelRunResultSchema,
+                    body: {
+                        commandId: command.commandId,
+                        executionEpoch: command.executionEpoch,
+                        terminal,
+                        event: {
+                            ...journal,
+                            id: `${command.runId}:${journal.attempt}:terminal`,
+                            type: terminal.status === "succeeded"
+                                ? "run.succeeded"
+                                : "run.failed",
+                            data: terminal.status === "succeeded"
+                                ? { reply: terminal.reply }
+                                : { error: terminal.error },
+                        },
+                    },
+                });
+                clearTimeout(timer);
+                await forwardChannelAddressRequest({
+                    address: command.address,
+                    environment,
+                    path: "/v2/wake",
+                    init: { method: "POST" },
+                });
+                controller.enqueue(encode({ terminal }));
+                controller.close();
+            };
+            void execute().catch((error) => {
+                clearTimeout(timer);
+                controller.error(error);
+            });
+        },
+        cancel() {
+            abort.abort(new Error("Execution host disconnected."));
+            clearTimeout(timer);
+        },
+    });
+    return new Response(body, {
+        headers: {
+            "content-type": "application/x-ndjson",
+            "cache-control": "no-store",
+        },
+    });
+}
+/**
+ * Creates file-authored Channels and the exact-executionTarget internal protocol.
+ * Channels belong to each Main Agent's composed package.
+ */
+export function createAgentChannelApplicationFetch(input) {
+    const channels = Object.entries(input.agents)
+        .flatMap(([agentKey, definition]) => {
+        const runtime = prepareAgentRuntime(definition);
+        return runtime.snapshot.channels.map((channel) => ({
+            agentKey,
+            channel,
+            definitionVersion: createAgentChannelStableId("definition", channel),
+            runtime,
+        }));
+    })
+        .sort((left, right) => left.channel.path.localeCompare(right.channel.path));
+    return async (request, environment, context) => {
+        const url = new URL(request.url);
+        if (url.pathname === "/_gea/channels/v3/receiver") {
+            if (request.method !== "POST")
+                return channelError("invalid_request", 405, "POST is required.");
+            try {
+                const control = agentChannelReceiverControlSchema.parse(await request.json());
+                const identity = await readAgentChannelIdentity(environment);
+                if (identity.channel.mode !== "internal" ||
+                    identity.channel.installationId !== control.installationId ||
+                    identity.channel.agentKey !== control.agentKey ||
+                    identity.channel.channelKey !== control.channelKey)
+                    return channelError("forbidden", 403, "Receiver control identity does not match.");
+                if (!environment.CHANNEL_RECEIVERS)
+                    return channelError("unsupported_capability", 503, "Managed receivers are unavailable.");
+                const name = await createAgentChannelStableId("receiver", control.installationId);
+                return await environment.CHANNEL_RECEIVERS.get(environment.CHANNEL_RECEIVERS.idFromName(name)).fetch(new Request("http://receiver/control", {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify(control),
+                }));
+            }
+            catch {
+                return channelError("invalid_receiver_control", 403, "Receiver control was rejected.");
+            }
+        }
+        if (url.pathname.startsWith("/_gea/channels/v2/")) {
+            if (request.method !== "POST")
+                return channelError("invalid_request", 405, "POST is required.");
+            try {
+                const identity = await readAgentChannelIdentity(environment);
+                if (url.pathname === "/_gea/channels/v2/address") {
+                    const body = z
+                        .object({
+                        address: agentChannelAddressSchema,
+                        path: z.string(),
+                        body: z.unknown().optional(),
+                    })
+                        .strict()
+                        .parse(await request.json());
+                    const trusted = identity.channel;
+                    if (trusted.mode !== "internal" ||
+                        trusted.installationId !== body.address.installationId ||
+                        trusted.agentKey !== body.address.agentKey ||
+                        trusted.channelKey !== body.address.channelKey ||
+                        trusted.workspaceId !== body.address.workspaceId ||
+                        trusted.studioAgentId !== body.address.studioAgentId ||
+                        trusted.environment !== body.address.environment)
+                        throw new AgentChannelTargetMismatch();
+                    const addressUrl = new URL(body.path, "http://channel-address.internal");
+                    if (addressUrl.origin !== "http://channel-address.internal" ||
+                        addressUrl.hash ||
+                        (addressUrl.pathname !== "/v2/deliveries" &&
+                            addressUrl.pathname !== "/v2/deliveries/resolve" &&
+                            !/^\/v2\/(operations|status)\/[A-Za-z0-9._~-]+$/u.test(addressUrl.pathname)))
+                        return channelError("invalid_request", 400, "Unsupported address operation.");
+                    const operation = addressUrl.pathname === "/v2/deliveries/resolve"
+                        ? agentChannelRuntimeResolveSchema.parse(body.body)
+                        : undefined;
+                    return await forwardChannelAddressRequest({
+                        address: body.address,
+                        environment,
+                        path: `${addressUrl.pathname}${addressUrl.search}`,
+                        ...(operation
+                            ? {
+                                init: {
+                                    method: "POST",
+                                    headers: { "content-type": "application/json" },
+                                    body: JSON.stringify(operation),
+                                },
+                            }
+                            : {}),
+                    });
+                }
+                const command = agentChannelRuntimeCommandSchema.parse(await request.json());
+                if (url.pathname !== `/_gea/channels/v2/${command.kind}`)
+                    return channelError("invalid_request", 400, "Channel command path mismatch.");
+                const channel = channels.find((entry) => entry.agentKey === command.address.agentKey &&
+                    entry.channel.key === command.address.channelKey &&
+                    entry.channel.provider === "custom");
+                if (!channel)
+                    return channelError("invalid_request", 404, "Custom Channel not found.");
+                await assertPinnedChannelCommand({ channel, command, identity });
+                if (command.kind === "start_run")
+                    return await startCustomChannelRun({
+                        channel,
+                        command,
+                        identity,
+                        environment,
+                        request,
+                    });
+                const definition = channel.runtime.channels.find((entry) => entry.key === channel.channel.key);
+                return Response.json(await executeChannelBehavior({
+                    definition,
+                    command,
+                    environment,
+                    signal: request.signal,
+                }));
+            }
+            catch (error) {
+                if (error instanceof z.ZodError || error instanceof SyntaxError)
+                    return channelError("invalid_request", 400, "Invalid Channel command.");
+                if (error instanceof AgentChannelTargetMismatch)
+                    return channelError("channel_execution_target_mismatch", 403, "Channel execution target does not match.");
+                if (error instanceof AgentChannelInstallationDisabled)
+                    return channelError("installation_disabled", 403, "Channel installation is disabled.");
+                return channelError("channel_command_failed", 503, "Channel command execution failed.", true);
+            }
+        }
+        const internalPath = url.pathname.startsWith("/_gea/channels/v1/")
+            ? url.pathname.slice("/_gea/channels/v1/".length)
+            : null;
+        if (internalPath !== null) {
+            if (request.method !== "POST") {
+                return new Response("Method Not Allowed", {
+                    headers: { allow: "POST" },
+                    status: 405,
+                });
+            }
+            try {
+                const identity = await readAgentChannelIdentity(environment);
+                const body = await request.json();
+                if (internalPath === "start") {
+                    const command = agentChannelStartRunCommandSchema.parse(body);
+                    const channel = channels.find((entry) => entry.agentKey === command.address.agentKey &&
+                        entry.channel.key === command.address.channelKey);
+                    if (!channel)
+                        return channelError("invalid_request", 404, "Channel not found.");
+                    return Response.json(await startPinnedChannelRun({
+                        channel,
+                        command,
+                        context,
+                        environment,
+                        identity,
+                        request,
+                    }));
+                }
+                if (internalPath === "project") {
+                    const command = agentChannelProjectTerminalCommandSchema.parse(body);
+                    const channel = channels.find((entry) => entry.agentKey === command.address.agentKey &&
+                        entry.channel.key === command.address.channelKey);
+                    if (!channel)
+                        return channelError("invalid_request", 404, "Channel not found.");
+                    await assertPinnedChannelCommand({ channel, command, identity });
+                    return Response.json({
+                        kind: "project_terminal",
+                        runId: command.runId,
+                        terminal: command.terminal,
+                    });
+                }
+                if (internalPath === "callback") {
+                    const command = agentChannelRunTerminalCallbackSchema.parse(body);
+                    const channel = channels.find((entry) => entry.agentKey === command.address.agentKey &&
+                        entry.channel.key === command.address.channelKey);
+                    if (!channel)
+                        return channelError("invalid_request", 404, "Channel not found.");
+                    await assertPinnedChannelCommand({ channel, command, identity });
+                    const response = await forwardChannelAddressRequest({
+                        address: command.address,
+                        environment,
+                        init: {
+                            body: JSON.stringify(command),
+                            headers: { "content-type": "application/json" },
+                            method: "POST",
+                        },
+                        path: "/v1/callback",
+                    });
+                    return new Response(response.body, response);
+                }
+                return channelError("invalid_request", 404, "Internal Channel route not found.");
+            }
+            catch (error) {
+                if (error instanceof AgentChannelInstallationDisabled) {
+                    return channelError("installation_disabled", 403, "The Channel installation is disabled.");
+                }
+                if (error instanceof z.ZodError || error instanceof SyntaxError) {
+                    return channelError("invalid_request", 400, "Invalid Channel request.");
+                }
+                return error instanceof AgentChannelTargetMismatch
+                    ? channelError("channel_execution_target_mismatch", 403, "Channel execution target does not match.")
+                    : channelError("run_failed", 503, "Channel command execution failed and will be retried.", true);
+            }
+        }
+        const channel = channels.find((entry) => url.pathname === entry.channel.path ||
+            url.pathname.startsWith(`${entry.channel.path}/`));
+        if (!channel)
+            return undefined;
+        if (channel.channel.provider === "http" &&
+            !["GET", "HEAD", "OPTIONS", "POST"].includes(request.method)) {
+            return undefined;
+        }
+        let identity;
+        try {
+            identity = await readAgentChannelIdentity(environment);
+        }
+        catch {
+            return channelError("unauthorized_installation", 401, "A valid Channel installation is required.");
+        }
+        if (identity.channel.mode !== "ingress" ||
+            identity.channel.agentKey !== channel.agentKey ||
+            identity.channel.channelKey !== channel.channel.key) {
+            return channelError("unauthorized_installation", 403, "The Channel installation does not own this route.");
+        }
+        const relativePath = url.pathname.slice(channel.channel.path.length);
+        if (channel.channel.provider === "custom") {
+            if (identity.channel.installationStatus === "retired" ||
+                (identity.channel.installationStatus === "disabled" &&
+                    request.headers.get("upgrade")?.toLowerCase() === "websocket"))
+                return channelError("installation_disabled", 403, "Channel installation is unavailable.");
+            const definition = channel.runtime.channels.find((entry) => entry.key === channel.channel.key);
+            const isSocket = request.headers.get("upgrade")?.toLowerCase() === "websocket";
+            const route = definition.routes.find((entry) => entry.path === (relativePath || "/") &&
+                entry.method === (isSocket ? "WS" : request.method));
+            if (!route)
+                return channelError("route_not_found", 404, "Channel route not found.");
+            const abort = new AbortController();
+            try {
+                const authorContext = await createChannelRouteContext({
+                    definition,
+                    environment,
+                    identity: identity.channel,
+                    signal: isSocket ? abort.signal : request.signal,
+                    request,
+                });
+                return route.method === "WS"
+                    ? await openChannelWebSocket(route, request, authorContext, abort, environment)
+                    : await route.handler(request, authorContext);
+            }
+            catch (error) {
+                abort.abort();
+                console.error("Channel route callback failed", {
+                    channelKey: channel.channel.key,
+                    error: error instanceof Error &&
+                        /^(Channel capability|Channel address|Channel session)/u.test(error.message)
+                        ? error.message
+                        : error instanceof Error
+                            ? error.name
+                            : "unknown",
+                });
+                return channelError("channel_handler_failed", error instanceof z.ZodError ? 400 : 503, "Channel handler failed.");
+            }
+        }
+        if (relativePath === "/v1/messages") {
+            if (request.method !== "POST") {
+                return new Response("Method Not Allowed", {
+                    headers: { allow: "POST" },
+                    status: 405,
+                });
+            }
+            if (identity.channel.installationStatus === "disabled") {
+                return channelError("installation_disabled", 403, "The Channel installation is disabled.");
+            }
+            if (identity.channel.installationStatus === "retired") {
+                return channelError("installation_retired", 410, "The Channel installation is retired.");
+            }
+            try {
+                const message = agentChannelHttpMessageRequestSchema.parse(await request.json());
+                const target = await createChannelAddressInput({
+                    channel,
+                    identity,
+                    message,
+                });
+                const response = await forwardChannelAddressRequest({
+                    address: target.address,
+                    environment,
+                    init: {
+                        body: JSON.stringify({
+                            ...target,
+                            channelPath: channel.channel.path,
+                            input: message,
+                        }),
+                        headers: { "content-type": "application/json" },
+                        method: "POST",
+                    },
+                    path: "/v1/ingress",
+                });
+                return new Response(response.body, response);
+            }
+            catch (error) {
+                if (error instanceof z.ZodError || error instanceof SyntaxError) {
+                    return channelError("invalid_request", 400, "Invalid Channel request.");
+                }
+                throw error;
+            }
+        }
+        const statusSegments = relativePath.split("/").filter(Boolean);
+        if (request.method === "GET" &&
+            statusSegments.length === 5 &&
+            statusSegments[0] === "v1" &&
+            statusSegments[1] === "conversations" &&
+            statusSegments[3] === "operations") {
+            try {
+                const conversationId = agentChannelOpaqueIdSchema.parse(decodeURIComponent(statusSegments[2]));
+                const operationId = agentChannelOpaqueIdSchema.parse(decodeURIComponent(statusSegments[4]));
+                const target = await createChannelAddressInput({
+                    channel,
+                    identity,
+                    message: {
+                        conversationId,
+                        principal: studioExternalUserPrincipalSchema.parse({
+                            principalType: "user",
+                            principalId: new URL(request.url).searchParams.get("principalId"),
+                        }),
+                        message: { text: "status", type: "text" },
+                        operationId,
+                    },
+                });
+                const response = await forwardChannelAddressRequest({
+                    address: target.address,
+                    environment,
+                    path: `/v1/operations/${encodeURIComponent(operationId)}`,
+                });
+                return new Response(response.body, response);
+            }
+            catch (error) {
+                if (error instanceof z.ZodError || error instanceof URIError) {
+                    return channelError("invalid_request", 400, "Invalid Channel request.");
+                }
+                throw error;
+            }
+        }
+        return channelError("not_found", 404, "Channel route not found.");
+    };
+}
 function createAgentWorkerHostAdapter(bindings) {
     return {
         async fetch(path, init) {
@@ -1943,8 +2765,6 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer) {
     }
     const payload = runRequestSchema.parse(await input.request.json());
     const sessionExecution = input.sessionExecution;
-    if (input.snapshot.engine !== input.engine?.kind)
-        throw new Error("Agent engine binding does not match its immutable snapshot.");
     let mutationSequence = 1;
     let writeTail = Promise.resolve();
     let writeFailure;
@@ -2384,8 +3204,9 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer) {
         ? undefined
         : await createGeaAI(host, configuredModel, payload.requestOptions?.extraBody, { kind: "agent-dev", packageName: input.snapshot.name });
     const modelMessages = replaceInputFiles(await convertToModelMessages(payload.originalMessages), inputFiles);
-    const runtimeContext = payload.runtimeContext;
-    let currentTurn = payload.currentTurn;
+    // Model file parts can contain URL and byte values that ordinary JSON cannot preserve.
+    const runtimeContext = decodeAgentModelProxyValue(payload.runtimeContext);
+    let currentTurn = decodeAgentModelProxyValue(payload.currentTurn);
     const storedContext = await requestSessionJson({
         chatId: payload.chatId,
         method: "GET",
@@ -2411,15 +3232,14 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer) {
             contextSize: storedContext.context.contextSize,
             messages: (input.engine && storedContext.context.metadata.agentCore) ||
                 storedContext.context.runId === payload.runId
-                ? storedContext.context.messages
+                ? storedContext.context.messages.map(decodeAgentModelProxyValue)
                 : currentTurn.length > 0
                     ? [
-                        ...storedContext.context.messages,
+                        ...storedContext.context.messages.map(decodeAgentModelProxyValue),
                         ...currentTurn,
                     ]
                     : replaceLastAssistantInteraction({
-                        managedMessages: storedContext.context
-                            .messages,
+                        managedMessages: storedContext.context.messages.map(decodeAgentModelProxyValue),
                         modelMessages,
                     }),
             metadata: structuredClone(storedContext.context.metadata),
@@ -2525,7 +3345,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer) {
     const persistModelContext = async () => {
         const modelContext = {
             contextSize: context.contextSize,
-            messages: context.messages,
+            messages: context.messages.map(encodeAgentModelProxyValue),
             metadata: context.metadata,
             runId: payload.runId,
         };
@@ -2744,6 +3564,18 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer) {
         if (failure)
             throw failure.error;
         await persistModelContext();
+        if (input.channelJournal)
+            await appendSessionValue({
+                body: {
+                    ...input.channelJournal,
+                    id: `${input.channelJournal.runId}:${input.channelJournal.attempt}:message`,
+                    type: "message.completed",
+                    data: agentChannelJsonSchema.parse(JSON.parse(JSON.stringify({ message: responseMessage }))),
+                },
+                chatId: payload.chatId,
+                namespace: input.sessionNamespace,
+                path: "/v2/events",
+            });
     };
     const coreUsage = (value) => {
         const usage = value == null ? null : agentCoreUsageSchema.parse(value);
@@ -3156,6 +3988,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer) {
         // abort callbacks and model/tool spans settle before request teardown.
         waitUntil(result.consumeStream({ onError: fail }).then(() => finishContext()));
     }
+    let channelEventSequence = 0;
     const durableStream = stream.pipeThrough(new TransformStream({
         async transform(chunk, controller) {
             // AI SDK emits finish before awaiting onEnd. Publish success and usage
@@ -3174,10 +4007,17 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer) {
                 return;
             }
             await appendSessionValue({
-                body: { event: chunk },
+                body: input.channelJournal
+                    ? {
+                        ...input.channelJournal,
+                        id: `${input.channelJournal.runId}:${input.channelJournal.attempt}:${++channelEventSequence}`,
+                        type: chunk.type,
+                        data: agentChannelJsonSchema.parse(JSON.parse(JSON.stringify(chunk))),
+                    }
+                    : { event: chunk },
                 chatId: payload.chatId,
                 namespace: input.sessionNamespace,
-                path: "/v1/events",
+                path: input.channelJournal ? "/v2/events" : "/v1/events",
             });
             controller.enqueue(chunk);
         },