managed-deepagents 0.9.6-dev.2 → 0.9.6-dev.21

package/dist/channels/reserved-connections.js

@@ -0,0 +1,55 @@
+import { GITHUB_TOKEN_SLUG, githubAppConnectionSlug, } from "./github/connections.js";
+import { LINEAR_TOKEN_SLUG, linearAppConnectionSlug, } from "./linear/connections.js";
+import { SLACK_BOT_TOKEN_SLUG } from "./slack/connections.js";
+// First-party channels' reserved agent connection names, listed here so
+// resolution does not depend on adapter modules being loaded.
+const builtinReservedConnections = new Map([
+    [
+        GITHUB_TOKEN_SLUG,
+        {
+            resolve: githubAppConnectionSlug,
+            token: "the GitHub App's installation token",
+            actsAs: "act on GitHub as the App",
+        },
+    ],
+    [
+        LINEAR_TOKEN_SLUG,
+        {
+            resolve: linearAppConnectionSlug,
+            token: "the Linear app's token",
+            actsAs: "act in Linear as the app",
+        },
+    ],
+    [
+        SLACK_BOT_TOKEN_SLUG,
+        {
+            // The Slack app's connection has the reserved name itself.
+            resolve: () => SLACK_BOT_TOKEN_SLUG,
+            token: "the Slack app's bot token",
+            actsAs: "act in Slack as the app",
+        },
+    ],
+]);
+/**
+ * Why a channel's reserved agent connection cannot be read as a user
+ * connection, or undefined for any other slug. Reading an app's token as the
+ * person running the agent is not supported yet.
+ */
+export function reservedUserConnectionError(slug) {
+    const reserved = builtinReservedConnections.get(slug);
+    if (!reserved)
+        return undefined;
+    const name = JSON.stringify(slug);
+    return (`${name} is not supported as a user connection yet: it is ${reserved.token}, ` +
+        `an agent connection. Use connections.get(${name}, { type: "agent" }) to ` +
+        `${reserved.actsAs}.`);
+}
+/**
+ * The connection that actually holds a channel's reserved agent connection;
+ * other slugs pass through unchanged.
+ */
+export function reservedAgentConnectionSlug(slug, deploymentId) {
+    const reserved = builtinReservedConnections.get(slug);
+    return reserved && deploymentId ? reserved.resolve(deploymentId) : slug;
+}
+//# sourceMappingURL=reserved-connections.js.map

package/dist/channels/reserved-connections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reserved-connections.js","sourceRoot":"","sources":["../../src/channels/reserved-connections.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D,wEAAwE;AACxE,8DAA8D;AAC9D,MAAM,0BAA0B,GAAG,IAAI,GAAG,CASxC;IACA;QACE,iBAAiB;QACjB;YACE,OAAO,EAAE,uBAAuB;YAChC,KAAK,EAAE,qCAAqC;YAC5C,MAAM,EAAE,0BAA0B;SACnC;KACF;IACD;QACE,iBAAiB;QACjB;YACE,OAAO,EAAE,uBAAuB;YAChC,KAAK,EAAE,wBAAwB;YAC/B,MAAM,EAAE,0BAA0B;SACnC;KACF;IACD;QACE,oBAAoB;QACpB;YACE,2DAA2D;YAC3D,OAAO,EAAE,GAAG,EAAE,CAAC,oBAAoB;YACnC,KAAK,EAAE,2BAA2B;YAClC,MAAM,EAAE,yBAAyB;SAClC;KACF;CACF,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAAY;IACtD,MAAM,QAAQ,GAAG,0BAA0B,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtD,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,CACL,GAAG,IAAI,qDAAqD,QAAQ,CAAC,KAAK,IAAI;QAC9E,4CAA4C,IAAI,0BAA0B;QAC1E,GAAG,QAAQ,CAAC,MAAM,GAAG,CACtB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAY,EACZ,YAAgC;IAEhC,MAAM,QAAQ,GAAG,0BAA0B,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtD,OAAO,QAAQ,IAAI,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1E,CAAC"}

