managed-deepagents 0.10.0-dev.3 → 0.10.0-dev.5

package/dist/channels/linear/graphql.js

@@ -0,0 +1,169 @@
+import { connections } from "../../connections.js";
+import { LINEAR_TOKEN_SLUG } from "./connections.js";
+const LINEAR_GRAPHQL_URL = "https://api.linear.app/graphql";
+const LINEAR_API_TIMEOUT_MS = 10_000;
+/** The largest Linear response body read. */
+const LINEAR_RESPONSE_MAX_CHARS = 1_000_000;
+/** How long the app token read from Agent Auth is reused. */
+const TOKEN_TTL_MS = 5 * 60_000;
+let appToken;
+/**
+ * Where GraphQL requests go: Linear's API, or under `mda dev`
+ * (`MDA_LOCAL_DEV=1`) the stand-in `MDA_LINEAR_API_URL` names, so local
+ * tests never reach Linear. A deployment always uses Linear's API.
+ */
+function graphqlUrl(env = process.env) {
+    const override = env.MDA_LINEAR_API_URL?.trim();
+    if (env.MDA_LOCAL_DEV !== "1" || !override)
+        return LINEAR_GRAPHQL_URL;
+    const url = new URL(override);
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        throw new TypeError("MDA_LINEAR_API_URL must be an http(s) URL");
+    return url.toString();
+}
+/** Linear refused a request for exceeding its rate limit. */
+export class LinearRateLimitError extends Error {
+    constructor() {
+        super("Linear rate limit exceeded");
+        this.name = "LinearRateLimitError";
+    }
+}
+/** The app's access token, read from Agent Auth at most every few minutes. */
+function linearToken() {
+    if (appToken && appToken.expiresAt > Date.now())
+        return appToken.value;
+    const entry = {
+        value: connections.resolveDeploymentSecret(LINEAR_TOKEN_SLUG),
+        expiresAt: Date.now() + TOKEN_TTL_MS,
+    };
+    entry.value.catch(() => {
+        if (appToken === entry)
+            appToken = undefined;
+    });
+    appToken = entry;
+    return entry.value;
+}
+/** Forget the cached app token; for tests. */
+export function resetLinearToken() {
+    appToken = undefined;
+}
+function errorCodes(body) {
+    return (body.errors ?? []).flatMap((error) => typeof error.extensions?.code === "string" ? [error.extensions.code] : []);
+}
+/**
+ * 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`.
+ */
+export async function linearRequest(query, variables = {}) {
+    const send = async () => fetch(graphqlUrl(), {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${await linearToken()}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ query, variables }),
+        signal: AbortSignal.timeout(LINEAR_API_TIMEOUT_MS),
+    });
+    let response = await send();
+    let body = await readBody(response);
+    if (response.status === 401 ||
+        errorCodes(body).includes("AUTHENTICATION_ERROR")) {
+        appToken = undefined;
+        response = await send();
+        body = await readBody(response);
+    }
+    if (errorCodes(body).includes("RATELIMITED"))
+        throw new LinearRateLimitError();
+    if (!response.ok || body.errors?.length || body.data === undefined)
+        throw new Error(`Linear refused the request (HTTP ${response.status})`);
+    return body.data;
+}
+async function readBody(response) {
+    const text = await response.text();
+    if (text.length > LINEAR_RESPONSE_MAX_CHARS)
+        return {};
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+const VIEWER_QUERY = "query MdaLinearViewer { viewer { id displayName } }";
+let appUser;
+/**
+ * The Linear user the app acts as, read once per process: its own comments
+ * and changes are ignored, and a comment mentioning its `displayName` starts
+ * an agent session.
+ */
+export function linearAppUser() {
+    appUser ??= linearRequest(VIEWER_QUERY).then(({ viewer }) => {
+        if (typeof viewer?.id !== "string" ||
+            !viewer.id ||
+            typeof viewer.displayName !== "string")
+            throw new Error("Linear did not report the app's user");
+        return { id: viewer.id, displayName: viewer.displayName };
+    });
+    appUser.catch(() => {
+        appUser = undefined;
+    });
+    return appUser;
+}
+/** Forget the cached app user; for tests. */
+export function resetLinearAppUser() {
+    appUser = undefined;
+}
+const COMMENT_CREATE_MUTATION = `mutation MdaLinearCommentCreate($input: CommentCreateInput!) {
+  commentCreate(input: $input) { success comment { id url } }
+}`;
+/**
+ * Comment on an issue as the app, threaded under `parentId` when given.
+ * Returns the comment's id and URL.
+ */
+export async function createLinearComment(input) {
+    const data = await linearRequest(COMMENT_CREATE_MUTATION, { input });
+    const comment = data.commentCreate?.comment;
+    if (!data.commentCreate?.success || !comment?.id)
+        throw new Error("Linear did not create the comment");
+    return { id: comment.id, ...(comment.url && { url: comment.url }) };
+}
+const COMMENT_SESSION_QUERY = `query MdaLinearCommentSession($id: String!) {
+  comment(id: $id) { agentSession { id } }
+}`;
+/** Whether a comment belongs to an agent session's thread. */
+export async function commentInAgentSession(commentId) {
+    const data = await linearRequest(COMMENT_SESSION_QUERY, { id: commentId });
+    return Boolean(data.comment?.agentSession?.id);
+}
+const ACTIVITY_CREATE_MUTATION = `mutation MdaLinearActivityCreate($input: AgentActivityCreateInput!) {
+  agentActivityCreate(input: $input) { success agentActivity { id } }
+}`;
+/**
+ * Post an activity to an agent session as the app. `ephemeral` thoughts and
+ * actions are replaced by the next activity; a `select` signal offers
+ * options to choose from.
+ */
+export async function createLinearActivity(input) {
+    const data = await linearRequest(ACTIVITY_CREATE_MUTATION, { input });
+    const activity = data.agentActivityCreate?.agentActivity;
+    if (!data.agentActivityCreate?.success || !activity?.id)
+        throw new Error("Linear did not create the activity");
+    return { id: activity.id };
+}
+const SESSION_UPDATE_MUTATION = `mutation MdaLinearSessionUpdate($id: String!, $input: AgentSessionUpdateInput!) {
+  agentSessionUpdate(id: $id, input: $input) { success }
+}`;
+/** Link an agent session to a page about it, such as its Studio thread. */
+export async function addLinearSessionUrl(agentSessionId, link) {
+    const data = await linearRequest(SESSION_UPDATE_MUTATION, {
+        id: agentSessionId,
+        input: { addedExternalUrls: [link] },
+    });
+    if (!data.agentSessionUpdate?.success)
+        throw new Error("Linear did not update the session");
+}
+//# sourceMappingURL=graphql.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graphql.js","sourceRoot":"","sources":["../../../src/channels/linear/graphql.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,kBAAkB,GAAG,gCAAgC,CAAC;AAC5D,MAAM,qBAAqB,GAAG,MAAM,CAAC;AACrC,6CAA6C;AAC7C,MAAM,yBAAyB,GAAG,SAAS,CAAC;AAC5C,6DAA6D;AAC7D,MAAM,YAAY,GAAG,CAAC,GAAG,MAAM,CAAC;AAEhC,IAAI,QAAmE,CAAC;AAExE;;;;GAIG;AACH,SAAS,UAAU,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG;IACnC,MAAM,QAAQ,GAAG,GAAG,CAAC,kBAAkB,EAAE,IAAI,EAAE,CAAC;IAChD,IAAI,GAAG,CAAC,aAAa,KAAK,GAAG,IAAI,CAAC,QAAQ;QAAE,OAAO,kBAAkB,CAAC;IACtE,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC9B,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ;QACvD,MAAM,IAAI,SAAS,CAAC,2CAA2C,CAAC,CAAC;IACnE,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC;AAED,6DAA6D;AAC7D,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C;QACE,KAAK,CAAC,4BAA4B,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,8EAA8E;AAC9E,SAAS,WAAW;IAClB,IAAI,QAAQ,IAAI,QAAQ,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,QAAQ,CAAC,KAAK,CAAC;IACvE,MAAM,KAAK,GAAG;QACZ,KAAK,EAAE,WAAW,CAAC,uBAAuB,CAAC,iBAAiB,CAAC;QAC7D,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY;KACrC,CAAC;IACF,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE;QACrB,IAAI,QAAQ,KAAK,KAAK;YAAE,QAAQ,GAAG,SAAS,CAAC;IAC/C,CAAC,CAAC,CAAC;IACH,QAAQ,GAAG,KAAK,CAAC;IACjB,OAAO,KAAK,CAAC,KAAK,CAAC;AACrB,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,gBAAgB;IAC9B,QAAQ,GAAG,SAAS,CAAC;AACvB,CAAC;AAKD,SAAS,UAAU,CAAC,IAAqB;IACvC,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAC3C,OAAO,KAAK,CAAC,UAAU,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAC1E,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAa,EACb,SAAS,GAA4B,EAAE;IAEvC,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE,CACtB,KAAK,CAAC,UAAU,EAAE,EAAE;QAClB,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,MAAM,WAAW,EAAE,EAAE;YAC9C,cAAc,EAAE,kBAAkB;SACnC;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAC1C,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,qBAAqB,CAAC;KACnD,CAAC,CAAC;IACL,IAAI,QAAQ,GAAG,MAAM,IAAI,EAAE,CAAC;IAC5B,IAAI,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACpC,IACE,QAAQ,CAAC,MAAM,KAAK,GAAG;QACvB,UAAU,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,sBAAsB,CAAC,EACjD,CAAC;QACD,QAAQ,GAAG,SAAS,CAAC;QACrB,QAAQ,GAAG,MAAM,IAAI,EAAE,CAAC;QACxB,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC;QAC1C,MAAM,IAAI,oBAAoB,EAAE,CAAC;IACnC,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;QAChE,MAAM,IAAI,KAAK,CAAC,oCAAoC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IAC1E,OAAO,IAAI,CAAC,IAAS,CAAC;AACxB,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,QAAkB;IACxC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,IAAI,CAAC,MAAM,GAAG,yBAAyB;QAAE,OAAO,EAAE,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;QAC3C,OAAO,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YACnE,CAAC,CAAE,MAA0B;YAC7B,CAAC,CAAC,EAAE,CAAC;IACT,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,YAAY,GAAG,qDAAqD,CAAC;AAI3E,IAAI,OAA2C,CAAC;AAEhD;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,KAAK,aAAa,CAEtB,YAAY,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE;QACnC,IACE,OAAO,MAAM,EAAE,EAAE,KAAK,QAAQ;YAC9B,CAAC,MAAM,CAAC,EAAE;YACV,OAAO,MAAM,CAAC,WAAW,KAAK,QAAQ;YAEtC,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC1D,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC;IAC5D,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE;QACjB,OAAO,GAAG,SAAS,CAAC;IACtB,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,kBAAkB;IAChC,OAAO,GAAG,SAAS,CAAC;AACtB,CAAC;AAED,MAAM,uBAAuB,GAAG;;EAE9B,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,KAIzC;IACC,MAAM,IAAI,GAAG,MAAM,aAAa,CAE7B,uBAAuB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC;IAC5C,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE;QAC9C,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;AACtE,CAAC;AAED,MAAM,qBAAqB,GAAG;;EAE5B,CAAC;AAEH,8DAA8D;AAC9D,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,SAAiB;IAEjB,MAAM,IAAI,GAAG,MAAM,aAAa,CAE7B,qBAAqB,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAC7C,OAAO,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,CAAC,CAAC;AACjD,CAAC;AAOD,MAAM,wBAAwB,GAAG;;EAE/B,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,KAM1C;IACC,MAAM,IAAI,GAAG,MAAM,aAAa,CAE7B,wBAAwB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,mBAAmB,EAAE,aAAa,CAAC;IACzD,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,OAAO,IAAI,CAAC,QAAQ,EAAE,EAAE;QACrD,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACxD,OAAO,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,uBAAuB,GAAG;;EAE9B,CAAC;AAEH,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,cAAsB,EACtB,IAAoC;IAEpC,MAAM,IAAI,GAAG,MAAM,aAAa,CAE7B,uBAAuB,EAAE;QAC1B,EAAE,EAAE,cAAc;QAClB,KAAK,EAAE,EAAE,iBAAiB,EAAE,CAAC,IAAI,CAAC,EAAE;KACrC,CAAC,CAAC;IACH,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,OAAO;QACnC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;AACzD,CAAC"}

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

@@ -0,0 +1,9 @@
+import { type HttpChannel } from "../http/index.js";
+import type { LinearChannelOptions } from "./types.js";
+export type { LinearAppOptions, LinearChannelOptions, LinearChannelRuntime, LinearEvent, LinearEventCallback, LinearEventKey, LinearEventResult, LinearPayloadFor, } from "./types.js";
+export { LinearRateLimitError } from "./graphql.js";
+/** Adapt verified Linear webhooks into HTTP channel messages or skips. */
+export declare function linearChannel(options?: LinearChannelOptions): HttpChannel;
+/** Forget the cached webhook secret; for tests. */
+export declare function resetLinearWebhookSecret(): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/channels/linear/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,WAAW,EAMjB,MAAM,kBAAkB,CAAC;AA2B1B,OAAO,KAAK,EAEV,oBAAoB,EAIrB,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAgBpD,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,WAAW,CAiD7E;AA0FD,mDAAmD;AACnD,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}

