@copilotkit/channels-core 0.4.1-canary.perfall1 → 0.5.0

package/README.md

@@ -68,11 +68,8 @@ handler:
 ```ts
 import { createChannel } from "@copilotkit/channels-core";
 import { slack } from "@copilotkit/channels-slack";
-import {
-  CopilotRuntime,
-  CopilotKitIntelligence,
-  createCopilotRuntimeHandler,
-} from "@copilotkit/runtime/v2";
+import { CopilotRuntime, CopilotKitIntelligence } from "@copilotkit/runtime/v2";
+import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";
 
 const channel = createChannel({
   name: "support-bot", // project-unique Intelligence Channel name
@@ -89,9 +86,11 @@ const runtime = new CopilotRuntime({
   channels: [channel],
 });
 
-const handler = createCopilotRuntimeHandler({ runtime });
-await handler.channels.ready(); // starts every declared channel
-// await handler.channels.stop(); // tears them down
+// Creating the listener starts every declared channel's connection.
+const listener = createCopilotNodeListener({ runtime });
+// Optional: await that activation so a broken config fails startup loudly.
+await listener.channels.ready();
+// await listener.channels.stop(); // tears them down
 ```
 
 ## `Thread`

package/dist/canonical-run-loop.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=canonical-run-loop.test.d.ts.map

package/dist/canonical-run-loop.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-run-loop.test.d.ts","sourceRoot":"","sources":["../src/canonical-run-loop.test.ts"],"names":[],"mappings":""}

package/dist/canonical-run-loop.test.js