package/dist/channels/resolve-user-endpoint.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A `resolveUser` that is an endpoint. Kept apart from `resolve-user.ts`, which
+ * reaches Agent Auth, so `defineIdentity` can check one with no runtime
+ * dependency.
+ */
+import { type EventEndpoint } from "./http/endpoint.js";
+import type { ResolveUser, ResolveUserRequest } from "./resolve-user.js";
+/**
+ * A `resolveUser` that is an endpoint: a URL, or a `Request` that also carries
+ * headers, such as a credential the service checks. Before a delivery starts a
+ * run, MDA POSTs the {@link ResolveUserRequest} as JSON to the URL, with the
+ * `Request`'s headers, signed when the deployment has `MDA_SERVICE_SECRET`,
+ * with the webhook ID `msg_<deliveryId>_resolve_user`. The service answers
+ * with a `ResolveUserResult`, checked as a function's; `null` or HTTP 204
+ * keeps the channel's own principal. A network error, HTTP 429 or a 5xx is
+ * tried again once. Any other answer, a redirect, or no answer within 5
+ * seconds fails the delivery, as a function that throws does. A retry and a
+ * redelivery keep the webhook ID, so the service answers each request and
+ * never dedupes on it.
+ */
+export declare class ResolveUserEndpoint {
+    #private;
+    constructor(endpoint: EventEndpoint, label: string);
+    /** The service's answer about one delivery's sender, not yet checked. */
+    ask(request: ResolveUserRequest, deliveryId: string): Promise<unknown>;
+}
+/** A declared `resolveUser`: a function, or the service an endpoint names. */
+export type ChannelResolveUser = ResolveUser | ResolveUserEndpoint;
+/**
+ * A declared `resolveUser`, with an endpoint's URL and the deployment's secret
+ * checked; one that is neither a function nor an endpoint throws.
+ */
+export declare function checkedResolveUser(resolveUser: unknown, owner: string): ChannelResolveUser | undefined;
+//# sourceMappingURL=resolve-user-endpoint.d.ts.map

package/dist/channels/resolve-user-endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-user-endpoint.d.ts","sourceRoot":"","sources":["../../src/channels/resolve-user-endpoint.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAazE;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAmB;;IAG9B,YAAY,QAAQ,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAEjD;IAED,yEAAyE;IACzE,GAAG,CAAC,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMrE;CACF;AAED,8EAA8E;AAC9E,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,mBAAmB,CAAC;AAEnE;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,OAAO,EACpB,KAAK,EAAE,MAAM,GACZ,kBAAkB,GAAG,SAAS,CAQhC"}

package/dist/channels/resolve-user-endpoint.js

@@ -0,0 +1,51 @@
+/**
+ * A `resolveUser` that is an endpoint. Kept apart from `resolve-user.ts`, which
+ * reaches Agent Auth, so `defineIdentity` can check one with no runtime
+ * dependency.
+ */
+import { endpointClient, isEventEndpoint, } from "./http/endpoint.js";
+/**
+ * The limits of a `resolveUser` endpoint. The delivery waits on it before MDA
+ * acknowledges it, and Trigger Server gives up on a delivery after 10 seconds,
+ * so two attempts share 5 seconds.
+ */
+const ENDPOINT_LIMITS = {
+    timeoutMs: 5_000,
+    total: true,
+    retryDelaysMs: [500],
+};
+/**
+ * A `resolveUser` that is an endpoint: a URL, or a `Request` that also carries
+ * headers, such as a credential the service checks. Before a delivery starts a
+ * run, MDA POSTs the {@link ResolveUserRequest} as JSON to the URL, with the
+ * `Request`'s headers, signed when the deployment has `MDA_SERVICE_SECRET`,
+ * with the webhook ID `msg_<deliveryId>_resolve_user`. The service answers
+ * with a `ResolveUserResult`, checked as a function's; `null` or HTTP 204
+ * keeps the channel's own principal. A network error, HTTP 429 or a 5xx is
+ * tried again once. Any other answer, a redirect, or no answer within 5
+ * seconds fails the delivery, as a function that throws does. A retry and a
+ * redelivery keep the webhook ID, so the service answers each request and
+ * never dedupes on it.
+ */
+export class ResolveUserEndpoint {
+    #ask;
+    constructor(endpoint, label) {
+        this.#ask = endpointClient(endpoint, label, "resolveUser endpoint");
+    }
+    /** The service's answer about one delivery's sender, not yet checked. */
+    ask(request, deliveryId) {
+        return this.#ask(`msg_${deliveryId}_resolve_user`, JSON.stringify(request), ENDPOINT_LIMITS);
+    }
+}
+/**
+ * A declared `resolveUser`, with an endpoint's URL and the deployment's secret
+ * checked; one that is neither a function nor an endpoint throws.
+ */
+export function checkedResolveUser(resolveUser, owner) {
+    if (resolveUser === undefined || typeof resolveUser === "function")
+        return resolveUser;
+    if (isEventEndpoint(resolveUser))
+        return new ResolveUserEndpoint(resolveUser, `${owner}(...) resolveUser`);
+    throw new TypeError(`${owner}(...) resolveUser must be a function or an endpoint URL`);
+}
+//# sourceMappingURL=resolve-user-endpoint.js.map

