managed-deepagents 0.5.0-dev.79 → 0.5.0-dev.81

package/dist/ingress/index.js

@@ -0,0 +1,128 @@
+/**
+ * Managed ingress pipeline: verified inbound event → agent run.
+ *
+ * Providers keep signature verification, event normalization, and reply
+ * transport. This module owns the shared pieces: deterministic thread ids,
+ * trusted loopback invoke with source-provider stamps, and source-thread
+ * existence probes.
+ */
+import { createHash } from "node:crypto";
+import { Client } from "@langchain/langgraph-sdk";
+import { extractAssistantText } from "../channels/assistant-text.js";
+import { CHANNEL_BINDING_KEY, } from "../channels/binding.js";
+import { ChannelError } from "../channels/errors.js";
+import { resolveLoopbackApiKey, resolveLoopbackApiUrl, } from "../identity/loopback.js";
+import { USER_HEADER, INGRESS_SECRET_ENV, INGRESS_SECRET_HEADER, SOURCE_PROVIDER_HEADER, SOURCE_THREAD_HEADER, ORGANIZATION_HEADER, } from "../runtime/auth.js";
+/**
+ * Schedule background work after the provider ACK. Defaults to fire-and-forget
+ * with error logging; tests pass an inline runner.
+ */
+export function scheduleIngressWork(work, options) {
+    const schedule = options.schedule ??
+        ((fn) => {
+            fn().catch((error) => {
+                console.error(`[mda] ${options.label} failed:`, error);
+            });
+        });
+    schedule(work);
+}
+/**
+ * True when an MDA thread already exists for this source-thread key.
+ *
+ * Call with the **resolved** actor (post identity remap) so ownership matches
+ * the thread created on the first run.
+ */
+export async function ingressSourceThreadExists(input) {
+    const ingressSecret = process.env[INGRESS_SECRET_ENV];
+    if (!ingressSecret) {
+        return false;
+    }
+    const client = createIngressLoopbackClient({
+        userId: input.userId,
+        organizationId: input.organizationId,
+        sourceThreadKey: input.sourceThreadKey,
+        ingressSecret,
+    });
+    const threadId = stableThreadId(input.sourceThreadKey);
+    try {
+        await client.threads.get(threadId);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Invoke the managed graph over a trusted loopback with ingress identity stamped.
+ *
+ * Only this path may set `x-mda-source-provider` / `x-mda-source-thread-id`.
+ */
+export async function invokeIngressAgent(input) {
+    const ingressSecret = process.env[INGRESS_SECRET_ENV];
+    if (!ingressSecret) {
+        throw new ChannelError("channel_run_failed", "MDA_INGRESS_SECRET is required for channel agent invocation");
+    }
+    const client = createIngressLoopbackClient({
+        userId: input.userId,
+        organizationId: input.organizationId,
+        sourceThreadKey: input.sourceThreadKey,
+        ingressSecret,
+        sourceProvider: input.sourceProvider ?? input.binding.provider,
+    });
+    const threadId = stableThreadId(input.sourceThreadKey);
+    try {
+        await client.threads.create({
+            threadId,
+            metadata: { owner: input.sourceThreadKey },
+            ifExists: "do_nothing",
+        });
+    }
+    catch {
+        // Some SDK versions use different ifExists semantics; continue and let run fail loudly.
+    }
+    const run = (await client.runs.wait(threadId, input.assistantId, {
+        input: {
+            messages: [{ role: "human", content: input.text }],
+        },
+        config: {
+            configurable: {
+                [CHANNEL_BINDING_KEY]: input.binding,
+            },
+        },
+    }));
+    return {
+        replyText: extractAssistantText(run),
+        runId: run.runId ?? run.run_id,
+        threadId,
+    };
+}
+function createIngressLoopbackClient(input) {
+    const apiUrl = resolveLoopbackApiUrl();
+    const apiKey = resolveLoopbackApiKey();
+    const headers = {
+        [INGRESS_SECRET_HEADER]: input.ingressSecret,
+        [USER_HEADER]: input.userId,
+        [SOURCE_PROVIDER_HEADER]: input.sourceProvider ?? "slack",
+        [SOURCE_THREAD_HEADER]: input.sourceThreadKey,
+    };
+    if (input.organizationId) {
+        headers[ORGANIZATION_HEADER] = input.organizationId;
+    }
+    return new Client({
+        apiUrl,
+        apiKey,
+        defaultHeaders: headers,
+    });
+}
+/** Deterministic LangGraph thread id from a provider source-thread key. */
+export function stableThreadId(sourceThreadKey) {
+    const hex = createHash("sha256").update(sourceThreadKey).digest("hex");
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        `5${hex.slice(13, 16)}`,
+        `a${hex.slice(17, 20)}`,
+        hex.slice(20, 32),
+    ].join("-");
+}
+//# sourceMappingURL=index.js.map

package/dist/ingress/index.js.map

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

package/dist/namespaces.d.ts

@@ -0,0 +1,306 @@
+/**
+ * The first-party primitive namespaces.
+ *
+ * Every provider an agent project can select is reached the same way —
+ * `<primitive>.<provider>(...)` — so the primitive is obvious at the call site
+ * and providers can be added without growing the barrel:
+ *
+ * ```ts
+ * connectors.slack({ on: ["app_mention"] });
+ * connectors.github({
+ *   repositories: [{ repo: "acme/api", path: "api" }],
+ *   events: [{ on: "pull_request.opened", prompt: () => "review" }],
+ * });
+ * sandboxes.langsmith({ defaultTimeout: 600 });
+ * auth.supabase({ projectRef: "abc" });
+ * credentials.github({ read: ["user"] });
+ * connect.github();
+ * connect.google(); // usually inferred from Fleet integration connectors (gmail, …)
+ * connect.microsoft(); // usually inferred (outlook, teams, …)
+ * connect.linkedin(); // usually inferred (connectors.linkedin)
+ * connect.x(); // usually inferred (connectors.x)
+ * ```
+ *
+ * These are the only primitives the managed runtime will mount. A project
+ * cannot contribute its own — `defineExtension` stays internal.
+ */
+import { LangSmithSandbox } from "deepagents";
+import { githubConnector } from "./connectors/github/index.js";
+import { annotationQueues, chatFeedback, examples, feedback, langsmithConnector, prompts, runs, threads, traceViewer } from "./connectors/langsmith/index.js";
+import { type MarketplaceConnectors } from "./connectors/marketplace/index.js";
+import { mcpConnector } from "./connectors/mcp/index.js";
+import { slackConnector } from "./connectors/slack/index.js";
+import { type ToolServerConnectors } from "./connectors/toolserver/index.js";
+import { connect as githubConnect } from "./identity/github/connect-http.js";
+import { credentials as githubCredentials } from "./identity/github/credentials.js";
+import { connect as googleConnect } from "./identity/google/connect-http.js";
+import { type MarketplaceConnect } from "./identity/marketplace/index.js";
+import { connect as linkedinConnect } from "./identity/linkedin/connect-http.js";
+import { connect as microsoftConnect } from "./identity/microsoft/connect-http.js";
+import { connect as slackConnect } from "./identity/slack/connect-http.js";
+import { connect as xConnect } from "./identity/x/connect-http.js";
+import { type LangSmithSandboxOptions, type SandboxDefinition } from "./sandbox.js";
+export { auth } from "./identity/index.js";
+/** Execution environments the agent's shell runs in. Exported from `sandbox/`. */
+export declare const sandboxes: {
+    langsmith(options?: LangSmithSandboxOptions): SandboxDefinition<typeof LangSmithSandbox>;
+};
+/**
+ * `connectors.langsmith` — the connector factory plus its capability builders.
+ *
+ * Call `connectors.langsmith({ capabilities })` to declare the connector; use
+ * the attached builders / presets to compose grants without a second import.
+ *
+ * Builder properties are typed as `typeof` the exported functions so hover
+ * docs stay on those symbols (`runs`, `chatFeedback`, …) rather than being
+ * restated here.
+ *
+ * @see {@link langsmithConnector}
+ */
+export type LangSmithConnectorsNamespace = typeof langsmithConnector & {
+    readonly runs: typeof runs;
+    readonly feedback: typeof feedback;
+    readonly examples: typeof examples;
+    readonly annotationQueues: typeof annotationQueues;
+    readonly prompts: typeof prompts;
+    readonly threads: typeof threads;
+    readonly chatFeedback: typeof chatFeedback;
+    readonly traceViewer: typeof traceViewer;
+};
+/**
+ * Integrations: tools, HTTP routes, sandbox provisioning, inbound events, and
+ * named messaging. Exported from `connectors/*`.
+ *
+ * Most entries are the LangSmith tool server's built-in integrations —
+ * `connectors.gmail`, `connectors.linear`, `connectors.googleSheets`, … — whose
+ * tools resolve against the connection the workspace already manages in
+ * LangSmith. They are spread from the catalog so adding an integration is one
+ * entry there rather than a line here as well. Marketplace bridges
+ * (`connectors.notion`, `connectors.cloudflare`, …) are spread the same way
+ * from the Fleet marketplace catalog. GitHub and Slack are first-class
+ * connectors that may also contribute sandbox / Events / messaging.
+ *
+ * `langsmith` doubles as the namespace for its capability builders, so a
+ * project selects grants without a second import.
+ *
+ * Docs live on this interface (not the value) so IDE hover on `connectors.<name>`
+ * stays useful — TypeScript surfaces property docs from the annotation.
+ */
+export interface Connectors extends ToolServerConnectors, MarketplaceConnectors {
+    /**
+     * Declare remote MCP servers (HTTP/SSE) whose tools load at agent-graph
+     * construction. Stdio servers are not supported.
+     *
+     * @example
+     * ```ts
+     * export const connector = connectors.mcp({
+     *   mcpServers: {
+     *     docs: { transport: "http", url: "https://docs.example.com/mcp" },
+     *   },
+     * });
+     * ```
+     *
+     * @see {@link mcpConnector}
+     */
+    mcp: typeof mcpConnector;
+    /**
+     * GitHub tools (via the LangSmith tool server), sandbox repository checkout,
+     * optional `gh` CLI provisioning, and optional GitHub App webhook Events.
+     *
+     * Installing the `gh` CLI (the default) leaves tool-server tools off; name
+     * tools via `includeTools` / `excludeTools` or set `installCLI: false` to
+     * expose them. Tool names are typed from the catalog's `github` entry.
+     *
+     * @example
+     * ```ts
+     * export const connector = connectors.github({
+     *   repositories: [{ repo: "acme/api", path: "api" }],
+     *   events: [{ on: "pull_request.opened", prompt: () => "review" }],
+     * });
+     * ```
+     *
+     * @see {@link githubConnector}
+     */
+    github: typeof githubConnector;
+    /**
+     * Slack Events ingress, named messaging, and optional tool-server Slack tools.
+     *
+     * Events (`on`) mount ingress + messaging; `includeTools` / `excludeTools`
+     * enable Slack tool-server tools (names typed from the catalog's `slack`
+     * entry).
+     *
+     * @example
+     * ```ts
+     * export const connector = connectors.slack({ on: ["app_mention"] });
+     * ```
+     *
+     * @see {@link slackConnector}
+     */
+    slack: typeof slackConnector;
+    /**
+     * Capability-delegation connector for external / untrusted callers (browser,
+     * channels, schedules). Declares constrained LangSmith grants; MDA performs
+     * them server-side so the caller never receives `LANGSMITH_API_KEY`.
+     *
+     * Also namespaces the grant builders: `connectors.langsmith.runs(...)`,
+     * `connectors.langsmith.chatFeedback(...)`, …
+     *
+     * @example
+     * ```ts
+     * export const connector = connectors.langsmith({
+     *   capabilities: [connectors.langsmith.traceViewer()],
+     * });
+     * ```
+     *
+     * @see {@link langsmithConnector}
+     */
+    langsmith: LangSmithConnectorsNamespace;
+}
+/**
+ * Integrations: tools, HTTP routes, sandbox provisioning, inbound events, and
+ * named messaging. Exported from `connectors/*`.
+ *
+ * Factories are assigned by reference (same pattern as the Python namespace) so
+ * signatures stay in step with the connector modules. Hover docs come from
+ * {@link Connectors}.
+ */
+export declare const connectors: Connectors;
+/** Third-party token resolvers. Composed into `defineIdentity({ credentials })`. */
+export declare const credentials: {
+    github: typeof githubCredentials;
+};
+/**
+ * First-party Connect-with-X providers for `defineIdentity({ connect })`.
+ *
+ * Docs live on this interface so IDE hover on `connect.<provider>` stays useful.
+ */
+export interface Connect extends MarketplaceConnect {
+    /**
+     * Connect-with-GitHub — link a caller's GitHub account for actor OAuth tokens
+     * used by sandbox git/`gh` and GitHub credentials.
+     *
+     * Usually unnecessary: declaring `connectors.github` on a user-scoped identity
+     * deployment mounts this automatically (same pattern as Google/Microsoft).
+     * Also mounts when a credential chain reads per-user GitHub tokens, or when
+     * listed on `identity.connect`.
+     *
+     * @example
+     * ```ts
+     * export const identity = defineIdentity({
+     *   connect: [connect.github()],
+     * });
+     * ```
+     *
+     * @see {@link githubConnect}
+     */
+    github: typeof githubConnect;
+    /**
+     * Connect-with-Google. Usually unnecessary: declaring Google toolserver
+     * connectors (`connectors.gmail`, `connectors.googleSheets`, …) on a
+     * user-scoped identity deployment mounts this automatically with unioned
+     * scopes.
+     *
+     * @example
+     * ```ts
+     * export const identity = defineIdentity({
+     *   connect: [connect.google()],
+     * });
+     * ```
+     *
+     * @see {@link googleConnect}
+     */
+    google: typeof googleConnect;
+    /**
+     * Connect-with-Microsoft. Usually unnecessary: declaring Microsoft toolserver
+     * connectors (`connectors.outlook`, `connectors.teams`, …) on a user-scoped
+     * identity deployment mounts this automatically with unioned scopes.
+     *
+     * @example
+     * ```ts
+     * export const identity = defineIdentity({
+     *   connect: [connect.microsoft()],
+     * });
+     * ```
+     *
+     * @see {@link microsoftConnect}
+     */
+    microsoft: typeof microsoftConnect;
+    /**
+     * Connect-with-LinkedIn. Usually unnecessary: declaring `connectors.linkedin`
+     * on a user-scoped identity deployment mounts this automatically with
+     * connector-derived scopes.
+     *
+     * @example
+     * ```ts
+     * export const identity = defineIdentity({
+     *   connect: [connect.linkedin()],
+     * });
+     * ```
+     *
+     * @see {@link linkedinConnect}
+     */
+    linkedin: typeof linkedinConnect;
+    /**
+     * Connect-with-X. Usually unnecessary: declaring `connectors.x` on a
+     * user-scoped identity deployment mounts this automatically with
+     * connector-derived scopes (Fleet `twitter-oauth-provider`).
+     *
+     * @example
+     * ```ts
+     * export const identity = defineIdentity({
+     *   connect: [connect.x()],
+     * });
+     * ```
+     *
+     * @see {@link xConnect}
+     */
+    x: typeof xConnect;
+    /**
+     * Connect-with-Slack — link a caller's Slack identity via OIDC for per-user
+     * channel routing and actor mapping.
+     *
+     * Mounts under `/identity/slack/*` when listed on `identity.connect`, or when
+     * a Slack channel routes into a user-scoped deployment.
+     *
+     * @example
+     * ```ts
+     * export const identity = defineIdentity({
+     *   connect: [connect.slack()],
+     * });
+     * ```
+     *
+     * @see {@link slackConnect}
+     */
+    slack: typeof slackConnect;
+}
+/**
+ * Connect-with-X — bind an MDA principal to an external account via OAuth.
+ *
+ * Pass providers into `defineIdentity({ connect: […] })`. Each mounts HTTP
+ * routes under `/identity/{id}/{status,connect,callback,link}` so a caller can
+ * link (or unlink) their account. Outcomes depend on the provider:
+ *
+ * - **Identity link** (Slack) — maps an external person to an MDA user so
+ *   channel ingress can resolve `slack:T:U` → actor.
+ * - **Credential vault** (GitHub, Google, Microsoft, LinkedIn, X) — stores
+ *   per-actor tokens for tools, sandbox git/`gh`, or Fleet toolserver subjects.
+ *
+ * Authors rarely list providers by hand. Prefer inference: a user-scoped
+ * identity plus `connectors.github` / `credentials.github({ read: ["user"] })`,
+ * Slack Events, Google/Microsoft/LinkedIn/X toolserver connectors, or marketplace
+ * bridges (`connectors.notion`, `connectors.neon`, …) mounts the matching
+ * Connect flow automatically. Use this namespace when you need an explicit
+ * opt-in or a custom options bag.
+ *
+ * @example
+ * ```ts
+ * // Explicit (usually unnecessary — inference covers the common cases)
+ * export const identity = defineIdentity({
+ *   connect: [connect.github(), connect.slack()],
+ * });
+ * ```
+ *
+ * @see {@link Connect}
+ */
+export declare const connect: Connect;
+//# sourceMappingURL=namespaces.d.ts.map

package/dist/namespaces.d.ts.map

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

package/dist/namespaces.js

@@ -0,0 +1,127 @@
+/**
+ * The first-party primitive namespaces.
+ *
+ * Every provider an agent project can select is reached the same way —
+ * `<primitive>.<provider>(...)` — so the primitive is obvious at the call site
+ * and providers can be added without growing the barrel:
+ *
+ * ```ts
+ * connectors.slack({ on: ["app_mention"] });
+ * connectors.github({
+ *   repositories: [{ repo: "acme/api", path: "api" }],
+ *   events: [{ on: "pull_request.opened", prompt: () => "review" }],
+ * });
+ * sandboxes.langsmith({ defaultTimeout: 600 });
+ * auth.supabase({ projectRef: "abc" });
+ * credentials.github({ read: ["user"] });
+ * connect.github();
+ * connect.google(); // usually inferred from Fleet integration connectors (gmail, …)
+ * connect.microsoft(); // usually inferred (outlook, teams, …)
+ * connect.linkedin(); // usually inferred (connectors.linkedin)
+ * connect.x(); // usually inferred (connectors.x)
+ * ```
+ *
+ * These are the only primitives the managed runtime will mount. A project
+ * cannot contribute its own — `defineExtension` stays internal.
+ */
+import { LangSmithSandbox } from "deepagents";
+import { githubConnector } from "./connectors/github/index.js";
+import { annotationQueues, chatFeedback, examples, feedback, langsmithConnector, prompts, runs, threads, traceViewer, } from "./connectors/langsmith/index.js";
+import { marketplaceConnectors, } from "./connectors/marketplace/index.js";
+import { mcpConnector } from "./connectors/mcp/index.js";
+import { slackConnector } from "./connectors/slack/index.js";
+import { toolServerConnectors, } from "./connectors/toolserver/index.js";
+import { defineExtension } from "./extension.js";
+import { connect as githubConnect } from "./identity/github/connect-http.js";
+import { credentials as githubCredentials } from "./identity/github/credentials.js";
+import { connect as googleConnect } from "./identity/google/connect-http.js";
+import { marketplaceConnect, } from "./identity/marketplace/index.js";
+import { connect as linkedinConnect } from "./identity/linkedin/connect-http.js";
+import { connect as microsoftConnect } from "./identity/microsoft/connect-http.js";
+import { connect as slackConnect } from "./identity/slack/connect-http.js";
+import { connect as xConnect } from "./identity/x/connect-http.js";
+import {} from "./sandbox.js";
+export { auth } from "./identity/index.js";
+const langsmithSandbox = defineExtension("sandbox", {
+    label: "sandboxes.langsmith",
+    provider: LangSmithSandbox,
+    // Not a schema: a sandbox's options are inferred from the provider class's
+    // own `create(...)` types, so a hand-written one would restate deepagents'
+    // surface and drift from it.
+    args: (options) => options ?? {},
+});
+/** Execution environments the agent's shell runs in. Exported from `sandbox/`. */
+export const sandboxes = {
+    langsmith(options) {
+        return langsmithSandbox(options);
+    },
+};
+const langsmithConnectors = Object.assign(langsmithConnector, {
+    runs,
+    feedback,
+    examples,
+    annotationQueues,
+    prompts,
+    threads,
+    chatFeedback,
+    traceViewer,
+});
+/**
+ * Integrations: tools, HTTP routes, sandbox provisioning, inbound events, and
+ * named messaging. Exported from `connectors/*`.
+ *
+ * Factories are assigned by reference (same pattern as the Python namespace) so
+ * signatures stay in step with the connector modules. Hover docs come from
+ * {@link Connectors}.
+ */
+export const connectors = {
+    ...toolServerConnectors,
+    ...marketplaceConnectors,
+    mcp: mcpConnector,
+    github: githubConnector,
+    slack: slackConnector,
+    langsmith: langsmithConnectors,
+};
+/** Third-party token resolvers. Composed into `defineIdentity({ credentials })`. */
+export const credentials = {
+    github: githubCredentials,
+};
+/**
+ * Connect-with-X — bind an MDA principal to an external account via OAuth.
+ *
+ * Pass providers into `defineIdentity({ connect: […] })`. Each mounts HTTP
+ * routes under `/identity/{id}/{status,connect,callback,link}` so a caller can
+ * link (or unlink) their account. Outcomes depend on the provider:
+ *
+ * - **Identity link** (Slack) — maps an external person to an MDA user so
+ *   channel ingress can resolve `slack:T:U` → actor.
+ * - **Credential vault** (GitHub, Google, Microsoft, LinkedIn, X) — stores
+ *   per-actor tokens for tools, sandbox git/`gh`, or Fleet toolserver subjects.
+ *
+ * Authors rarely list providers by hand. Prefer inference: a user-scoped
+ * identity plus `connectors.github` / `credentials.github({ read: ["user"] })`,
+ * Slack Events, Google/Microsoft/LinkedIn/X toolserver connectors, or marketplace
+ * bridges (`connectors.notion`, `connectors.neon`, …) mounts the matching
+ * Connect flow automatically. Use this namespace when you need an explicit
+ * opt-in or a custom options bag.
+ *
+ * @example
+ * ```ts
+ * // Explicit (usually unnecessary — inference covers the common cases)
+ * export const identity = defineIdentity({
+ *   connect: [connect.github(), connect.slack()],
+ * });
+ * ```
+ *
+ * @see {@link Connect}
+ */
+export const connect = {
+    ...marketplaceConnect,
+    github: githubConnect,
+    google: googleConnect,
+    microsoft: microsoftConnect,
+    linkedin: linkedinConnect,
+    x: xConnect,
+    slack: slackConnect,
+};
+//# sourceMappingURL=namespaces.js.map

package/dist/namespaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespaces.js","sourceRoot":"","sources":["../src/namespaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,kBAAkB,EAClB,OAAO,EACP,IAAI,EACJ,OAAO,EACP,WAAW,GACZ,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,qBAAqB,GAEtB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EACL,oBAAoB,GAErB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAC7E,OAAO,EAAE,WAAW,IAAI,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACpF,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAC7E,OAAO,EACL,kBAAkB,GAEnB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AACnF,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAGN,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAE3C,MAAM,gBAAgB,GAAG,eAAe,CAAC,SAAS,EAAE;IAClD,KAAK,EAAE,qBAAqB;IAC5B,QAAQ,EAAE,gBAAgB;IAC1B,2EAA2E;IAC3E,2EAA2E;IAC3E,6BAA6B;IAC7B,IAAI,EAAE,CAAC,OAAiC,EAAE,EAAE,CAAC,OAAO,IAAI,EAAE;CAC3D,CAAC,CAAC;AAEH,kFAAkF;AAClF,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,SAAS,CACP,OAAiC;QAEjC,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;CACF,CAAC;AAuHF,MAAM,mBAAmB,GAAiC,MAAM,CAAC,MAAM,CACrE,kBAAkB,EAClB;IACE,IAAI;IACJ,QAAQ;IACR,QAAQ;IACR,gBAAgB;IAChB,OAAO;IACP,OAAO;IACP,YAAY;IACZ,WAAW;CACZ,CACF,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAe;IACpC,GAAG,oBAAoB;IACvB,GAAG,qBAAqB;IACxB,GAAG,EAAE,YAAY;IACjB,MAAM,EAAE,eAAe;IACvB,KAAK,EAAE,cAAc;IACrB,SAAS,EAAE,mBAAmB;CAC/B,CAAC;AAEF,oFAAoF;AACpF,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,MAAM,EAAE,iBAAiB;CAC1B,CAAC;AAgHF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,OAAO,GAAY;IAC9B,GAAG,kBAAkB;IACrB,MAAM,EAAE,aAAa;IACrB,MAAM,EAAE,aAAa;IACrB,SAAS,EAAE,gBAAgB;IAC3B,QAAQ,EAAE,eAAe;IACzB,CAAC,EAAE,QAAQ;IACX,KAAK,EAAE,YAAY;CACpB,CAAC"}

package/dist/runtime/auth.d.ts

@@ -1,14 +1,16 @@
 import { Auth } from "@langchain/langgraph-sdk/auth";
-import type { IdentityConfig, IdentityDefinition, RuntimeIdentity } from "../identity/index.js";
+import { type IdentityConfig, type IdentityDefinition, type RuntimeIdentity } from "../identity/index.js";
 /**
- * Reserved transport for the trusted-backend ingress mode. Actor/tenant travel
- * as reserved headers (mapped into `config.configurable` by the generated
+ * Reserved transport for the trusted-backend ingress mode. User/organization
+ * travel as reserved headers (mapped into `config.configurable` by the generated
  * `langgraph.json` allowlist); the ingress secret is validated here and is
  * deliberately **not** allowlisted, so it never reaches `config.configurable`.
  */
 /** Trusted-backend / channel-loopback identity headers (single source of truth). */
-export declare const ACTOR_HEADER = "x-mda-actor-id";
-export declare const TENANT_HEADER = "x-mda-tenant-id";
+export declare const USER_HEADER = "x-mda-user-id";
+export declare const ORGANIZATION_HEADER = "x-mda-organization-id";
+/** Comma- or space-delimited group memberships. */
+export declare const GROUPS_HEADER = "x-mda-groups";
 export declare const INGRESS_SECRET_HEADER = "x-mda-ingress-secret";
 /**
  * Internal channel handoff headers. Accepted only after the ingress secret
@@ -27,9 +29,11 @@ export declare const INGRESS_SECRET_ENV = "MDA_INGRESS_SECRET";
 export interface ManagedUser {
     identity: string;
     permissions: string[];
-    mda_actor_id: string;
-    mda_tenant_id?: string;
-    mda_actor_email?: string;
+    mda_user_id: string;
+    mda_organization_id?: string;
+    mda_user_email?: string;
+    /** Group memberships the ingress asserted; read-only, never an isolation key. */
+    mda_groups?: string[];
     mda_claims?: Record<string, unknown>;
     /** Trusted source provider stamped by managed ingress (never client-supplied). */
     mda_source_provider?: string;
@@ -56,11 +60,11 @@ export declare function buildManagedAuth(identity: IdentityDefinition): Auth;
  * connector route runs behind identity by default, and this is what enforces it.
  */
 export declare function resolveRequestIdentity(cfg: IdentityConfig, request: Request): Promise<RuntimeIdentity>;
-/** LangGraph Store namespace prefix for Slack ↔ actor account links. */
+/** LangGraph Store namespace prefix for Slack ↔ user account links. */
 export declare const IDENTITY_LINKS_STORE_PREFIX = "mda_identity_links";
 /**
  * LangGraph Store namespace prefix for Connect-with-GitHub OAuth tokens.
- * Deployment-wide (keyed by actor id inside the namespace); only the trusted
+ * Deployment-wide (keyed by user id inside the namespace); only the trusted
  * identity-links service principal may read/write it.
  */
 export declare const GITHUB_CREDENTIALS_STORE_PREFIX = "mda_github_credentials";
@@ -68,7 +72,7 @@ export declare const GITHUB_CREDENTIALS_STORE_PREFIX = "mda_github_credentials";
  * Trusted service principal for {@link IDENTITY_LINKS_STORE_PREFIX} Store ops.
  * Stamped by the managed link client together with the ingress secret.
  */
-export declare const IDENTITY_LINKS_SERVICE_ACTOR = "mda:identity-links";
+export declare const IDENTITY_LINKS_SERVICE_USER = "mda:identity-links";
 /**
  * Fail-closed (403) unless the store `namespace` contains the identity segments
  * the memory scope requires as a contiguous ordered prefix (typically after the
@@ -79,8 +83,8 @@ export declare function assertStoreAccess(cfg: IdentityConfig, user: ManagedUser
 export declare function namespaceHasOrderedSegments(namespace: string[], required: string[]): boolean;
 /**
  * Resolve the caller identity for `trusted_backend`: validate the shared ingress
- * secret, then trust the reserved actor/tenant headers. Fail-closed (401) on a
- * missing/invalid secret, a missing actor, or a missing tenant under multi.
+ * secret, then trust the reserved user/organization headers. Fail-closed (401) on a
+ * missing/invalid secret, a missing user, or a missing organization when one is required.
  *
  * Under `mda dev` (`MDA_LOCAL_DEV=1`), requests without a valid ingress secret
  * resolve to a synthetic local service principal so LangGraph Studio can talk
@@ -108,7 +112,7 @@ export declare function tryLocalDevTrustedUser(cfg: IdentityConfig, request: Req
 export declare function threadOwnerKey(cfg: IdentityConfig, user: ManagedUser): string;
 /** True when this deployment exposes guest issuance and the request targets it. */
 export declare function isGuestIssuanceRequest(request: Request, cfg: IdentityConfig): boolean;
-/** True when the request targets a public channel Events ingress route. */
+/** True when the request targets a public connector Events ingress route. */
 export declare function isChannelEventsRequest(request: Request): boolean;
 /** True when the request is a public identity-provider OAuth/OIDC callback. */
 export declare function isIdentityProviderCallbackRequest(request: Request): boolean;