@@ -0,0 +1,453 @@
+import { EventType } from "@ag-ui/client";
+import { expect, test } from "vitest";
+import { z } from "zod";
+import { runAgentLoop } from "./run-loop.js";
+import { ChannelDeliveryTerminatedError } from "./delivery-error.js";
+import { FakeAgent } from "./testing/fake-agent.js";
+const canonicalRun = {
+    threadId: "canonical-thread",
+    runId: "canonical-run",
+};
+function lifecycleBatch(runId, middle) {
+    return [
+        {
+            type: EventType.RUN_STARTED,
+            threadId: "inner-thread",
+            runId,
+        },
+        ...middle,
+        {
+            type: EventType.RUN_FINISHED,
+            threadId: "inner-thread",
+            runId,
+        },
+    ];
+}
+function textEvent(messageId, text) {
+    return {
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId,
+        delta: text,
+    };
+}
+async function emitBatch(subscriber, agent, runId, middle) {
+    const input = {
+        threadId: agent.threadId,
+        runId,
+        messages: agent.messages,
+        state: agent.state,
+        tools: [],
+        context: [],
+        forwardedProps: {},
+    };
+    const params = {
+        messages: agent.messages,
+        state: agent.state,
+        agent,
+        input,
+    };
+    for (const event of lifecycleBatch(runId, middle)) {
+        await subscriber.onEvent?.({ ...params, event });
+        switch (event.type) {
+            case EventType.RUN_STARTED:
+                await subscriber.onRunStartedEvent?.({ ...params, event });
+                break;
+            case EventType.RUN_FINISHED:
+                await subscriber.onRunFinishedEvent?.({
+                    ...params,
+                    event,
+                    outcome: "success",
+                });
+                break;
+            case EventType.RUN_ERROR:
+                await subscriber.onRunErrorEvent?.({ ...params, event });
+                break;
+            case EventType.TEXT_MESSAGE_CONTENT:
+                await subscriber.onTextMessageContentEvent?.({
+                    ...params,
+                    event,
+                    textMessageBuffer: event.delta,
+                });
+                break;
+            case EventType.TOOL_CALL_END:
+                await subscriber.onToolCallEndEvent?.({
+                    ...params,
+                    event,
+                    toolCallName: "echo",
+                    toolCallArgs: { value: "ok" },
+                });
+                break;
+        }
+    }
+}
+function setupRenderer(options = {}) {
+    const renderedEvents = [];
+    const renderedFinishMetadata = [];
+    const toolCalls = [];
+    const subscriber = {
+        onRunStartedEvent: ({ event }) => {
+            renderedEvents.push(event);
+        },
+        onRunFinishedEvent: ({ event }) => {
+            renderedEvents.push(event);
+            renderedFinishMetadata.push(event.metadata);
+            if (options.failOnFinish) {
+                throw new Error("renderer finalization failed");
+            }
+        },
+        onRunErrorEvent: ({ event }) => {
+            renderedEvents.push(event);
+        },
+        onTextMessageContentEvent: ({ event }) => {
+            renderedEvents.push(event);
+            if (options.failOnContent) {
+                throw new Error("renderer failed");
+            }
+        },
+        onToolCallEndEvent: ({ event, toolCallName, toolCallArgs }) => {
+            toolCalls.push({
+                toolCallId: event.toolCallId,
+                toolCallName,
+                toolCallArgs,
+            });
+        },
+    };
+    return {
+        renderer: {
+            subscriber,
+            markInterrupted: async () => { },
+            getCapturedToolCalls: () => toolCalls,
+            getPendingInterrupt: () => undefined,
+            clearPendingInterrupt: () => { },
+        },
+        renderedEvents,
+        renderedFinishMetadata,
+    };
+}
+test("managed runAgentLoop emits one canonical lifecycle and shares stamped events with ingestion and rendering", async () => {
+    let agent;
+    agent = new FakeAgent([
+        (subscriber) => emitBatch(subscriber, agent, "inner-run-1", [
+            textEvent("message-1", "first"),
+            {
+                type: EventType.TOOL_CALL_END,
+                toolCallId: "tool-call-1",
+            },
+        ]),
+        (subscriber) => emitBatch(subscriber, agent, "inner-run-2", [
+            textEvent("message-2", "second"),
+        ]),
+    ]);
+    const { renderer, renderedEvents } = setupRenderer();
+    const ingestedEvents = [];
+    let commits = 0;
+    const echo = {
+        name: "echo",
+        description: "Return the value.",
+        parameters: z.object({ value: z.string() }),
+        handler: ({ value }) => value,
+    };
+    const result = await runAgentLoop({
+        agent,
+        renderer,
+        tools: new Map([["echo", echo]]),
+        toolDescriptors: [],
+        context: [],
+        makeToolCtx: () => {
+            throw new Error("tool context is not used by this test");
+        },
+        subscriber: {
+            onEvent: ({ event }) => {
+                ingestedEvents.push(event);
+            },
+        },
+        canonicalRun: {
+            ...canonicalRun,
+            beforeToolCall: async () => {
+                commits += 1;
+            },
+        },
+    });
+    const lifecycleTypes = ingestedEvents
+        .filter(({ type }) => type === EventType.RUN_STARTED ||
+        type === EventType.RUN_FINISHED ||
+        type === EventType.RUN_ERROR)
+        .map(({ type }) => type);
+    const ingestedContent = ingestedEvents.filter(({ type }) => type === EventType.TEXT_MESSAGE_CONTENT);
+    const renderedContent = renderedEvents.filter(({ type }) => type === EventType.TEXT_MESSAGE_CONTENT);
+    expect(result).toEqual({ iterations: 2, interrupted: false });
+    expect(commits).toBe(1);
+    expect(lifecycleTypes).toEqual([
+        EventType.RUN_STARTED,
+        EventType.RUN_FINISHED,
+    ]);
+    expect(renderedEvents
+        .filter(({ type }) => type === EventType.RUN_STARTED ||
+        type === EventType.RUN_FINISHED ||
+        type === EventType.RUN_ERROR)
+        .map(({ type }) => type)).toEqual([EventType.RUN_STARTED, EventType.RUN_FINISHED]);
+    expect(ingestedContent).toHaveLength(2);
+    expect(renderedContent).toHaveLength(2);
+    expect(renderedContent[0]).toBe(ingestedContent[0]);
+    expect(renderedContent[1]).toBe(ingestedContent[1]);
+    expect(ingestedEvents).toEqual(expect.arrayContaining([
+        expect.objectContaining(canonicalRun),
+        expect.objectContaining({
+            ...canonicalRun,
+            type: EventType.TEXT_MESSAGE_CONTENT,
+            messageId: "message-1",
+        }),
+        expect.objectContaining({
+            ...canonicalRun,
+            type: EventType.TEXT_MESSAGE_CONTENT,
+            messageId: "message-2",
+        }),
+    ]));
+});
+test("managed renderer failure is deferred until canonical RUN_FINISHED reaches ingestion", async () => {
+    let agent;
+    agent = new FakeAgent([
+        (subscriber) => emitBatch(subscriber, agent, "inner-run", [
+            textEvent("message-1", "hello"),
+        ]),
+    ]);
+    const { renderer } = setupRenderer({ failOnContent: true });
+    const ingestedByTypedCallback = [];
+    const ingestedLifecycle = [];
+    const result = await runAgentLoop({
+        agent,
+        renderer,
+        tools: new Map(),
+        toolDescriptors: [],
+        context: [],
+        makeToolCtx: () => {
+            throw new Error("no tool calls are expected");
+        },
+        subscriber: {
+            onEvent: ({ event }) => {
+                if (event.type === EventType.RUN_STARTED ||
+                    event.type === EventType.RUN_FINISHED ||
+                    event.type === EventType.RUN_ERROR) {
+                    ingestedLifecycle.push(event);
+                }
+            },
+            onTextMessageContentEvent: ({ event }) => {
+                ingestedByTypedCallback.push(event);
+            },
+        },
+        canonicalRun,
+    });
+    expect(result).toMatchObject({
+        iterations: 1,
+        interrupted: false,
+        deliveryError: { message: "renderer failed" },
+    });
+    expect(ingestedByTypedCallback).toEqual([
+        expect.objectContaining({
+            ...canonicalRun,
+            type: EventType.TEXT_MESSAGE_CONTENT,
+            messageId: "message-1",
+        }),
+    ]);
+    expect(ingestedLifecycle.map(({ type }) => type)).toEqual([
+        EventType.RUN_STARTED,
+        EventType.RUN_FINISHED,
+    ]);
+});
+test("managed renderer failure freezes later rendering while canonical ingestion finishes", async () => {
+    let agent;
+    agent = new FakeAgent([
+        (subscriber) => emitBatch(subscriber, agent, "inner-run", [
+            textEvent("message-1", "first"),
+            textEvent("message-2", "second"),
+        ]),
+    ]);
+    const { renderer, renderedEvents } = setupRenderer({
+        failOnContent: true,
+    });
+    const ingestedEvents = [];
+    const result = await runAgentLoop({
+        agent,
+        renderer,
+        tools: new Map(),
+        toolDescriptors: [],
+        context: [],
+        makeToolCtx: () => {
+            throw new Error("no tool calls are expected");
+        },
+        subscriber: {
+            onEvent: ({ event }) => {
+                ingestedEvents.push(event);
+            },
+        },
+        canonicalRun,
+    });
+    expect(result).toMatchObject({
+        deliveryError: { message: "renderer failed" },
+    });
+    expect(renderedEvents.map(({ type, ...event }) => ({
+        type,
+        messageId: "messageId" in event ? event.messageId : undefined,
+    }))).toEqual([
+        { type: EventType.RUN_STARTED, messageId: undefined },
+        { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "message-1" },
+    ]);
+    expect(ingestedEvents
+        .filter(({ type }) => type === EventType.TEXT_MESSAGE_CONTENT ||
+        type === EventType.RUN_FINISHED)
+        .map(({ type, ...event }) => ({
+        type,
+        messageId: "messageId" in event ? event.messageId : undefined,
+    }))).toEqual([
+        { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "message-1" },
+        { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "message-2" },
+        { type: EventType.RUN_FINISHED, messageId: undefined },
+    ]);
+});
+test("terminal delivery tool failure stops the loop and closes renderer fanout", async () => {
+    const deliveryError = new ChannelDeliveryTerminatedError("provider delivery timed out");
+    let agent;
+    agent = new FakeAgent([
+        (subscriber) => emitBatch(subscriber, agent, "inner-run-1", [
+            {
+                type: EventType.TOOL_CALL_END,
+                toolCallId: "tool-call-1",
+            },
+        ]),
+        (subscriber) => emitBatch(subscriber, agent, "inner-run-2", [
+            textEvent("message-after-failure", "should not render"),
+        ]),
+    ]);
+    const { renderer, renderedEvents } = setupRenderer();
+    const ingestedEvents = [];
+    const postFile = {
+        name: "echo",
+        description: "Post a managed file.",
+        parameters: z.object({ value: z.string() }),
+        handler: () => {
+            throw deliveryError;
+        },
+    };
+    await expect(runAgentLoop({
+        agent,
+        renderer,
+        tools: new Map([["echo", postFile]]),
+        toolDescriptors: [],
+        context: [],
+        makeToolCtx: () => ({ thread: {}, platform: "fake" }),
+        subscriber: {
+            onEvent: ({ event }) => {
+                ingestedEvents.push(event);
+            },
+        },
+        canonicalRun,
+    })).rejects.toBe(deliveryError);
+    expect(agent.runAgentCalls).toBe(1);
+    expect(agent.messages.some(({ role }) => role === "tool")).toBe(false);
+    expect(renderedEvents
+        .filter(({ type }) => type === EventType.RUN_STARTED ||
+        type === EventType.RUN_FINISHED ||
+        type === EventType.RUN_ERROR ||
+        type === EventType.TEXT_MESSAGE_CONTENT)
+        .map(({ type }) => type)).toEqual([EventType.RUN_STARTED]);
+    expect(ingestedEvents
+        .filter(({ type }) => type === EventType.RUN_STARTED ||
+        type === EventType.RUN_FINISHED ||
+        type === EventType.RUN_ERROR)
+        .map(({ type }) => type)).toEqual([EventType.RUN_STARTED, EventType.RUN_ERROR]);
+});
+test("inner RUN_ERROR becomes one canonical outer RUN_ERROR", async () => {
+    let agent;
+    agent = new FakeAgent([
+        (subscriber) => emitBatch(subscriber, agent, "inner-run", [
+            {
+                type: EventType.RUN_ERROR,
+                message: "inner agent failed",
+                code: "INNER_FAILED",
+            },
+        ]),
+    ]);
+    const { renderer, renderedEvents } = setupRenderer();
+    const ingestedEvents = [];
+    await expect(runAgentLoop({
+        agent,
+        renderer,
+        tools: new Map(),
+        toolDescriptors: [],
+        context: [],
+        makeToolCtx: () => {
+            throw new Error("no tool calls are expected");
+        },
+        subscriber: {
+            onEvent: ({ event }) => {
+                ingestedEvents.push(event);
+            },
+        },
+        canonicalRun,
+    })).rejects.toMatchObject({
+        message: "inner agent failed",
+        code: "INNER_FAILED",
+    });
+    const expectedLifecycle = [
+        expect.objectContaining({
+            ...canonicalRun,
+            type: EventType.RUN_STARTED,
+        }),
+        expect.objectContaining({
+            ...canonicalRun,
+            type: EventType.RUN_ERROR,
+            message: "inner agent failed",
+            code: "INNER_FAILED",
+        }),
+    ];
+    expect(ingestedEvents.filter(({ type }) => type === EventType.RUN_STARTED ||
+        type === EventType.RUN_FINISHED ||
+        type === EventType.RUN_ERROR)).toEqual(expectedLifecycle);
+    expect(renderedEvents.filter(({ type }) => type === EventType.RUN_STARTED ||
+        type === EventType.RUN_FINISHED ||
+        type === EventType.RUN_ERROR)).toEqual(expectedLifecycle);
+});
+test("managed renderer finalization sees runner metadata without replacing canonical RUN_FINISHED", async () => {
+    let agent;
+    agent = new FakeAgent([
+        (subscriber) => emitBatch(subscriber, agent, "inner-run", []),
+    ]);
+    const { renderer, renderedFinishMetadata } = setupRenderer({
+        failOnFinish: true,
+    });
+    const ingestedEvents = [];
+    const runnerMetadata = {
+        cpki_event_id: "runner-event-finished",
+        cpki_event_seq: 1,
+    };
+    const result = await runAgentLoop({
+        agent,
+        renderer,
+        tools: new Map(),
+        toolDescriptors: [],
+        context: [],
+        makeToolCtx: () => {
+            throw new Error("no tool calls are expected");
+        },
+        subscriber: {
+            onEvent: ({ event }) => {
+                if (event.type === EventType.RUN_FINISHED) {
+                    event.metadata = runnerMetadata;
+                }
+                ingestedEvents.push(event);
+            },
+        },
+        canonicalRun,
+    });
+    expect(result).toMatchObject({
+        iterations: 1,
+        interrupted: false,
+        deliveryError: { message: "renderer finalization failed" },
+    });
+    expect(ingestedEvents
+        .filter(({ type }) => type === EventType.RUN_STARTED ||
+        type === EventType.RUN_FINISHED ||
+        type === EventType.RUN_ERROR)
+        .map(({ type }) => type)).toEqual([EventType.RUN_STARTED, EventType.RUN_FINISHED]);
+    expect(renderedFinishMetadata).toEqual([runnerMetadata]);
+});