package/dist/channels/resolve-user-endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-user-endpoint.js","sourceRoot":"","sources":["../../src/channels/resolve-user-endpoint.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,cAAc,EACd,eAAe,GAIhB,MAAM,oBAAoB,CAAC;AAG5B;;;;GAIG;AACH,MAAM,eAAe,GAAmB;IACtC,SAAS,EAAE,KAAK;IAChB,KAAK,EAAE,IAAI;IACX,aAAa,EAAE,CAAC,GAAG,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,mBAAmB;IACrB,IAAI,CAAc;IAE3B,YAAY,QAAuB,EAAE,KAAa;QAChD,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,EAAE,KAAK,EAAE,sBAAsB,CAAC,CAAC;IACtE,CAAC;IAED,yEAAyE;IACzE,GAAG,CAAC,OAA2B,EAAE,UAAkB;QACjD,OAAO,IAAI,CAAC,IAAI,CACd,OAAO,UAAU,eAAe,EAChC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EACvB,eAAe,CAChB,CAAC;IACJ,CAAC;CACF;AAKD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAAoB,EACpB,KAAa;IAEb,IAAI,WAAW,KAAK,SAAS,IAAI,OAAO,WAAW,KAAK,UAAU;QAChE,OAAO,WAAsC,CAAC;IAChD,IAAI,eAAe,CAAC,WAAW,CAAC;QAC9B,OAAO,IAAI,mBAAmB,CAAC,WAAW,EAAE,GAAG,KAAK,mBAAmB,CAAC,CAAC;IAC3E,MAAM,IAAI,SAAS,CACjB,GAAG,KAAK,yDAAyD,CAClE,CAAC;AACJ,CAAC"}

package/dist/channels/resolve-user.d.ts

@@ -0,0 +1,95 @@
+import { type ResolvePrincipalIdentity } from "../agent-auth.js";
+import { type ChannelActor } from "./actor.js";
+import { type ChannelResolveUser } from "./resolve-user-endpoint.js";
+import { type ChannelMessagingAdapter } from "./runtime.js";
+import type { ChannelMessage, JsonValue } from "./types.js";
+/**
+ * What `resolveUser` gets: the verified sender of a channel delivery. An
+ * endpoint is POSTed it as JSON.
+ *
+ * @experimental This may change in a minor release.
+ */
+export interface ResolveUserRequest<A extends ChannelActor = ChannelActor> {
+    /** Absent when the channel could not verify who sent the delivery. */
+    actor?: A;
+    channel: {
+        name: string;
+    };
+}
+/**
+ * Who a channel delivery runs as.
+ *
+ * - `user`: one of your users. The run gets the principal a backend call with
+ *   `auth: "backend"` gets for the same `id`.
+ * - `identity`: an exact Agent Auth identity, such as the IdP `sub` your web
+ *   users sign in with.
+ * - `reply`: start nothing, and post `message` where the delivery came from, as
+ *   `runtime.channel.post` would.
+ * - `ignore`: start nothing.
+ *
+ * `null` or `undefined` keeps the channel's own principal.
+ *
+ * @experimental This may change in a minor release.
+ */
+export type ResolveUserResult = {
+    type: "user";
+    id: string;
+} | {
+    type: "identity";
+    provider: string;
+    issuer: string;
+    subject: string;
+} | {
+    type: "reply";
+    message: ChannelMessage;
+} | {
+    type: "ignore";
+} | null | undefined;
+/**
+ * Map a channel's verified sender to one of your users.
+ *
+ * @experimental This may change in a minor release.
+ */
+export type ResolveUser<A extends ChannelActor = ChannelActor> = (request: ResolveUserRequest<A>) => ResolveUserResult | Promise<ResolveUserResult>;
+/**
+ * What a delivery does after `resolveUser`.
+ *
+ * @experimental This may change in a minor release.
+ */
+export type ChannelUser = {
+    type: "principal";
+    id: string;
+} | {
+    type: "reply";
+    message: ChannelMessage;
+} | {
+    type: "ignore";
+};
+/**
+ * Ask `resolveUser` about the actor of delivery `deliveryId`; `undefined` keeps
+ * the channel's principal.
+ */
+export declare function resolveChannelUser(resolveUser: ChannelResolveUser | undefined, actor: ChannelActor | undefined, channelName: string, deliveryId: string, resolvePrincipal?: (identity: ResolvePrincipalIdentity) => Promise<string>): Promise<ChannelUser | undefined>;
+/**
+ * The principal a webhook channel's sender runs as when no `resolveUser` maps
+ * them, from {@link actorIdentity}; `undefined` runs the delivery as the
+ * channel. Unlike a mapped user's, it owns no user connections: whoever
+ * completes a connection's sign-in from a public thread would attach their
+ * account to it. Without Agent Auth (`mda dev` without a LangSmith key) the
+ * channel's own user ID stays.
+ */
+export declare function senderPrincipalId(actor: ChannelActor | undefined, resolvePrincipal?: (identity: ResolvePrincipalIdentity) => Promise<string>): Promise<string | undefined>;
+/** Set a channel's own `resolveUser`, which overrides the identity's. */
+export declare function withResolveUser<C extends object>(channel: C, resolveUser: unknown, owner: string): C;
+/**
+ * Post `resolveUser`'s reply through the path `runtime.channel.post` takes,
+ * once per `deliveryKey`.
+ */
+export declare function postReply(message: ChannelMessage, channel: {
+    name: string;
+    provider: string;
+    target: JsonValue;
+    transport: ChannelMessagingAdapter | undefined;
+    deliveryKey?: string;
+}): Promise<void>;
+//# sourceMappingURL=resolve-user.d.ts.map