package/dist/channels/linear/index.js

@@ -0,0 +1,466 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { channelThreadId, httpChannel, } from "../http/index.js";
+import { studioUrl } from "../http/studio.js";
+import { isJsonValue } from "../message-schema.js";
+import { immutableCopy, requireTextContent } from "../runtime.js";
+import { logger } from "../../runtime/log.js";
+import { validateChannelIconPath } from "../../runtime/channel-icon.js";
+import { ConnectionNotFoundError, DEPLOYMENT_ID_ENV, connections, } from "../../connections.js";
+import { linearAppConnectionSlug } from "./connections.js";
+import { addLinearSessionUrl, commentInAgentSession, createLinearActivity, createLinearComment, linearAppUser, } from "./graphql.js";
+import { SUPPORTED_EVENT_KEYS, linearEventSchema, linearReceiptSchema, } from "./schema.js";
+export { LinearRateLimitError } from "./graphql.js";
+const SESSION_KEYS = new Set([
+    "AgentSessionEvent.created",
+    "AgentSessionEvent.prompted",
+]);
+const APP_OPTION_KEYS = new Set([
+    "name",
+    "description",
+    "icon",
+    "teams",
+]);
+/** Adapt verified Linear webhooks into HTTP channel messages or skips. */
+export function linearChannel(options = {}) {
+    const handlers = { ...options.onEvent };
+    // A misspelled option would silently widen what starts runs.
+    const unknown = Object.keys(options.app ?? {}).filter((key) => !APP_OPTION_KEYS.has(key));
+    if (unknown.length)
+        throw new TypeError(`unknown Linear app option ${unknown.join(", ")}; use ${[...APP_OPTION_KEYS].join(", ")}`);
+    if (options.app)
+        validateAppDisplay(options.app);
+    const teams = options.app?.teams?.map((team) => team.trim().toLowerCase());
+    if (teams?.length === 0 || teams?.some((team) => !team))
+        throw new TypeError("Linear app.teams must list team keys; omit it to allow every team");
+    const filters = {
+        teams,
+        ignoreBots: options.ignoreBots ?? true,
+        sessions: options.sessions ?? true,
+    };
+    const channel = httpChannel({
+        provider: "linear",
+        ...(options.multitaskStrategy && {
+            multitaskStrategy: options.multitaskStrategy,
+        }),
+        providerConfig: {
+            // Deploy subscribes the app's webhook to the handled events.
+            events: handledEvents(handlers, filters.sessions),
+            ...(options.app && { app: appConfig(options.app) }),
+        },
+        verify: verifyLinearRequest,
+        parse: (context) => parseLinearRequest(context, handlers, channelName(channel), filters),
+        input: (_message, rawEvent) => handlerInput(handlers, rawEvent, channelName(channel)),
+        post: postReply,
+        onDelivered: acknowledgeSession,
+        onCancelled: confirmStopped,
+        onError: reportError,
+        onPaused: notifyPaused,
+    });
+    // Served at /channels/{name}/icon; deploy points the app's icon at it.
+    const icon = options.app?.icon;
+    return icon === undefined
+        ? channel
+        : Object.assign(channel, {
+            icon: validateChannelIconPath(icon, "Linear app.icon"),
+        });
+}
+function channelName(channel) {
+    return channel.name ?? channel.kind;
+}
+/** The events deploy subscribes the app's webhook to. */
+function handledEvents(handlers, sessions) {
+    const handled = Object.keys(handlers).filter((key) => handlers[key] !== undefined);
+    return [...new Set([...handled, ...(sessions ? SESSION_KEYS : [])])].sort();
+}
+/** Check how the app looks against Linear's rules, before deploy sends it. */
+function validateAppDisplay({ name, description, icon }) {
+    if (name !== undefined) {
+        const trimmed = name.trim();
+        if (trimmed.length < 2 ||
+            trimmed.length > 80 ||
+            /linear|https?:\/\//i.test(trimmed))
+            throw new TypeError('Linear app.name must be 2-80 characters, without "Linear" or a URL');
+    }
+    if (description !== undefined &&
+        (!description.trim() || description.trim().length > 1000))
+        throw new TypeError("Linear app.description must be 1-1000 characters");
+    if (icon !== undefined)
+        validateChannelIconPath(icon, "Linear app.icon");
+}
+/** The app options deploy reads, without unset fields. */
+function appConfig(app) {
+    return Object.fromEntries(Object.entries({
+        name: app.name?.trim(),
+        description: app.description?.trim(),
+        icon: app.icon && validateChannelIconPath(app.icon, "Linear app.icon"),
+        teams: app.teams && [...app.teams],
+    }).filter(([, value]) => value !== undefined));
+}
+/** How long the webhook secret read from Agent Auth is reused. */
+const SECRET_TTL_MS = 5 * 60_000;
+/** How long a missing secret is remembered, so unsigned traffic can't hammer Agent Auth. */
+const MISSING_SECRET_TTL_MS = 60_000;
+let webhookSecret;
+/**
+ * The app's webhook signing secret: `LINEAR_WEBHOOK_SECRET` when set,
+ * otherwise the agent secret stored at
+ * `mda/linear-app/{deployment}/webhook-secret`. Only a missing connection
+ * reads as `undefined`; credential store failures propagate.
+ */
+async function linearWebhookSecret() {
+    const override = process.env.LINEAR_WEBHOOK_SECRET?.trim();
+    if (override)
+        return override;
+    const deploymentId = process.env[DEPLOYMENT_ID_ENV]?.trim();
+    if (!deploymentId)
+        return undefined;
+    if (webhookSecret && webhookSecret.expiresAt > Date.now())
+        return webhookSecret.value;
+    // Concurrent deliveries share the in-flight read.
+    const entry = {
+        value: connections
+            .resolveDeploymentSecret(linearAppConnectionSlug(deploymentId, "webhook-secret"))
+            .catch((error) => {
+            if (error instanceof ConnectionNotFoundError) {
+                entry.expiresAt = Date.now() + MISSING_SECRET_TTL_MS;
+                logger.error("Linear webhook secret is not stored in Agent Auth");
+                return undefined;
+            }
+            // Read again on the next delivery rather than caching a failure.
+            if (webhookSecret === entry)
+                webhookSecret = undefined;
+            throw error;
+        }),
+        expiresAt: Date.now() + SECRET_TTL_MS,
+    };
+    webhookSecret = entry;
+    return entry.value;
+}
+/** Forget the cached webhook secret; for tests. */
+export function resetLinearWebhookSecret() {
+    webhookSecret = undefined;
+}
+/**
+ * How far a delivery's `webhookTimestamp` may be from now. Linear recommends
+ * rejecting older payloads, so a captured delivery can't be replayed.
+ */
+const WEBHOOK_TOLERANCE_MS = 60_000;
+async function verifyLinearRequest({ request, rawBody, }) {
+    // Reject unsigned deliveries before reading the secret from Agent Auth.
+    const signature = request.headers.get("linear-signature") ?? "";
+    if (!/^[0-9a-f]{64}$/i.test(signature))
+        return false;
+    const secret = await linearWebhookSecret();
+    if (!secret)
+        return false;
+    if (!timingSafeEqual(createHmac("sha256", secret).update(rawBody).digest(), Buffer.from(signature, "hex")))
+        return false;
+    return isFresh(rawBody);
+}
+/** Whether a signed delivery was sent within the replay window. */
+function isFresh(rawBody) {
+    let timestamp;
+    try {
+        timestamp = JSON.parse(new TextDecoder().decode(rawBody)).webhookTimestamp;
+    }
+    catch {
+        return false;
+    }
+    return (typeof timestamp === "number" &&
+        Math.abs(Date.now() - timestamp) <= WEBHOOK_TOLERANCE_MS);
+}
+const EVENT_KEYS = new Set(SUPPORTED_EVENT_KEYS);
+/**
+ * Whether another app or an integration made the change. The delivery's actor
+ * says who acted. An issue's or comment's `botActor` is the bot that created
+ * it, so it names the actor only when the event is its creation.
+ */
+function byBot(event) {
+    const actor = event.payload.actor;
+    if (typeof actor?.type === "string" && actor.type.toLowerCase() !== "user")
+        return true;
+    if (event.key === "Issue.update")
+        return false;
+    const data = event.payload.data;
+    return data?.botActor !== undefined && data.botActor !== null;
+}
+async function parseLinearRequest({ request }, handlers, channelName, filters) {
+    const receipt = linearReceiptSchema.parse({
+        deliveryId: request.headers.get("linear-delivery"),
+        payload: await request.json(),
+    });
+    const { deliveryId, payload } = receipt;
+    const key = `${payload.type}.${payload.action}`;
+    logger.info(`linear receipt ${JSON.stringify({
+        event: logger.logIdentifier(key),
+        deliveryId: logger.logIdentifier(deliveryId),
+    })}`);
+    // Linear expects a 200 for every delivery it should not retry.
+    const response = Response.json({ status: "received" }, { status: 200 });
+    if (key === "OAuthApp.revoked") {
+        logger.warn("Linear app access was revoked; reinstall it with mda deploy");
+        return { type: "ignore", response };
+    }
+    // Events nothing handles stop here, before run creation. Sessions have a
+    // default handler while they are on.
+    const handled = EVENT_KEYS.has(key) &&
+        ((filters.sessions && SESSION_KEYS.has(key)) ||
+            (Object.hasOwn(handlers, key) &&
+                handlers[key] !== undefined));
+    if (!handled)
+        return { type: "ignore", response };
+    const event = linearEventSchema.parse({ key, deliveryId, payload });
+    // Issues of teams the channel is not limited to start nothing.
+    if (filters.teams &&
+        !(event.team && filters.teams.includes(event.team.key.toLowerCase())))
+        return { type: "ignore", response };
+    if (event.type !== "AgentSessionEvent" && (await ignored(event, filters)))
+        return { type: "ignore", response };
+    // Preserve the original event even if a callback modifies its argument.
+    if (!isJsonValue(event))
+        throw new TypeError("invalid Linear event");
+    const eventSnapshot = immutableCopy(event);
+    // One thread per issue, so the agent keeps the conversation.
+    const message = {
+        threadId: channelThreadId(channelName, `${event.organizationId}/${event.issueId}`),
+        userId: "mda:channel",
+        target: linearTarget(event),
+        deliveryKey: deliveryId,
+    };
+    // Stop in a session cancels the conversation's run.
+    if (event.key === "AgentSessionEvent.prompted" &&
+        event.payload.agentActivity.signal === "stop")
+        return { type: "cancel", message, rawEvent: eventSnapshot, response };
+    // What the run starts with, or how the event answers an interrupt, is
+    // decided once MDA knows whether the thread waits on one.
+    return { type: "message", message, rawEvent: eventSnapshot, response };
+}
+/**
+ * Whether a webhook event starts nothing: another app's change, the app's own
+ * activity, or a comment an agent session already delivers.
+ */
+async function ignored(event, filters) {
+    if (event.type === "AgentSessionEvent")
+        return false;
+    if (filters.ignoreBots && byBot(event))
+        return true;
+    // Linear reports the app's comments as its user's, not as a bot's.
+    const appUser = await linearAppUser();
+    if (event.actor?.id === appUser.id)
+        return true;
+    if (event.key !== "Comment.create")
+        return false;
+    const comment = event.payload.data;
+    if ((comment.user?.id ?? comment.userId) === appUser.id)
+        return true;
+    return filters.sessions && sessionComment(comment, appUser);
+}
+/**
+ * Whether a comment is part of an agent session, which delivers it as a
+ * session event too: one that mentions the app opens a session, and a reply
+ * in a session's thread prompts it.
+ */
+async function sessionComment(comment, appUser) {
+    if (mentionsApp(comment.body, appUser.displayName))
+        return true;
+    return comment.parentId ? commentInAgentSession(comment.parentId) : false;
+}
+function mentionsApp(body, displayName) {
+    if (!displayName)
+        return false;
+    const name = displayName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|[^\\w@])@${name}(?![\\w-])`, "i").test(body);
+}
+/** Where replies go: the issue, and the comment thread or session that asked. */
+function linearTarget(event) {
+    const identifier = event.key === "Comment.create"
+        ? event.payload.data.issue?.identifier
+        : event.type === "AgentSessionEvent"
+            ? event.payload.agentSession.issue?.identifier
+            : event.payload.data.identifier;
+    return {
+        organizationId: event.organizationId,
+        issueId: event.issueId,
+        ...(identifier && { identifier }),
+        // Replies go into the comment's thread; Linear threads one level deep.
+        ...(event.key === "Comment.create" && {
+            commentId: event.payload.data.parentId ?? event.payload.data.id,
+        }),
+        ...(event.sessionId && { sessionId: event.sessionId }),
+    };
+}
+/** What the event's handler starts a run with; `undefined` when it skips or fails. */
+async function handlerInput(handlers, rawEvent, channelName) {
+    const event = linearEvent(rawEvent);
+    if (!event)
+        return undefined;
+    const handler = (Object.hasOwn(handlers, event.key) ? handlers[event.key] : undefined);
+    const receipt = {
+        event: logger.logIdentifier(event.key),
+        deliveryId: logger.logIdentifier(event.deliveryId),
+    };
+    let input;
+    try {
+        input = handler
+            ? await handler(event, { channel: { name: channelName } })
+            : sessionInput(event);
+    }
+    catch (error) {
+        logger.error(`linear callback failed ${JSON.stringify(receipt)} (${logger.safeErrorLabel(error)})`);
+        input = undefined;
+    }
+    if (input === undefined || input === null) {
+        // A session that gets no run would wait for an answer that never comes,
+        // whether it just opened or this is a follow-up in it.
+        if (event.type === "AgentSessionEvent")
+            await say(event.sessionId, {
+                type: "response",
+                body: "I'm not set up to work on this request.",
+            });
+        return undefined;
+    }
+    logger.info(`Linear handler returned run input ${JSON.stringify(receipt)}`);
+    return input;
+}
+/** What a session event starts a run with when no handler decides. */
+function sessionInput(event) {
+    if (event.key === "AgentSessionEvent.created") {
+        const { promptContext, agentSession } = event.payload;
+        return (promptContext?.trim() ||
+            agentSession.comment?.body?.trim() ||
+            agentSession.issue?.title?.trim() ||
+            undefined);
+    }
+    if (event.key === "AgentSessionEvent.prompted")
+        return event.payload.agentActivity.content.body?.trim() || undefined;
+    return undefined;
+}
+/** The parsed event a delivery carries, as handlers may change it. */
+function linearEvent(rawEvent) {
+    if (!rawEvent || typeof rawEvent !== "object" || Array.isArray(rawEvent))
+        return undefined;
+    const event = structuredClone(rawEvent);
+    return EVENT_KEYS.has(event.key) ? event : undefined;
+}
+/** Say something in a session; a failure is logged, never thrown. */
+async function say(sessionId, content, extra = {}) {
+    if (!sessionId)
+        return;
+    try {
+        await createLinearActivity({
+            agentSessionId: sessionId,
+            content,
+            ...extra,
+        });
+    }
+    catch (error) {
+        logger.error(`linear session activity failed (${logger.safeErrorLabel(error)})`);
+    }
+}
+/**
+ * Post the agent's reply: as the session's response when a session asked,
+ * otherwise as a comment in the thread of the comment that started the run.
+ * A post that starts a new thread, such as a scheduled one, comments on the
+ * issue itself.
+ */
+async function postReply(input) {
+    const { target, newThread, ...message } = input;
+    if (!isLinearTarget(target))
+        throw new TypeError("invalid Linear target");
+    const body = requireTextContent(message);
+    if (target.sessionId && !newThread)
+        return createLinearActivity({
+            agentSessionId: target.sessionId,
+            content: { type: "response", body },
+        });
+    return createLinearComment({
+        issueId: target.issueId,
+        body,
+        ...(target.commentId && !newThread && { parentId: target.commentId }),
+    });
+}
+/**
+ * Linear marks a session unresponsive without an activity within seconds, even
+ * while the run waits behind another one: acknowledge it at once, and link a
+ * new session to its thread in Studio.
+ */
+async function acknowledgeSession(target, run) {
+    if (!isLinearTarget(target) || !target.sessionId)
+        return;
+    await say(target.sessionId, { type: "thought", body: "Working on it." }, {
+        ephemeral: true,
+    });
+    const url = studioUrl(run);
+    if (!url || linearEvent(run.rawEvent)?.key !== "AgentSessionEvent.created")
+        return;
+    try {
+        await addLinearSessionUrl(target.sessionId, {
+            label: "LangSmith Studio",
+            url,
+        });
+    }
+    catch (error) {
+        logger.error(`linear session link failed (${logger.safeErrorLabel(error)})`);
+    }
+}
+/** After Stop, Linear waits for a final word from the agent. */
+async function confirmStopped(target) {
+    if (!isLinearTarget(target) || !target.sessionId)
+        return;
+    await say(target.sessionId, { type: "response", body: "Stopped." });
+}
+const ERROR_MESSAGE = "Something went wrong while working on this.";
+/** Tell the session or the issue that the run failed. */
+async function reportError(_error, target) {
+    if (!isLinearTarget(target))
+        return;
+    if (target.sessionId) {
+        await createLinearActivity({
+            agentSessionId: target.sessionId,
+            content: { type: "error", body: ERROR_MESSAGE },
+        });
+        return;
+    }
+    await createLinearComment({
+        issueId: target.issueId,
+        body: ERROR_MESSAGE,
+        ...(target.commentId && { parentId: target.commentId }),
+    });
+}
+/**
+ * The conversation waits on a decision, made in LangSmith Studio: say so with
+ * a link. In a session it asks for input, so the session waits rather than
+ * ends: once the decision is made, the resumed run's answer is the session's
+ * response. Otherwise it is a comment.
+ */
+async function notifyPaused(target, run) {
+    if (!isLinearTarget(target))
+        return;
+    const url = studioUrl(run);
+    const studio = url ? `[LangSmith Studio](${url})` : "LangSmith Studio";
+    const body = run.stopped
+        ? `I need a decision before I continue. Review the pending step in ${studio}.`
+        : `I'm waiting for a decision on an earlier step, so I haven't read this yet. Review the pending step in ${studio}, then ask again.`;
+    if (target.sessionId) {
+        await createLinearActivity({
+            agentSessionId: target.sessionId,
+            content: { type: "elicitation", body },
+        });
+        return;
+    }
+    await createLinearComment({
+        issueId: target.issueId,
+        body,
+        ...(target.commentId && { parentId: target.commentId }),
+    });
+}
+function isLinearTarget(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const { organizationId, issueId, identifier, commentId, sessionId } = value;
+    const nonblank = (field) => typeof field === "string" && field.trim().length > 0;
+    return (nonblank(organizationId) &&
+        nonblank(issueId) &&
+        [identifier, commentId, sessionId].every((field) => field === undefined || nonblank(field)));
+}
+//# sourceMappingURL=index.js.map