package/dist/codec.d.ts

@@ -4,13 +4,12 @@ import type { ChannelNode } from "@copilotkit/channels-ui";
  * the Intelligence side. It exists so platform *semantics* (how to render IR to
  * a native payload, and — later — how to normalize a native event to the
  * neutral ingress shape) live in ONE place, instead of being duplicated between
- * a credentialed local adapter (Bolt/discord.js) and the Connector Outbox /
- * webhook ingress.
+ * a credentialed local adapter and Gateway-owned provider delivery.
  *
  * Only the two creds/connection-bound concerns stay per-side: the transport
  * (who holds the platform connection) and the credentialed send. The codec
  * excludes both — `renderEgress` is pure (IR → native payload); the actual
- * send happens in the Connector Outbox with Intelligence-owned credentials.
+ * send happens in the Gateway with Intelligence-owned credentials.
  *
  * TODO(OSS-363): add `normalizeIngress(raw): NeutralEvent` once the pure Slack
  * ingress mapping (mention stripping, stable event-id derivation, real-user

package/dist/codec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,YAAY,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;CAC1C"}
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,YAAY,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;CAC1C"}

package/dist/create-channel.d.ts

@@ -5,11 +5,54 @@ import type { ChannelTool, ContextEntry } from "./tools.js";
 import type { ChannelCommand, CommandContext } from "./commands.js";
 import { Thread } from "./thread.js";
 import type { AbstractAgent } from "@ag-ui/client";
-import type { InteractionContext, IncomingMessage, PlatformUser, EmojiValue, ComponentFn, MessageRef } from "@copilotkit/channels-ui";
+import type { ChannelMessage, InteractionContext, IncomingMessage, PlatformUser, EmojiValue, ComponentFn, MessageRef } from "@copilotkit/channels-ui";
 import { Transcripts } from "./transcripts.js";
 import type { Identity, TranscriptsConfig } from "./transcripts.js";
 import type { StandardSchemaV1, InferSchemaOutput } from "./standard-schema.js";
 export type LockConflictDecision = "drop" | "force";
+/**
+ * How overlapping turns on the same `conversationKey` are handled.
+ *
+ * - `"parallel"` (default) — concurrent turns run together (no exclusive turn lock).
+ * - `"serial"` — later turns wait for the in-flight turn on that conversation to finish.
+ * - `"drop"` — later turns are discarded while a turn is in flight.
+ */
+export type ChannelConcurrency = "parallel" | "serial" | "drop";
+/**
+ * Isolate an agent for one turn via `clone()`.
+ *
+ * Applied to every configured shape, so the object a turn runs on is never one
+ * the caller still holds a reference to:
+ * - `createChannel({ agent: shared })` — singleton config
+ * - `agent: (id) => new Agent()` — fresh factory, cloning an unused agent
+ * - `agent: (id) => shared` — factory returning the same object every call
+ *
+ * The last shape is the one that needs this, and it is easy to write by accident
+ * (it is also what a singleton becomes when someone refactors to get at the
+ * `threadId`). Sharing one `AbstractAgent` across turns is not safe, because
+ * turn concurrency defaults to `"parallel"` — see {@link ChannelConcurrency} —
+ * and only the managed adapter serializes same-thread deliveries. On a directly
+ * connected adapter two turns in one conversation can run at the same time, and
+ * on the same instance they corrupt each other: `messages` is a single array
+ * both runs append into, so each run's new-message diff picks up the other's,
+ * and `isRunning` / `activeRunDetach$` / `activeRunCompletionPromise` are
+ * single-slot fields the second run overwrites while the first is still
+ * streaming. Managed delivery serializes them instead, on object identity, which
+ * head-of-line blocks two *different* conversations that share one instance.
+ *
+ * Fails loud on all three ways cloning can fail to isolate: a missing `clone()`,
+ * a `clone()` that hands back the same object, and a `clone()` that silently
+ * drops subclass state (see {@link assertCloneKeptOwnFields}).
+ */
+export declare function isolateAgentInstance(prototype: AbstractAgent, threadId: string): AbstractAgent;
+/**
+ * Resolve effective turn concurrency from `store.concurrency` and legacy
+ * `store.onLockConflict`. Prefer `concurrency` when both are set.
+ */
+export declare function resolveChannelConcurrency(cfg: {
+    concurrency?: ChannelConcurrency;
+    onLockConflict?: LockConflictDecision | ((conversationKey: string, message: IncomingMessage) => LockConflictDecision | Promise<LockConflictDecision>);
+}): ChannelConcurrency | "legacy-callback";
 /**
  * The managed delivery provider a no-adapter Channel targets when it is
  * activated through CopilotKit Intelligence.
@@ -42,7 +85,7 @@ export type ManagedChannelProvider = "slack" | "teams";
 export type ChannelComponent = (props: never) => ReturnType<ComponentFn>;
 export type ChannelHandler<TState = unknown> = (ctx: {
     thread: StatefulThread<TState>;
-    message: IncomingMessage;
+    message: ChannelMessage;
 }) => void | Promise<void>;
 /** Handler for a "conversation opened" lifecycle event (e.g. the Slack assistant pane). */
 export type ThreadStartHandler<TState = unknown> = (ctx: {
@@ -108,13 +151,51 @@ export interface StoreConfig<TStateSchema extends StandardSchemaV1 | undefined =
     identity?: Identity;
     /** Cross-platform transcript storage config. Paired with `identity`. */
     transcripts?: TranscriptsConfig;
-    /** What to do when a turn arrives while a prior turn on the same conversationKey is processing. */
+    /**
+     * How overlapping turns on the same conversationKey are handled.
+     * Default: `"parallel"`. Prefer this over {@link onLockConflict}.
+     */
+    concurrency?: ChannelConcurrency;
+    /**
+     * What to do when a turn arrives while a prior turn on the same conversationKey is processing.
+     *
+     * @deprecated Prefer {@link concurrency}. When `concurrency` is unset:
+     * `"drop"` → `concurrency: "drop"`, `"force"` → `concurrency: "parallel"`.
+     * A callback keeps the legacy lock + drop/force path.
+     */
     onLockConflict?: LockConflictDecision | ((conversationKey: string, message: IncomingMessage) => LockConflictDecision | Promise<LockConflictDecision>);
-    /** TTL (ms) for the per-conversation turn lock. Default 60_000. */
+    /** TTL (ms) for the per-conversation turn lock. Default 60_000. Used by `drop` / legacy paths. */
     lockTtl?: number;
     /** TTL (ms) for the inbound event dedup window. Default 300_000. */
     dedupTtl?: number;
 }
+/**
+ * Tuning for how a long reply is spread across continuation messages.
+ *
+ * Providers cap how much text one message can hold; past that the reply is
+ * split, and past {@link ReplyContinuationOptions.maxMessages} it is truncated
+ * with a visible marker. Defaults are conservative and suit most bots — reach
+ * for these when a provider's real ceiling differs, when a product wants a
+ * different tolerance for how many messages one reply may occupy, or when the
+ * truncation notice needs to be in another language.
+ *
+ * Currently honoured by managed and direct Slack.
+ */
+export interface ReplyContinuationOptions {
+    /**
+     * Soft cap on the UTF-8 bytes one message may hold before continuing into a
+     * new one. Bytes rather than characters because the provider ceiling may be
+     * counted either way, and bytes are the safe reading for non-Latin scripts.
+     */
+    readonly messageByteLimit?: number;
+    /**
+     * Ceiling on messages a single reply may occupy before it is truncated with a
+     * visible marker. Bounds a runaway reply.
+     */
+    readonly maxMessages?: number;
+    /** Notice appended when `maxMessages` is reached. Defaults to English copy. */
+    readonly truncationMarker?: string;
+}
 export interface CreateChannelOptions<TStateSchema extends StandardSchemaV1 | undefined = undefined> {
     /**
      * Project-unique Intelligence Channel name. Required for Intelligence Channel
@@ -154,7 +235,27 @@ export interface CreateChannelOptions<TStateSchema extends StandardSchemaV1 | un
      * `slack({ showToolStatus: true })` instead.
      */
     showToolStatus?: boolean;
+    /**
+     * Tuning for splitting a long reply across continuation messages. See
+     * {@link ReplyContinuationOptions}. Applies to managed and direct Slack;
+     * configure direct Slack with `slack({ replyContinuation })` instead.
+     */
+    replyContinuation?: ReplyContinuationOptions;
     agent?: AbstractAgent | ((threadId: string) => AbstractAgent);
+    /**
+     * Tolerate the AG-UI event streams real agents emit. On by default.
+     *
+     * `@ag-ui/langgraph` emits a `TOOL_CALL_START` whose `parentMessageId` is
+     * `null` — notably the tool call that triggers an interrupt — which strict
+     * client-side validation rejects, aborting the whole run and breaking
+     * human-in-the-loop. Channels coerce that field on the wire so the run
+     * survives; see {@link sanitizeAgentEventStream} for exactly what is touched.
+     *
+     * Set `false` to stream events through unmodified and let a malformed event
+     * fail the run. Only meaningful for agents that stream over HTTP — nothing
+     * re-validates the events of an in-process agent.
+     */
+    sanitizeAgentEvents?: boolean;
     /** @deprecated Pass `store.adapter` instead. */
     actionStore?: ActionStore;
     tools?: ChannelTool[];
@@ -189,6 +290,11 @@ export interface Channel<TState = unknown> {
      * undefined. Ignored for direct-adapter Channels.
      */
     readonly showToolStatus?: boolean;
+    /**
+     * Continuation-message tuning from `createChannel({ replyContinuation })`.
+     * Undefined leaves the provider defaults in place.
+     */
+    readonly replyContinuation?: ReplyContinuationOptions;
     /** Declared slash-command names (normalized). Surfaced for Channel activation metadata. */
     readonly commandNames: string[];
     onMention(h: ChannelHandler<TState>): void;