package/dist/channels/resolve-user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-user.d.ts","sourceRoot":"","sources":["../../src/channels/resolve-user.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,kBAAkB,CAAC;AAO1B,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAK9D,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY;IACvE,sEAAsE;IACtE,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB,IAAI,GACJ,SAAS,CAAC;AAEd;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,IAAI,CAC/D,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAC3B,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAiBpD;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEvB;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,kBAAkB,GAAG,SAAS,EAC3C,KAAK,EAAE,YAAY,GAAG,SAAS,EAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,gBAAgB,GAAE,CAChB,QAAQ,EAAE,wBAAwB,KAC/B,OAAO,CAAC,MAAM,CAA8B,GAChD,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAqClC;AAKD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,YAAY,GAAG,SAAS,EAC/B,gBAAgB,GAAE,CAChB,QAAQ,EAAE,wBAAwB,KAC/B,OAAO,CAAC,MAAM,CAA8B,GAChD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAC9C,OAAO,EAAE,CAAC,EACV,WAAW,EAAE,OAAO,EACpB,KAAK,EAAE,MAAM,GACZ,CAAC,CAQH;AAMD;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE;IACP,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,uBAAuB,GAAG,SAAS,CAAC;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACA,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/channels/resolve-user.js

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import { ConnectionsNotConfiguredError, WORKSPACE_SETTING, } from "../agent-auth.js";
+import { resolveExternalPrincipalId, TRUSTED_BACKEND_PROVIDER, } from "../connections.js";
+import { resolveWorkspaceId } from "../runtime/langsmith-env.js";
+import { logger } from "../runtime/log.js";
+import { actorIdentity } from "./actor.js";
+import { channelMessageSchema, nonblankStringSchema, } from "./message-schema.js";
+import { checkedResolveUser, ResolveUserEndpoint, } from "./resolve-user-endpoint.js";
+import { createRuntimeChannel, } from "./runtime.js";
+/** A result `resolveUser` returns, or an endpoint answers, other than `null`. */
+const resultSchema = z.discriminatedUnion("type", [
+    z.strictObject({ type: z.literal("user"), id: nonblankStringSchema }),
+    z.strictObject({
+        type: z.literal("identity"),
+        provider: nonblankStringSchema,
+        issuer: nonblankStringSchema,
+        subject: nonblankStringSchema,
+    }),
+    z.strictObject({ type: z.literal("reply"), message: channelMessageSchema }),
+    z.strictObject({ type: z.literal("ignore") }),
+]);
+const RESULT_SHAPE = 'resolveUser must return { type: "user", id }, { type: "identity", provider, issuer, subject }, { type: "reply", message }, { type: "ignore" } or null';
+/**
+ * Ask `resolveUser` about the actor of delivery `deliveryId`; `undefined` keeps
+ * the channel's principal.
+ */
+export async function resolveChannelUser(resolveUser, actor, channelName, deliveryId, resolvePrincipal = resolveExternalPrincipalId) {
+    if (!resolveUser)
+        return undefined;
+    const request = {
+        ...(actor && { actor }),
+        channel: { name: channelName },
+    };
+    const answer = resolveUser instanceof ResolveUserEndpoint
+        ? await resolveUser.ask(request, deliveryId)
+        : await resolveUser(request);
+    if (answer === null || answer === undefined)
+        return undefined;
+    // An endpoint's answer is any JSON, and a function's is checked the same way.
+    const parsed = resultSchema.safeParse(answer);
+    if (!parsed.success)
+        throw new TypeError(RESULT_SHAPE);
+    const result = parsed.data;
+    switch (result.type) {
+        case "user":
+            return {
+                type: "principal",
+                id: await resolvePrincipal(appUserIdentity(result.id)),
+            };
+        case "identity":
+            return {
+                type: "principal",
+                id: await resolvePrincipal({
+                    provider: result.provider,
+                    issuer: result.issuer,
+                    subject: result.subject,
+                }),
+            };
+        case "reply":
+            return { type: "reply", message: result.message };
+        case "ignore":
+            return { type: "ignore" };
+        default:
+            throw new TypeError(RESULT_SHAPE);
+    }
+}
+/** Whether the fallback without Agent Auth was logged already. */
+let loggedSenderFallback = false;
+/**
+ * The principal a webhook channel's sender runs as when no `resolveUser` maps
+ * them, from {@link actorIdentity}; `undefined` runs the delivery as the
+ * channel. Unlike a mapped user's, it owns no user connections: whoever
+ * completes a connection's sign-in from a public thread would attach their
+ * account to it. Without Agent Auth (`mda dev` without a LangSmith key) the
+ * channel's own user ID stays.
+ */
+export async function senderPrincipalId(actor, resolvePrincipal = resolveExternalPrincipalId) {
+    const identity = actor && actorIdentity(actor);
+    if (!identity)
+        return undefined;
+    try {
+        return await resolvePrincipal(identity);
+    }
+    catch (error) {
+        if (!(error instanceof ConnectionsNotConfiguredError))
+            throw error;
+        if (!loggedSenderFallback) {
+            loggedSenderFallback = true;
+            logger.warn(`channel senders keep the channel's user ID: ${error.message}`);
+        }
+        return undefined;
+    }
+}
+/** Set a channel's own `resolveUser`, which overrides the identity's. */
+export function withResolveUser(channel, resolveUser, owner) {
+    const checked = checkedResolveUser(resolveUser, owner);
+    if (checked === undefined)
+        return channel;
+    Object.defineProperty(channel, "resolveUser", {
+        value: checked,
+        enumerable: false,
+    });
+    return channel;
+}
+/** Deliveries already replied to; a provider may redeliver one. */
+const repliedDeliveries = new Set();
+const REPLIED_DELIVERIES_KEPT = 1000;
+/**
+ * Post `resolveUser`'s reply through the path `runtime.channel.post` takes,
+ * once per `deliveryKey`.
+ */
+export async function postReply(message, channel) {
+    const { deliveryKey, ...route } = channel;
+    if (deliveryKey !== undefined) {
+        if (repliedDeliveries.has(deliveryKey))
+            return;
+        repliedDeliveries.add(deliveryKey);
+        if (repliedDeliveries.size > REPLIED_DELIVERIES_KEPT)
+            repliedDeliveries.delete(repliedDeliveries.values().next().value);
+    }
+    const { post } = createRuntimeChannel({ ...route, event: null });
+    if (!post) {
+        logger.warn("channel cannot post resolveUser's reply");
+        return;
+    }
+    try {
+        await post(message);
+    }
+    catch (error) {
+        logger.error(`channel resolveUser reply failed (${logger.safeErrorLabel(error)})`);
+    }
+}
+function appUserIdentity(id) {
+    const workspaceId = resolveWorkspaceId();
+    if (!workspaceId)
+        throw new ConnectionsNotConfiguredError(WORKSPACE_SETTING);
+    return {
+        provider: TRUSTED_BACKEND_PROVIDER,
+        issuer: workspaceId,
+        subject: id,
+    };
+}
+//# sourceMappingURL=resolve-user.js.map

