managed-deepagents 0.9.4-dev.9 → 0.10.0-dev.10

package/dist/channels/http/reply.js

@@ -0,0 +1,116 @@
+/**
+ * An HTTP channel run posts its own answer.
+ *
+ * The run does it, not the process that received the delivery, so a restart
+ * of that process doesn't lose the answer, and a run LangSmith Studio resumes
+ * after a decision answers the conversation the paused run came from.
+ */
+import { getConfig } from "@langchain/langgraph";
+import { createMiddleware } from "langchain";
+import { z } from "zod";
+import { extractAssistantContent } from "../assistant-text.js";
+import { resolveChannelBinding } from "../binding.js";
+import { isJsonValue } from "../message-schema.js";
+import { messagingTransportForName } from "../messaging-registry.js";
+import { isTrustedScheduleDeliveryRun } from "../schedule-delivery.js";
+import { CHANNEL_THREAD_METADATA, configurableFromRuntime, resolveAmbientConfigurable, } from "../../runtime/identity-runtime.js";
+import { logger } from "../../runtime/log.js";
+/**
+ * Where the thread's latest channel delivery came from, kept in its state.
+ * Private (the leading `_`), so it's never part of a run's input or output.
+ */
+export const CHANNEL_REPLY_STATE_KEY = "_mda_channel_reply";
+const replyTargetSchema = z.object({
+    name: z.string().min(1),
+    target: z.custom((value) => isJsonValue(value)),
+});
+/**
+ * The run's verified HTTP channel delivery: one the channel's ingress started
+ * for that conversation (the binding matches the run's authenticated source),
+ * never one a caller put in the run's context.
+ */
+function deliveredTarget(runtime) {
+    const configurable = configurableFromRuntime(runtime) ??
+        resolveAmbientConfigurable();
+    const binding = resolveChannelBinding(undefined, configurable);
+    // Only HTTP channels deliver directly; others answer on their own.
+    if (!binding || binding.transport !== "direct")
+        return undefined;
+    return { name: binding.name, target: binding.target };
+}
+/**
+ * Whether the run is on a channel's thread. Only managed ingress marks one;
+ * the runtime's auth strips the marker from every other thread and run, so a
+ * caller can't point its own thread's stored target at someone else's
+ * conversation. Channel threads take runs only from their channel and resumes
+ * from LangSmith Studio.
+ */
+function onChannelThread() {
+    try {
+        const metadata = getConfig().metadata;
+        return metadata?.[CHANNEL_THREAD_METADATA] === "true";
+    }
+    catch {
+        // Outside a runnable context.
+        return false;
+    }
+}
+function storedTarget(state) {
+    if (!onChannelThread())
+        return undefined;
+    const value = state && typeof state === "object" && !Array.isArray(state)
+        ? state[CHANNEL_REPLY_STATE_KEY]
+        : undefined;
+    const parsed = replyTargetSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * Remember a channel delivery's target in the thread's state, and post the
+ * answer to it when the agent finishes. A run that stops on `interrupt()` or
+ * is cancelled doesn't finish, so it posts nothing; the run that resumes it
+ * carries no delivery, so it answers the remembered target.
+ */
+export function createChannelReplyMiddleware() {
+    return createMiddleware({
+        name: "mda-channel-reply",
+        stateSchema: z.object({
+            [CHANNEL_REPLY_STATE_KEY]: replyTargetSchema.optional(),
+        }),
+        beforeAgent(_state, runtime) {
+            const delivered = deliveredTarget(runtime);
+            return delivered ? { [CHANNEL_REPLY_STATE_KEY]: delivered } : undefined;
+        },
+        async afterAgent(state, runtime) {
+            const configurable = configurableFromRuntime(runtime) ??
+                resolveAmbientConfigurable();
+            // Scheduled runs post through schedule delivery.
+            if (isTrustedScheduleDeliveryRun(configurable))
+                return undefined;
+            const reply = deliveredTarget(runtime) ?? storedTarget(state);
+            if (!reply)
+                return undefined;
+            const content = extractAssistantContent({
+                messages: state.messages,
+            });
+            if (content === null)
+                return undefined;
+            const transport = messagingTransportForName(reply.name);
+            if (!transport) {
+                logger.warn(`channel reply skipped: no channel ${JSON.stringify(logger.logIdentifier(reply.name))}`);
+                return undefined;
+            }
+            try {
+                await transport.post({
+                    message: { type: "content", content },
+                    target: reply.target,
+                });
+            }
+            catch (error) {
+                // The answer stays in the thread; the run itself succeeded.
+                logger.error(`channel reply failed (${logger.safeErrorLabel(error)})`);
+            }
+            return undefined;
+        },
+    });
+}
+//# sourceMappingURL=reply.js.map

package/dist/channels/http/reply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reply.js","sourceRoot":"","sources":["../../../src/channels/http/reply.ts"],"names":[],"mappings":"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"}

package/dist/channels/http/studio.d.ts

@@ -0,0 +1,17 @@
+import type { HttpDelivery } from "./types.js";
+/**
+ * The thread in the deployment's Studio, or the deployment's page when the
+ * deployment's name or the thread's assistant is unknown. The LangSmith UI is
+ * the one `mda deploy` recorded for the deployment's environment
+ * (`MDA_LANGSMITH_URL`); without it there is nothing to link to.
+ */
+export declare function studioUrl(run: HttpDelivery | undefined, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * What a channel tells the conversation when its thread waits on a decision,
+ * with a link to the thread in Studio, where the decision is made: the run
+ * the delivery started stopped on interrupts (`interrupted`), or the message
+ * found the thread waiting (`waiting`). `again` says how to continue once it
+ * is made, such as "comment again".
+ */
+export declare function interruptedNotice(outcome: "interrupted" | "waiting", delivery: HttpDelivery, again: string): string;
+//# sourceMappingURL=studio.d.ts.map

package/dist/channels/http/studio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"studio.d.ts","sourceRoot":"","sources":["../../../src/channels/http/studio.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAS/C;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,YAAY,GAAG,SAAS,EAC7B,GAAG,oBAAc,GAChB,MAAM,GAAG,SAAS,CAsBpB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,MAAM,GACZ,MAAM,CAMR"}

package/dist/channels/http/studio.js

@@ -0,0 +1,82 @@
+/** Links from channel notices into the deployment's LangSmith Studio. */
+import { v5 as uuidv5 } from "uuid";
+import { DEPLOYMENT_ID_ENV } from "../../connections.js";
+import { managedDeploymentName } from "../../runtime/sandbox-manager.js";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DEPLOYMENT_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const GRAPH_ID_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/;
+/** The namespace the Agent Server derives a graph's default assistant from. */
+const GRAPH_NAMESPACE = "6ba7b821-9dad-11d1-80b4-00c04fd430c8";
+/**
+ * The thread in the deployment's Studio, or the deployment's page when the
+ * deployment's name or the thread's assistant is unknown. The LangSmith UI is
+ * the one `mda deploy` recorded for the deployment's environment
+ * (`MDA_LANGSMITH_URL`); without it there is nothing to link to.
+ */
+export function studioUrl(run, env = process.env) {
+    const threadId = run?.threadId;
+    const thread = threadId && UUID_PATTERN.test(threadId) ? threadId : undefined;
+    const workspace = env.LANGSMITH_TENANT_ID?.trim() ?? "";
+    const deployment = env[DEPLOYMENT_ID_ENV]?.trim() ?? "";
+    if (!UUID_PATTERN.test(workspace) || !UUID_PATTERN.test(deployment))
+        return undefined;
+    const origin = parseHttpUrl(env.MDA_LANGSMITH_URL)?.origin;
+    if (!origin)
+        return undefined;
+    const name = managedDeploymentName(env);
+    const assistantId = assistantUuid(run?.assistantId);
+    if (!name || !DEPLOYMENT_NAME_PATTERN.test(name) || !thread || !assistantId)
+        return `${origin}/o/${workspace}/host/deployments/${deployment}`;
+    const query = new URLSearchParams({
+        organizationId: workspace,
+        render: "interact",
+        hostProjectId: deployment,
+        assistantId,
+        mode: "chat",
+        threadId: thread,
+    });
+    return `${origin}/o/${workspace}/a/${encodeURIComponent(name)}/studio/thread?${query}`;
+}
+/**
+ * What a channel tells the conversation when its thread waits on a decision,
+ * with a link to the thread in Studio, where the decision is made: the run
+ * the delivery started stopped on interrupts (`interrupted`), or the message
+ * found the thread waiting (`waiting`). `again` says how to continue once it
+ * is made, such as "comment again".
+ */
+export function interruptedNotice(outcome, delivery, again) {
+    const url = studioUrl(delivery);
+    const studio = url ? `[LangSmith Studio](${url})` : "LangSmith Studio";
+    return outcome === "interrupted"
+        ? `I need a decision before I continue. Review the pending step in ${studio}.`
+        : `I'm waiting for a decision on an earlier step in this conversation, so I haven't read this yet. Review the pending step in ${studio}, then ${again}.`;
+}
+/**
+ * Studio opens an assistant by its ID. Channels start runs by graph ID, whose
+ * default assistant the Agent Server derives from it.
+ */
+function assistantUuid(assistant) {
+    if (!assistant)
+        return undefined;
+    if (UUID_PATTERN.test(assistant))
+        return assistant;
+    return GRAPH_ID_PATTERN.test(assistant)
+        ? uuidv5(assistant, GRAPH_NAMESPACE)
+        : undefined;
+}
+function parseHttpUrl(value) {
+    if (!value?.trim())
+        return undefined;
+    try {
+        const url = new URL(value.trim());
+        return (url.protocol === "https:" || url.protocol === "http:") &&
+            !url.username &&
+            !url.password
+            ? url
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=studio.js.map

package/dist/channels/http/studio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"studio.js","sourceRoot":"","sources":["../../../src/channels/http/studio.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAGzE,MAAM,YAAY,GAChB,iEAAiE,CAAC;AACpE,MAAM,uBAAuB,GAAG,oCAAoC,CAAC;AACrE,MAAM,gBAAgB,GAAG,qCAAqC,CAAC;AAC/D,+EAA+E;AAC/E,MAAM,eAAe,GAAG,sCAAsC,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,GAA6B,EAC7B,GAAG,GAAG,OAAO,CAAC,GAAG;IAEjB,MAAM,QAAQ,GAAG,GAAG,EAAE,QAAQ,CAAC;IAC/B,MAAM,MAAM,GAAG,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9E,MAAM,SAAS,GAAG,GAAG,CAAC,mBAAmB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACxD,MAAM,UAAU,GAAG,GAAG,CAAC,iBAAiB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACxD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC;QACjE,OAAO,SAAS,CAAC;IACnB,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3D,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,IAAI,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,WAAW,GAAG,aAAa,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACpD,IAAI,CAAC,IAAI,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,WAAW;QACzE,OAAO,GAAG,MAAM,MAAM,SAAS,qBAAqB,UAAU,EAAE,CAAC;IACnE,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC;QAChC,cAAc,EAAE,SAAS;QACzB,MAAM,EAAE,UAAU;QAClB,aAAa,EAAE,UAAU;QACzB,WAAW;QACX,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,MAAM;KACjB,CAAC,CAAC;IACH,OAAO,GAAG,MAAM,MAAM,SAAS,MAAM,kBAAkB,CAAC,IAAI,CAAC,kBAAkB,KAAK,EAAE,CAAC;AACzF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAkC,EAClC,QAAsB,EACtB,KAAa;IAEb,MAAM,GAAG,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,sBAAsB,GAAG,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC;IACvE,OAAO,OAAO,KAAK,aAAa;QAC9B,CAAC,CAAC,mEAAmE,MAAM,GAAG;QAC9E,CAAC,CAAC,8HAA8H,MAAM,UAAU,KAAK,GAAG,CAAC;AAC7J,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa,CAAC,SAA6B;IAClD,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IACjC,IAAI,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IACnD,OAAO,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC;QACrC,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,eAAe,CAAC;QACpC,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,SAAS,YAAY,CAAC,KAAyB;IAC7C,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE;QAAE,OAAO,SAAS,CAAC;IACrC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,CAAC;YAC5D,CAAC,GAAG,CAAC,QAAQ;YACb,CAAC,GAAG,CAAC,QAAQ;YACb,CAAC,CAAC,GAAG;YACL,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/channels/http/threads.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The thread for one provider conversation, such as an issue or a chat: the
+ * same channel and key always give the same UUID, so each message continues
+ * the conversation. The Python runtime derives the same IDs.
+ */
+export declare function channelThreadId(channelName: string, key: string): string;
+//# sourceMappingURL=threads.d.ts.map

package/dist/channels/http/threads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threads.d.ts","sourceRoot":"","sources":["../../../src/channels/http/threads.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAKxE"}

package/dist/channels/http/threads.js

@@ -0,0 +1,10 @@
+import { v5 as uuidv5 } from "uuid";
+/**
+ * The thread for one provider conversation, such as an issue or a chat: the
+ * same channel and key always give the same UUID, so each message continues
+ * the conversation. The Python runtime derives the same IDs.
+ */
+export function channelThreadId(channelName, key) {
+    return uuidv5(`mda-thread:v1:${JSON.stringify([channelName, key])}`, uuidv5.URL);
+}
+//# sourceMappingURL=threads.js.map

package/dist/channels/http/threads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"threads.js","sourceRoot":"","sources":["../../../src/channels/http/threads.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AAEpC;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,WAAmB,EAAE,GAAW;IAC9D,OAAO,MAAM,CACX,iBAAiB,IAAI,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,EAAE,EACrD,MAAM,CAAC,GAAG,CACX,CAAC;AACJ,CAAC"}

package/dist/channels/http/types.d.ts

@@ -1,11 +1,30 @@
+import type { MultitaskStrategy } from "../../ingress/runs.js";
 import type { MessageContent } from "@langchain/core/messages";
 import type { ChannelMessage, JsonValue } from "../types.js";
+import type { ChannelRunResult } from "../run-input.js";
 export interface HttpChannelInboundMessage {
     userId: string;
+    /** See {@link channelThreadId} for one thread per provider conversation. */
     threadId: string;
     /** Provider destination, independent of the LangGraph thread UUID. */
     target: JsonValue;
-    content: MessageContent;
+    /**
+     * What a new run starts with. Without it, the adapter's `input` supplies it
+     * once MDA knows the thread takes a new turn.
+     */
+    content?: MessageContent;
+    /**
+     * The provider's ID for this delivery. A thread runs each delivery once, so
+     * a redelivered event starts nothing.
+     */
+    deliveryKey?: string;
+}
+/** The thread a `cancel` result stops, and who to tell. */
+export interface HttpChannelCancelMessage {
+    userId: string;
+    threadId: string;
+    /** Where to report the stop. */
+    target: JsonValue;
 }
 export type HttpChannelParseResult = {
     type: "message";
@@ -16,6 +35,15 @@ export type HttpChannelParseResult = {
 } | {
     type: "ignore";
     response?: Response;
+} | {
+    /**
+     * Stop the work on the message's thread: MDA cancels its queued and
+     * running runs, keeping their progress, then calls `onSettled`.
+     */
+    type: "cancel";
+    message: HttpChannelCancelMessage;
+    rawEvent?: JsonValue;
+    response?: Response;
 };
 /** MDA adds the verified reply target to the validated message. */
 export type HttpChannelPostInput = ChannelMessage & {
@@ -29,12 +57,96 @@ export interface HttpPostedMessage {
 }
 export interface HttpChannelAdapter {
     provider: string;
+    providerConfig?: Record<string, JsonValue>;
+    /**
+     * What a message that starts a turn does while its thread already runs:
+     * `enqueue` (the default) waits for the run and starts after it,
+     * `interrupt` cancels the run, keeping its progress, and starts at once,
+     * `rollback` cancels it and discards its progress, and `reject` starts
+     * nothing. Messages to a thread that waits on an interrupt start nothing
+     * either way.
+     */
+    multitaskStrategy?: MultitaskStrategy;
     verify(context: HttpChannelRequest): boolean | Promise<boolean>;
     /** Decode the verified request body in the provider's format. */
     parse(context: HttpChannelRequest): HttpChannelParseResult | Promise<HttpChannelParseResult>;
     post?(input: HttpChannelPostInput): Promise<HttpPostedMessage>;
+    /**
+     * The run a message started failed: tell the sender instead of the default
+     * apology `post` sends. Called before `onSettled`.
+     */
     onError?(error: unknown, target: JsonValue): Promise<void>;
+    /**
+     * What a message without `content` starts a run with, asked only once the
+     * thread takes a new turn, never while it waits on an interrupt. `null` or
+     * `undefined` starts nothing.
+     */
+    input?(message: HttpChannelInboundMessage, rawEvent: JsonValue | undefined): ChannelRunResult | null | undefined | Promise<ChannelRunResult | null | undefined>;
+    /**
+     * A verified message reached its thread, before MDA starts or queues
+     * anything for it. For providers that expect a prompt acknowledgement.
+     * Each message that gets it also gets one `onSettled`. Runs in the
+     * background; failures are logged.
+     */
+    onReceived?(target: JsonValue, delivery: HttpDelivery): Promise<void>;
+    /**
+     * How a message or a cancel ended, once: the run it started completed,
+     * stopped on interrupts, was cancelled, replaced, or failed, or why it
+     * started none. See {@link HttpDeliveryOutcome}. Runs in the background;
+     * failures are logged.
+     *
+     * It runs in the process that took the delivery, so a restart while a run
+     * is in flight loses it; a run Studio resumes has no delivery, so it gets
+     * none.
+     */
+    onSettled?(target: JsonValue, delivery: HttpSettledDelivery): Promise<void>;
 }
+/** A delivery's thread, for notices and links into LangSmith Studio. */
+export interface HttpDelivery {
+    threadId: string;
+    /** The assistant that runs on the thread, when known. */
+    assistantId?: string;
+    /** The provider event `parse` returned, if any. */
+    rawEvent?: JsonValue;
+}
+/** A delivery and how it ended; see {@link HttpChannelAdapter.onSettled}. */
+export type HttpSettledDelivery = HttpDelivery & {
+    outcome: HttpDeliveryOutcome;
+};
+/**
+ * How a delivery ended. A message that started a run carries its `runId`:
+ *
+ * - `completed`: the run finished.
+ * - `interrupted`: it stopped on interrupts, so the thread waits on a
+ *   decision, made in Studio.
+ * - `cancelled`: a cancel, or a newer message's `interrupt`, ended it.
+ * - `replaced`: a newer message's `rollback` deleted it.
+ * - `failed`: it failed, after `onError`. Without a `runId`, MDA couldn't
+ *   start one.
+ * - `unknown`: MDA lost track of it; it may have answered.
+ *
+ * A message that started no run:
+ *
+ * - `waiting`: the thread waits on a decision.
+ * - `rejected`: the thread was busy and `multitaskStrategy` is `reject`.
+ * - `declined`: `input` returned nothing.
+ * - `dropped`: a cancel stopped the thread while the message waited for it.
+ * - `duplicate`: the thread already ran this `deliveryKey`.
+ *
+ * A cancel is `stopped`, with how many of the thread's runs were active.
+ */
+export type HttpDeliveryOutcome = {
+    type: "completed" | "interrupted" | "cancelled" | "replaced" | "unknown";
+    runId: string;
+} | {
+    type: "failed";
+    runId?: string;
+} | {
+    type: "waiting" | "rejected" | "declined" | "dropped" | "duplicate";
+} | {
+    type: "stopped";
+    cancelled: number;
+};
 export interface HttpChannelRequest {
     request: Request;
     rawBody: Uint8Array;

package/dist/channels/http/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/channels/http/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7D,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,MAAM,sBAAsB,GAC9B;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,yBAAyB,CAAC;IACnC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,GACD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE5C,mEAAmE;AACnE,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG;IAClD,MAAM,EAAE,SAAS,CAAC;IAClB,gFAAgF;IAChF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChE,iEAAiE;IACjE,KAAK,CACH,OAAO,EAAE,kBAAkB,GAC1B,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC5D,IAAI,CAAC,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC/D,OAAO,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,UAAU,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/channels/http/types.ts"],"names":[],"mappings":"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"}

package/dist/channels/linear/connections.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Reserved agent connection for the deployment's Linear app: reading it
+ * returns the app's access token, which Agent Auth renews.
+ */
+export declare const LINEAR_TOKEN_SLUG = "mda/linear-token";
+/**
+ * The deployment's Linear app connection, or one of the app values stored
+ * beside it (`webhook-secret`) when `suffix` is given.
+ */
+export declare function linearAppConnectionSlug(deploymentId: string, suffix?: string): string;
+//# sourceMappingURL=connections.d.ts.map

package/dist/channels/linear/connections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../../../src/channels/linear/connections.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,iBAAiB,qBAAqB,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAER"}

package/dist/channels/linear/connections.js

@@ -0,0 +1,14 @@
+import { appConnectionSlug } from "../http/provider.js";
+/**
+ * Reserved agent connection for the deployment's Linear app: reading it
+ * returns the app's access token, which Agent Auth renews.
+ */
+export const LINEAR_TOKEN_SLUG = "mda/linear-token";
+/**
+ * The deployment's Linear app connection, or one of the app values stored
+ * beside it (`webhook-secret`) when `suffix` is given.
+ */
+export function linearAppConnectionSlug(deploymentId, suffix) {
+    return appConnectionSlug("linear", deploymentId, suffix);
+}
+//# sourceMappingURL=connections.js.map

package/dist/channels/linear/connections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connections.js","sourceRoot":"","sources":["../../../src/channels/linear/connections.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAEpD;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,YAAoB,EACpB,MAAe;IAEf,OAAO,iBAAiB,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;AAC3D,CAAC"}

package/dist/channels/linear/graphql.d.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+/** Linear refused a request for exceeding its rate limit. */
+export declare class LinearRateLimitError extends Error {
+    constructor();
+}
+/** Forget the cached app token; for tests. */
+export declare function resetLinearToken(): void;
+/**
+ * Run a GraphQL operation as the app. `query` is a constant; everything that
+ * varies goes in `variables`. A rejected token is read again once. Returns
+ * the response's `data`, checked against `schema`.
+ */
+export declare function linearRequest<T>(query: string, variables: Record<string, unknown>, schema: z.ZodType<T>): Promise<T>;
+/** The Linear user the app acts as. */
+export type LinearAppUser = {
+    id: string;
+    displayName: string;
+};
+export declare function linearAppUser(): Promise<LinearAppUser>;
+/** Forget the cached app user; for tests. */
+export declare function resetLinearAppUser(): void;
+/**
+ * Comment on an issue as the app, threaded under `parentId` when given.
+ * Returns the comment's id and URL.
+ */
+export declare function createLinearComment(input: {
+    issueId: string;
+    body: string;
+    parentId?: string;
+}): Promise<{
+    id: string;
+    url?: string;
+}>;
+/** Whether a comment belongs to an agent session's thread. */
+export declare function commentInAgentSession(commentId: string): Promise<boolean>;
+/** What the app says in an agent session. */
+export type LinearActivityContent = {
+    type: "thought" | "response" | "error" | "elicitation";
+    body: string;
+};
+/**
+ * Post an activity to an agent session as the app. An `ephemeral` thought is
+ * replaced by the next activity.
+ */
+export declare function createLinearActivity(input: {
+    agentSessionId: string;
+    content: LinearActivityContent;
+    ephemeral?: boolean;
+}): Promise<{
+    id: string;
+}>;
+/** Link an agent session to a page about it, such as its Studio thread. */
+export declare function addLinearSessionUrl(agentSessionId: string, link: {
+    label: string;
+    url: string;
+}): Promise<void>;
+//# sourceMappingURL=graphql.d.ts.map

package/dist/channels/linear/graphql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql.d.ts","sourceRoot":"","sources":["../../../src/channels/linear/graphql.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiCxB,6DAA6D;AAC7D,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,cAGC;CACF;AAQD,8CAA8C;AAC9C,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAWD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CA4BZ;AAoBD,uCAAuC;AACvC,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAahE,wBAAgB,aAAa,IAAI,OAAO,CAAC,aAAa,CAAC,CAEtD;AAED,6CAA6C;AAC7C,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAYD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAKxC;AAWD,8DAA8D;AAC9D,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,6CAA6C;AAC7C,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,aAAa,CAAC;IACvD,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAYF;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE;IAChD,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAS1B;AASD,2EAA2E;AAC3E,wBAAsB,mBAAmB,CACvC,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACnC,OAAO,CAAC,IAAI,CAAC,CAMf"}