managed-deepagents 0.6.2-dev.8 → 0.7.0

package/README.md

@@ -75,12 +75,6 @@ the model, `--memory agent` opts into deployment-shared durable memory,
 `--channels`) writes `channels/slack.ts`. Every new project includes an
 `identity.ts` that explicitly selects `auth.langsmithApiKey()` authentication.
 
-`mda init my-agent --gateway` runs the agent on
-[LangSmith Gateway](https://docs.langchain.com/langsmith/gateway) — a model
-LangSmith hosts, billed to your workspace's Gateway Credits, authenticated with
-a LangSmith API key instead of a model provider key of your own. It is mutually
-exclusive with `--model`, which names a provider you hold the key for.
-
 ## Evaluate
 
 Managed Deep Agent evals run in Harbor. Install `uv` and Docker before running
@@ -163,11 +157,11 @@ my-agent/
   package.json
   .env                  # local deploy secrets, never committed
   schedules/            # optional managed cron schedules
-  tools/                # optional custom tools
+  tools/                # optional custom tools and MCP declaration
+    mcp.ts              # optional MCP server declaration
   middleware/           # optional middleware
   skills/               # optional skills synced to Context Hub
   sandbox/              # LangSmith sandbox (`mda init` includes this; delete to opt out)
-  connectors/mcp.ts     # optional MCP server declaration
 ```
 
 The CLI copies your project files into the managed build and generates the entry
@@ -241,27 +235,51 @@ export const sandbox = defineSandbox({
 Put `GHCR_TOKEN` in the project `.env` or process environment. Its value is
 used only to reconcile the registry and never enters the build or snapshot.
 
-## MCP Connectors
+## MCP Servers
+
+Add `tools/mcp.ts` to attach MCP servers. The file must export a named `mcp`.
+By default, MDA exposes every tool loaded from each declared
+server. In `mda dev`, an agent-owned connection reads from
+`MDA_DEV_<SLUG>` with the slug uppercased and hyphens changed to underscores.
+Hosted deployments resolve workspace connections from Agent Auth:
 
-Add `connectors/mcp.ts` to attach MCP servers. The file must export a named
-`connector`. By default, MDA exposes every tool loaded from each declared
-server. Supply your own auth via static `headers` when the server requires
-credentials:
+The old `connectors/mcp.ts` file API remains available with a warning during
+`0.7.x`. It will be removed in `0.8.0`.
 
 ```ts
-import { connectors } from "managed-deepagents";
+import { defineMcp, connections } from "managed-deepagents";
 
-export const connector = connectors.mcp({
-  mcpServers: {
+export const mcp = defineMcp({
+  servers: {
     langchainDocs: {
       transport: "http",
       url: "https://docs.langchain.com/mcp",
       includeTools: ["search", "fetch"],
+      connection: connections.get("docs-token", { type: "agent" }),
     },
   },
 });
 ```
 
+For this example, set `MDA_DEV_DOCS_TOKEN`.
+
+A user-owned connection — `connections.get(slug, { type: "user" })` — resolves
+per caller via OAuth. Any runtime access interrupts the run when a grant is
+missing, including access from a custom tool or middleware. Connector
+declarations use the same behavior in a pre-run gate, so all known grants can be
+requested before the first model call. This path works in `mda deploy` and
+`mda dev` when `LANGSMITH_API_KEY` and `LANGSMITH_WORKSPACE_ID` are set and
+the workspace connection rows exist. Use a person principal (for example, a
+Supabase JWT), not Studio’s synthetic service user. OAuth completes on
+LangSmith’s platform callback URL. The local UI must show
+`credential_authorization_required` and resume after the user connects.
+
+Deploy the project first, then provision its connections with
+`mda connections create`. Agent-owned opaque secrets are scoped to that
+deployment, so the command refuses to create one before `mda deploy`.
+`mda deploy` fails when a slug a project declares is missing from the
+workspace.
+
 Use `includeTools` or `excludeTools` inside a server config to select a subset.
 Tool names are raw MCP tool names before the managed `{server}__` prefix is
 applied, so `includeTools: ["search"]` on server `langchainDocs` exposes

package/dist/agent-auth.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Agent Auth client used by `credentials.get` and the pre-run credential gate.
+ *
+ * Talks to the shipped Agent Auth APIs (credentials + oauth-authorization-sessions),
+ * not the aspirational `credentials/mint` endpoint.
+ */
+export declare const AGENT_AUTH_TIMEOUT_MS = 10000;
+export declare const AGENT_AUTH_PROVIDER_PAGE_SIZE = 100;
+export declare const AGENT_AUTH_MAX_PROVIDER_PAGES = 20;
+export interface AgentAuthHttpConfig {
+    apiKey?: string;
+    workspaceId?: string;
+}
+/** Query string for listing credentials filtered by owner and kind. */
+export declare function agentAuthCredentialQuery(options: {
+    ownerType: string;
+    ownerId: string;
+    kind: string;
+    pageSize?: number;
+    cursor?: string;
+}): string;
+export declare function agentAuthHeaders(config: AgentAuthHttpConfig): Record<string, string>;
+/** One Agent Auth HTTP call: no redirects, bounded timeout, JSON body. */
+export declare function requestAgentAuthJson(options: {
+    url: string;
+    init?: Omit<RequestInit, "headers" | "signal">;
+    config: AgentAuthHttpConfig;
+    timeoutMs: number;
+    fetchImpl: typeof fetch;
+}): Promise<{
+    ok: boolean;
+    status: number;
+    body: Record<string, unknown>;
+}>;
+export interface AgentAuthContext {
+    baseUrl: string;
+    /**
+     * Deployment id when present. Required for agent-owned credential lookups;
+     * optional for user-owned OAuth (grants are principal-scoped).
+     */
+    agentId?: string;
+    /** Authenticated caller, used as `owner_id` for user credentials. */
+    principalId: string;
+    apiKey?: string;
+    workspaceId?: string;
+}
+export interface ResolvePrincipalIdentity {
+    provider: string;
+    issuer: string;
+    subject: string;
+}
+/** Drop cached principal resolutions. Test-only. */
+export declare function clearPrincipalResolveCacheForTests(): void;
+/** One credential slug the caller has not granted, with its connect URL. */
+export interface PendingAuthorization {
+    slug: string;
+    connectUrl: string;
+    authId: string;
+}
+export declare class CredentialAuthorizationRequiredError extends Error {
+    readonly slugs: readonly string[];
+    readonly name = "CredentialAuthorizationRequiredError";
+    constructor(slugs: readonly string[]);
+}
+export declare class AgentAuthUnknownProviderError extends Error {
+    readonly slug: string;
+    readonly name = "AgentAuthUnknownProviderError";
+    constructor(slug: string);
+}
+export declare const AGENT_AUTH_PROBLEM_HINT_MAX_CHARS = 200;
+/**
+ * The problem+json fields Agent Auth reserves for the caller: `detail` names
+ * the failure and `remedy` names the fix. Nothing else from a response body is
+ * read, because the rest can quote secret material.
+ *
+ * Both are collapsed to one line and truncated so a long or multi-line body
+ * cannot reshape an error message.
+ */
+export declare function agentAuthProblemHint(body: Record<string, unknown> | undefined): string | undefined;
+/**
+ * Agent Auth could not answer. Callers pass a fixed message; the only part of
+ * a response body that reaches it is the allow-listed problem+json hint, since
+ * an arbitrary body can quote secret material.
+ */
+export declare class CredentialStoreError extends Error {
+    readonly status?: number | undefined;
+    readonly name: string;
+    constructor(message: string, status?: number | undefined, problem?: Record<string, unknown>);
+}
+/** The error for a declared slug that has no workspace connection row. */
+export declare function missingWorkspaceConnectionError(slug: string): CredentialStoreError;
+/**
+ * Read the slug back out of a missing-connection message.
+ *
+ * A run that fails in the gate reaches a channel as a plain string, so this is
+ * the only way back to the slug. It must move with the message it parses.
+ */
+export declare function missingWorkspaceConnectionSlug(text: string): string | undefined;
+export interface WorkspaceConnection {
+    connectionId: string;
+    kind: string;
+    ownerPolicy: string;
+}
+/**
+ * Bound Agent Auth HTTP client. One instance per caller/run; headers, origin,
+ * and the request timeout stay on the instance rather than each call site.
+ */
+export declare class AgentAuth {
+    #private;
+    readonly context: AgentAuthContext;
+    constructor(context: AgentAuthContext, fetchImpl?: typeof fetch, timeoutMs?: number);
+    /**
+     * Resolve a verified external identity to an Agent Auth principal UUID.
+     *
+     * `POST /v1/agent-auth/principals` with `{ provider, issuer, subject }`.
+     * Results are cached per process for the same origin, workspace, and triple.
+     */
+    resolvePrincipal(identity: ResolvePrincipalIdentity): Promise<string>;
+    /** List workspace connections and return the row for `slug`, if any. */
+    findWorkspaceConnection(slug: string): Promise<WorkspaceConnection | undefined>;
+    /** Workspace credential id for an agent-owned opaque secret grant. */
+    findWorkspaceCredentialId(slug: string): Promise<string | undefined>;
+    /**
+     * Resolve the credential id for a secret connection row.
+     *
+     * Agent-owned connection declarations scope the credential to this
+     * deployment. Workspace-owned credentials are deliberately not visible to
+     * deployments.
+     */
+    findSecretCredentialId(connection: WorkspaceConnection, slug: string): Promise<string | undefined>;
+    /** Read a caller-owned opaque secret grant for a workspace connection slug. */
+    readUserSecret(slug: string): Promise<string | undefined>;
+    /** Read a caller-owned opaque secret when the connection row is already loaded. */
+    readUserSecretForConnection(connection: WorkspaceConnection): Promise<string | undefined>;
+    /** Read this deployment's OAuth grant for a workspace connection. */
+    readAgentAccessTokenForConnection(connection: WorkspaceConnection): Promise<string | undefined>;
+    /**
+     * Read the caller's OAuth access token for a slug without starting a session.
+     *
+     * Reads never mint, so a caller can be probed repeatedly — on every replay of
+     * an interrupted node, for instance — without leaving authorization sessions
+     * behind.
+     *
+     * @returns The access token, or `undefined` when the caller must connect.
+     */
+    readUserAccessToken(slug: string): Promise<string | undefined>;
+    /** Read a caller OAuth token when the connection row is already loaded. */
+    readUserAccessTokenForConnection(connection: WorkspaceConnection): Promise<string | undefined>;
+    /**
+     * Start an OAuth authorization session for a slug the caller has not granted.
+     *
+     * @returns The pending session, including the user-facing connect URL.
+     */
+    startAuthorizationSession(slug: string): Promise<PendingAuthorization>;
+    /** oauth-providers has no slug filter, so the match is made across pages. */
+    resolveOAuthProviderId(slug: string): Promise<string>;
+    /** The credential key is `credential_id`, never `id`. */
+    findCredentialId(options: {
+        ownerType: string;
+        ownerId: string;
+        kind: string;
+        slug: string;
+    }): Promise<string | undefined>;
+    /** @returns The secret, or `undefined` when Agent Auth has no value (404). */
+    readSecret(credentialId: string): Promise<string | undefined>;
+}
+//# sourceMappingURL=agent-auth.d.ts.map

package/dist/agent-auth.d.ts.map

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