package/dist/channels/resolve-user.js.map

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

package/dist/channels/run-input.d.ts

@@ -0,0 +1,88 @@
+/**
+ * What a channel handler starts a run with, in the shapes `agent.invoke`
+ * takes, normalized to the JSON the Agent Server accepts.
+ */
+import { type BaseMessage, type BaseMessageLike } from "@langchain/core/messages";
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import type { JsonObject } from "./manifest.js";
+import type { JsonValue } from "./types.js";
+/**
+ * State to start a run with, as `agent.invoke` takes it: `messages` plus any
+ * other keys of the agent's state.
+ */
+export interface ChannelStateInput {
+    messages?: BaseMessageLike[];
+    [key: string]: unknown;
+}
+/** A user message's text, a message, or state to start a run with. */
+export type ChannelRunInput = string | BaseMessage | ChannelStateInput;
+/**
+ * Run options a handler may set with its input, as `agent.invoke` takes them.
+ *
+ * @experimental This may change in a minor release.
+ */
+export type ChannelRunOptions = Pick<LangGraphRunnableConfig<Record<string, unknown>>, "context"> & {
+    /**
+     * Metadata for the run, such as where it came from, to find it by in
+     * LangSmith. Keys are letters, digits, `_`, `.` or `-` and start with a
+     * letter. Keys the Agent Server and LangSmith set are reserved: those
+     * starting with `mda_`, `langgraph_` or `ls_`, and ids such as `thread_id`,
+     * `session_id`, `run_id` or `user_id`.
+     */
+    metadata?: {
+        readonly [key: string]: JsonValue;
+    };
+    /**
+     * A URL the Agent Server POSTs the finished run to (its status, metadata,
+     * values and any error), as LangGraph's `runs.create({ webhook })` does:
+     * from the server, so it reaches you even if the deployment restarts.
+     * http(s), without credentials in it.
+     */
+    webhook?: string;
+};
+/**
+ * What a channel handler may return to start a run: the input, or the input
+ * with run options, as `agent.invoke(input, options)` takes them.
+ *
+ * @experimental This may change in a minor release.
+ */
+export type ChannelRunResult = ChannelRunInput | readonly [ChannelRunInput, ChannelRunOptions];
+/** A handler's result as the Agent Server takes it. */
+export interface NormalizedRunInput {
+    /** Messages as JSON, each with a `role`. */
+    messages: JsonObject[];
+    /** Other state keys. */
+    state: JsonObject;
+    context?: JsonObject;
+    metadata?: JsonObject;
+    webhook?: string;
+}
+/**
+ * A handler's run input as `startIngressRun` takes it, with MDA's own
+ * `metadata` over the handler's, so a handler can't replace it. Empty state
+ * and metadata are left out.
+ */
+export declare function runStartOptions(input: NormalizedRunInput, metadata?: JsonObject): {
+    messages: JsonObject[];
+    state?: JsonObject;
+    metadata?: JsonObject;
+    webhook?: string;
+};
+/**
+ * Run input MDA starts no run with. Its `reason`, which is also its message,
+ * says what is wrong in a fixed phrase. A key or type it names is bounded to
+ * one log line, so the channel logs the reason, where it logs no other
+ * error's message. A `TypeError`, as invalid run input threw before.
+ */
+export declare class InvalidRunInput extends TypeError {
+    /** Why MDA refused the input, such as `run metadata key is reserved: user_id`. */
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * Normalize what a handler returned. `null` and `undefined` start nothing;
+ * anything else that is not valid input throws an {@link InvalidRunInput}, a
+ * `TypeError`. A run option that is `null` or `undefined` is not set.
+ */
+export declare function normalizeRunInput(value: unknown): NormalizedRunInput | undefined;
+//# sourceMappingURL=run-input.d.ts.map

package/dist/channels/run-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-input.d.ts","sourceRoot":"","sources":["../../src/channels/run-input.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,eAAe,EAErB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAEpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,sEAAsE;AACtE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,WAAW,GAAG,iBAAiB,CAAC;AAEvE;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,uBAAuB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAChD,SAAS,CACV,GAAG;IACF;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;IACjD;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GACxB,eAAe,GACf,SAAS,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAC;AAElD,uDAAuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,wBAAwB;IACxB,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,kBAAkB,EACzB,QAAQ,GAAE,UAAe,GACxB;IACD,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAQA;AASD;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAC5C,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,YAAY,MAAM,EAAE,MAAM,EAIzB;CACF;AAOD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,GACb,kBAAkB,GAAG,SAAS,CAsBhC"}