@atomicmail/langchain 0.3.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atomic Mail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+---
+description: Use @atomicmail/langchain to run Atomic Mail register, jmap_request, and help as LangChain tools.
+---
+
+# @atomicmail/langchain
+
+`@atomicmail/langchain` exposes Atomic Mail as LangChain tools while reusing the
+same shared runtime used by MCP and AgentSkill. It provides both:
+
+- a ready-to-use tools array (`createAtomicMailTools`)
+- a toolkit class (`AtomicMailToolkit`)
+
+## Install
+
+```bash
+npm install @atomicmail/langchain
+```
+
+## Tool surfaces
+
+```ts
+import { createAtomicMailTools, AtomicMailToolkit } from "@atomicmail/langchain";
+
+const tools = await createAtomicMailTools();
+
+const toolkit = await AtomicMailToolkit.create();
+const registerTool = toolkit.registerTool;
+const jmapTool = toolkit.jmapRequestTool;
+const helpTool = toolkit.helpTool;
+```
+
+## Available tools
+
+| Tool | Purpose |
+| --- | --- |
+| `register` | PoW signup / idempotent register with optional `forced` and `credentials_dir`. |
+| `jmap_request` | Run JMAP request from `ops` or `ops_file` with vars and optional attachments. |
+| `help` | Return built-in docs topics bundled with the package. |
+
+## Behavior parity guarantees
+
+The LangChain wrapper enforces the same core behavior as MCP and AgentSkill:
+
+- register idempotency and `forced` semantics are delegated to shared `AgentSession.register`
+- exactly one of `ops` or `ops_file` is required for `jmap_request`
+- `dry_run` with attachments is rejected
+- user vars are validated with `^[A-Z][A-Z0-9_]*$`
+- post-register flow includes cron guidance (`help` topic `cron`)
+
+## Credentials and environment
+
+Defaults match the rest of the stack:
+
+- credential directory: `ATOMIC_MAIL_CREDENTIALS_DIR` or `~/.atomicmail`
+- auth API: `ATOMIC_MAIL_AUTH_URL`
+- JMAP API: `ATOMIC_MAIL_API_URL`
+- PoW salt: `ATOMIC_MAIL_SCRYPT_SALT`
+- API key override: `ATOMIC_MAIL_API_KEY`
+
+`credentials_dir` can be passed per tool call for multi-account use.
+
+## Example
+
+```ts
+import { createAtomicMailTools } from "@atomicmail/langchain";
+
+const [register, jmapRequest, help] = await createAtomicMailTools();
+
+await register.invoke({ username: "myagent" });
+
+const inbox = await jmapRequest.invoke({
+  ops_file: "list_inbox.json",
+});
+
+const docs = await help.invoke({ topic: "presets" });
+console.log(inbox, docs);
+```

package/esm/_dnt.polyfills.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Based on [import-meta-ponyfill](https://github.com/gaubee/import-meta-ponyfill),
+ * but instead of using npm to install additional dependencies,
+ * this approach manually consolidates cjs/mjs/d.ts into a single file.
+ *
+ * Note that this code might be imported multiple times
+ * (for example, both dnt.test.polyfills.ts and dnt.polyfills.ts contain this code;
+ *  or Node.js might dynamically clear the cache and then force a require).
+ * Therefore, it's important to avoid redundant writes to global objects.
+ * Additionally, consider that commonjs is used alongside esm,
+ * so the two ponyfill functions are stored independently in two separate global objects.
+ */
+import { createRequire } from "node:module";
+import { type URL } from "node:url";
+declare global {
+    interface ImportMeta {
+        /** A string representation of the fully qualified module URL. When the
+         * module is loaded locally, the value will be a file URL (e.g.
+         * `file:///path/module.ts`).
+         *
+         * You can also parse the string as a URL to determine more information about
+         * how the current module was loaded. For example to determine if a module was
+         * local or not:
+         *
+         * ```ts
+         * const url = new URL(import.meta.url);
+         * if (url.protocol === "file:") {
+         *   console.log("this module was loaded locally");
+         * }
+         * ```
+         */
+        url: string;
+        /**
+         * A function that returns resolved specifier as if it would be imported
+         * using `import(specifier)`.
+         *
+         * ```ts
+         * console.log(import.meta.resolve("./foo.js"));
+         * // file:///dev/foo.js
+         * ```
+         *
+         * @param specifier The module specifier to resolve relative to `parent`.
+         * @param parent The absolute parent module URL to resolve from.
+         * @returns The absolute (`file:`) URL string for the resolved module.
+         */
+        resolve(specifier: string, parent?: string | URL | undefined): string;
+        /** A flag that indicates if the current module is the main module that was
+         * called when starting the program under Deno.
+         *
+         * ```ts
+         * if (import.meta.main) {
+         *   // this was loaded as the main module, maybe do some bootstrapping
+         * }
+         * ```
+         */
+        main: boolean;
+        /** The absolute path of the current module.
+         *
+         * This property is only provided for local modules (ie. using `file://` URLs).
+         *
+         * Example:
+         * ```
+         * // Unix
+         * console.log(import.meta.filename); // /home/alice/my_module.ts
+         *
+         * // Windows
+         * console.log(import.meta.filename); // C:\alice\my_module.ts
+         * ```
+         */
+        filename: string;
+        /** The absolute path of the directory containing the current module.
+         *
+         * This property is only provided for local modules (ie. using `file://` URLs).
+         *
+         * * Example:
+         * ```
+         * // Unix
+         * console.log(import.meta.dirname); // /home/alice
+         *
+         * // Windows
+         * console.log(import.meta.dirname); // C:\alice
+         * ```
+         */
+        dirname: string;
+    }
+}
+type NodeRequest = ReturnType<typeof createRequire>;
+type NodeModule = NonNullable<NodeRequest["main"]>;
+interface ImportMetaPonyfillCommonjs {
+    (require: NodeRequest, module: NodeModule): ImportMeta;
+}
+interface ImportMetaPonyfillEsmodule {
+    (importMeta: ImportMeta): ImportMeta;
+}
+interface ImportMetaPonyfill extends ImportMetaPonyfillCommonjs, ImportMetaPonyfillEsmodule {
+}
+export declare let import_meta_ponyfill_commonjs: ImportMetaPonyfillCommonjs;
+export declare let import_meta_ponyfill_esmodule: ImportMetaPonyfillEsmodule;
+export declare let import_meta_ponyfill: ImportMetaPonyfill;
+export {};
+//# sourceMappingURL=_dnt.polyfills.d.ts.map

package/esm/_dnt.polyfills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dnt.polyfills.d.ts","sourceRoot":"","sources":["../src/_dnt.polyfills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAgC,KAAK,GAAG,EAAE,MAAM,UAAU,CAAC;AAGlE,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,UAAU;QAClB;;;;;;;;;;;;;;WAcG;QACH,GAAG,EAAE,MAAM,CAAC;QACZ;;;;;;;;;;;;WAYG;QACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,GAAG,MAAM,CAAC;QACtE;;;;;;;;WAQG;QACH,IAAI,EAAE,OAAO,CAAC;QAEd;;;;;;;;;;;;WAYG;QACH,QAAQ,EAAE,MAAM,CAAC;QAEjB;;;;;;;;;;;;WAYG;QACH,OAAO,EAAE,MAAM,CAAC;KACjB;CACF;AAED,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACpD,KAAK,UAAU,GAAG,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;AACnD,UAAU,0BAA0B;IAClC,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;CACxD;AACD,UAAU,0BAA0B;IAClC,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC;CACtC;AACD,UAAU,kBACR,SAAQ,0BAA0B,EAAE,0BAA0B;CAC/D;AAiBD,eAAO,IAAI,6BAA6B,EA2BnC,0BAA0B,CAAC;AAMhC,eAAO,IAAI,6BAA6B,EA4DnC,0BAA0B,CAAC;AAMhC,eAAO,IAAI,oBAAoB,EAoB1B,kBAAkB,CAAC"}

package/esm/_dnt.polyfills.js

@@ -0,0 +1,127 @@
+/**
+ * Based on [import-meta-ponyfill](https://github.com/gaubee/import-meta-ponyfill),
+ * but instead of using npm to install additional dependencies,
+ * this approach manually consolidates cjs/mjs/d.ts into a single file.
+ *
+ * Note that this code might be imported multiple times
+ * (for example, both dnt.test.polyfills.ts and dnt.polyfills.ts contain this code;
+ *  or Node.js might dynamically clear the cache and then force a require).
+ * Therefore, it's important to avoid redundant writes to global objects.
+ * Additionally, consider that commonjs is used alongside esm,
+ * so the two ponyfill functions are stored independently in two separate global objects.
+ */
+//@ts-ignore
+import { createRequire } from "node:module";
+//@ts-ignore
+import { fileURLToPath, pathToFileURL } from "node:url";
+//@ts-ignore
+import { dirname } from "node:path";
+const defineGlobalPonyfill = (symbolFor, fn) => {
+    if (!Reflect.has(globalThis, Symbol.for(symbolFor))) {
+        Object.defineProperty(globalThis, Symbol.for(symbolFor), {
+            configurable: true,
+            get() {
+                return fn;
+            },
+        });
+    }
+};
+export let import_meta_ponyfill_commonjs = (Reflect.get(globalThis, Symbol.for("import-meta-ponyfill-commonjs")) ??
+    (() => {
+        const moduleImportMetaWM = new WeakMap();
+        return (require, module) => {
+            let importMetaCache = moduleImportMetaWM.get(module);
+            if (importMetaCache == null) {
+                const importMeta = Object.assign(Object.create(null), {
+                    url: pathToFileURL(module.filename).href,
+                    main: require.main == module,
+                    resolve: (specifier, parentURL = importMeta.url) => {
+                        return pathToFileURL((importMeta.url === parentURL
+                            ? require
+                            : createRequire(parentURL))
+                            .resolve(specifier)).href;
+                    },
+                    filename: module.filename,
+                    dirname: module.path,
+                });
+                moduleImportMetaWM.set(module, importMeta);
+                importMetaCache = importMeta;
+            }
+            return importMetaCache;
+        };
+    })());
+defineGlobalPonyfill("import-meta-ponyfill-commonjs", import_meta_ponyfill_commonjs);
+export let import_meta_ponyfill_esmodule = (Reflect.get(globalThis, Symbol.for("import-meta-ponyfill-esmodule")) ??
+    ((importMeta) => {
+        const resolveFunStr = String(importMeta.resolve);
+        const shimWs = new WeakSet();
+        //@ts-ignore
+        const mainUrl = ("file:///" + process.argv[1].replace(/\\/g, "/"))
+            .replace(/\/{3,}/, "///");
+        const commonShim = (importMeta) => {
+            if (typeof importMeta.main !== "boolean") {
+                importMeta.main = importMeta.url === mainUrl;
+            }
+            if (typeof importMeta.filename !== "string") {
+                importMeta.filename = fileURLToPath(importMeta.url);
+                importMeta.dirname = dirname(importMeta.filename);
+            }
+        };
+        if (
+        // v16.2.0+, v14.18.0+: Add support for WHATWG URL object to parentURL parameter.
+        resolveFunStr === "undefined" ||
+            // v20.0.0+, v18.19.0+"" This API now returns a string synchronously instead of a Promise.
+            resolveFunStr.startsWith("async")
+        // enable by --experimental-import-meta-resolve flag
+        ) {
+            import_meta_ponyfill_esmodule = (importMeta) => {
+                if (!shimWs.has(importMeta)) {
+                    shimWs.add(importMeta);
+                    const importMetaUrlRequire = {
+                        url: importMeta.url,
+                        require: createRequire(importMeta.url),
+                    };
+                    importMeta.resolve = function resolve(specifier, parentURL = importMeta.url) {
+                        return pathToFileURL((importMetaUrlRequire.url === parentURL
+                            ? importMetaUrlRequire.require
+                            : createRequire(parentURL)).resolve(specifier)).href;
+                    };
+                    commonShim(importMeta);
+                }
+                return importMeta;
+            };
+        }
+        else {
+            /// native support
+            import_meta_ponyfill_esmodule = (importMeta) => {
+                if (!shimWs.has(importMeta)) {
+                    shimWs.add(importMeta);
+                    commonShim(importMeta);
+                }
+                return importMeta;
+            };
+        }
+        return import_meta_ponyfill_esmodule(importMeta);
+    }));
+defineGlobalPonyfill("import-meta-ponyfill-esmodule", import_meta_ponyfill_esmodule);
+export let import_meta_ponyfill = ((...args) => {
+    const _MODULE = (() => {
+        if (typeof require === "function" && typeof module === "object") {
+            return "commonjs";
+        }
+        else {
+            // eval("typeof import.meta");
+            return "esmodule";
+        }
+    })();
+    if (_MODULE === "commonjs") {
+        //@ts-ignore
+        import_meta_ponyfill = (r, m) => import_meta_ponyfill_commonjs(r, m);
+    }
+    else {
+        //@ts-ignore
+        import_meta_ponyfill = (im) => import_meta_ponyfill_esmodule(im);
+    }
+    //@ts-ignore
+    return import_meta_ponyfill(...args);
+});

package/esm/langchain/mod.d.ts

@@ -0,0 +1,23 @@
+import "../_dnt.polyfills.js";
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import { AgentSession, type ResolvedAgentConfig } from "../lib/mod.js";
+export interface AtomicMailToolkitContext {
+    defaultConfig: ResolvedAgentConfig;
+    defaultSession: AgentSession;
+}
+export interface AtomicMailToolkitOptions {
+    context?: AtomicMailToolkitContext;
+}
+export declare function buildAtomicMailTools(context: AtomicMailToolkitContext): DynamicStructuredTool[];
+export declare function createAtomicMailTools(options?: AtomicMailToolkitOptions): Promise<DynamicStructuredTool[]>;
+export declare class AtomicMailToolkit {
+    readonly tools: DynamicStructuredTool[];
+    private readonly context;
+    private constructor();
+    static create(options?: AtomicMailToolkitOptions): Promise<AtomicMailToolkit>;
+    get registerTool(): DynamicStructuredTool;
+    get jmapRequestTool(): DynamicStructuredTool;
+    get helpTool(): DynamicStructuredTool;
+    dispose(): void;
+}
+//# sourceMappingURL=mod.d.ts.map

package/esm/langchain/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/langchain/mod.ts"],"names":[],"mappings":"AACA,OAAO,sBAAsB,CAAC;AAG9B,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAG9D,OAAO,EACL,YAAY,EAOZ,KAAK,mBAAmB,EAIzB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,mBAAmB,CAAC;IACnC,cAAc,EAAE,YAAY,CAAC;CAC9B;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,wBAAwB,CAAC;CACpC;AAiKD,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,wBAAwB,GAChC,qBAAqB,EAAE,CAMzB;AAED,wBAAsB,qBAAqB,CACzC,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAGlC;AAED,qBAAa,iBAAiB;IAC5B,QAAQ,CAAC,KAAK,EAAE,qBAAqB,EAAE,CAAC;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IAEnD,OAAO;WAKM,MAAM,CACjB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC;IAK7B,IAAI,YAAY,IAAI,qBAAqB,CAExC;IAED,IAAI,eAAe,IAAI,qBAAqB,CAE3C;IAED,IAAI,QAAQ,IAAI,qBAAqB,CAEpC;IAED,OAAO,IAAI,IAAI;CAGhB"}

package/esm/langchain/mod.js

@@ -0,0 +1,157 @@
+// Atomic Mail LangChain toolkit and tool factories.
+import "../_dnt.polyfills.js";
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import { z } from "zod";
+import { AgentSession, createAgentSessionForCredentialDir, DEFAULT_JMAP_USING, getHelp, HELP_TOPIC_LIST, readOpsFile, resolveAgentConfigFromEnv, runJmapRequest, sharedError, USER_VAR_KEY_RE, } from "../lib/mod.js";
+import { postRegisterCronReminder } from "../lib/agent/jmap/help-content/cron.js";
+async function createDefaultContext() {
+    const defaultConfig = await resolveAgentConfigFromEnv();
+    const defaultSession = await AgentSession.create({
+        authUrl: defaultConfig.authUrl,
+        apiUrl: defaultConfig.apiUrl,
+        scryptSalt: defaultConfig.scryptSalt,
+        apiKey: defaultConfig.apiKey,
+        inboxId: defaultConfig.inboxId,
+        credentialDir: defaultConfig.credentialDir,
+        files: defaultConfig.files,
+    });
+    return { defaultConfig, defaultSession };
+}
+async function resolveToolkitSession(ctx, credentialsDir, mode) {
+    if (!credentialsDir) {
+        return ctx.defaultSession;
+    }
+    return await createAgentSessionForCredentialDir(credentialsDir, {
+        authUrl: ctx.defaultConfig.authUrl,
+        apiUrl: ctx.defaultConfig.apiUrl,
+        scryptSalt: ctx.defaultConfig.scryptSalt,
+    }, { requireCredentials: mode === "jmap" });
+}
+function buildRegisterTool(ctx) {
+    return new DynamicStructuredTool({
+        name: "register",
+        description: "PoW signup; writes credentials. Usernames are 5-21 chars. " +
+            "Idempotent for same username and stored inbox; different username is " +
+            "rejected unless forced=true is provided. After success, arrange hourly " +
+            "inbox polling per runtime (help topic cron).",
+        schema: z.object({
+            username: z.string().min(5).max(21),
+            credentials_dir: z.string().optional(),
+            forced: z.boolean().optional(),
+        }),
+        func: async ({ username, credentials_dir, forced }) => {
+            const session = await resolveToolkitSession(ctx, credentials_dir, "register");
+            const result = await session.register(username, { forced });
+            return JSON.stringify({
+                ...result,
+                _next: [postRegisterCronReminder],
+            }, null, 2);
+        },
+    });
+}
+function buildJmapRequestTool(ctx) {
+    return new DynamicStructuredTool({
+        name: "jmap_request",
+        description: "JMAP method-call batch with automatic auth. Exactly one of: " +
+            "ops (JSON string) or ops_file (preset path). Supports vars " +
+            "placeholder substitution and optional local-file attachments.",
+        schema: z.object({
+            credentials_dir: z.string().optional(),
+            using: z.array(z.string()).default([...DEFAULT_JMAP_USING]),
+            ops: z.string().optional(),
+            ops_file: z.string().optional(),
+            vars: z
+                .record(z.string().regex(USER_VAR_KEY_RE), z.string())
+                .optional(),
+            dry_run: z.boolean().optional(),
+            attachments: z
+                .array(z.object({
+                path: z.string(),
+                filename: z.string().optional(),
+                content_type: z.string().optional(),
+            }))
+                .optional(),
+        }),
+        func: async ({ credentials_dir, using, ops, ops_file, vars, dry_run, attachments, }) => {
+            if (ops && ops_file) {
+                throw new Error(sharedError("mcp_ops_mutually_exclusive"));
+            }
+            if (!ops && !ops_file) {
+                throw new Error(sharedError("mcp_ops_required"));
+            }
+            if (dry_run === true && attachments && attachments.length > 0) {
+                throw new Error(sharedError("cli_dry_run_with_attachment"));
+            }
+            const session = await resolveToolkitSession(ctx, credentials_dir, "jmap");
+            const rawOps = ops_file
+                ? await readOpsFile(session.credentialDir, ops_file)
+                : ops;
+            const sourceLabel = ops_file ? `ops_file '${ops_file}'` : "ops";
+            const { ok, status, bodyText } = await runJmapRequest({
+                session,
+                opsJson: rawOps,
+                defaultUsing: using,
+                sourceLabel,
+                vars,
+                dryRun: dry_run,
+                attachments: attachments?.map((item) => ({
+                    path: item.path,
+                    filename: item.filename,
+                    contentType: item.content_type,
+                })),
+            });
+            if (!ok) {
+                throw new Error(`JMAP request failed (HTTP ${status}): ${bodyText}`);
+            }
+            return bodyText;
+        },
+    });
+}
+function buildHelpTool() {
+    return new DynamicStructuredTool({
+        name: "help",
+        description: "Built-in Atomic Mail docs. Call early and often. Topics: " +
+            `${HELP_TOPIC_LIST.join(", ")}, readme.`,
+        schema: z.object({
+            topic: z.string().optional(),
+        }),
+        func: async ({ topic }) => {
+            return await getHelp(topic, "skill");
+        },
+    });
+}
+export function buildAtomicMailTools(context) {
+    return [
+        buildRegisterTool(context),
+        buildJmapRequestTool(context),
+        buildHelpTool(),
+    ];
+}
+export async function createAtomicMailTools(options = {}) {
+    const toolkit = await AtomicMailToolkit.create(options);
+    return toolkit.tools;
+}
+export class AtomicMailToolkit {
+    tools;
+    context;
+    constructor(context) {
+        this.context = context;
+        this.tools = buildAtomicMailTools(context);
+    }
+    static async create(options = {}) {
+        const context = options.context ?? (await createDefaultContext());
+        return new AtomicMailToolkit(context);
+    }
+    get registerTool() {
+        return this.tools[0];
+    }
+    get jmapRequestTool() {
+        return this.tools[1];
+    }
+    get helpTool() {
+        return this.tools[2];
+    }
+    dispose() {
+        this.context.defaultSession.destroy();
+    }
+}

package/esm/lib/agent/auth/agent-auth-http.d.ts

@@ -0,0 +1,26 @@
+export declare function fetchChallenge(authUrl: string): Promise<{
+    challengeJWT: string;
+    challenge: string;
+    difficulty: number;
+}>;
+export interface SessionResponse {
+    sessionJWT: string;
+    apiKey?: string;
+}
+export declare function exchangeSession(authUrl: string, body: {
+    challengeJWT: string;
+    powHex: string;
+    nonce: string;
+    apiKey?: string;
+    username?: string;
+}): Promise<SessionResponse>;
+export declare function fetchCapability(authUrl: string, sessionJWT: string): Promise<string>;
+export interface PerformPoWInput {
+    authUrl: string;
+    scryptSalt: string;
+    apiKey?: string;
+    username?: string;
+    onPowProgress?: (nonce: bigint) => void;
+}
+export declare function performPoWAndSession(input: PerformPoWInput): Promise<SessionResponse>;
+//# sourceMappingURL=agent-auth-http.d.ts.map

package/esm/lib/agent/auth/agent-auth-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-auth-http.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/auth/agent-auth-http.ts"],"names":[],"mappings":"AAKA,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CA8BD;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,eAAe,CAAC,CA8B1B;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAejB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,eAAe,CAAC,CAgB1B"}

package/esm/lib/agent/auth/agent-auth-http.js

@@ -0,0 +1,85 @@
+// auth-service HTTP: challenge → session → capability.
+import { decodeJwtPayload } from "./agent-jwt.js";
+import { solvePow } from "./agent-pow.js";
+export async function fetchChallenge(authUrl) {
+    const res = await fetch(`${authUrl}/api/v1/challenge`, {
+        method: "POST",
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`auth-service /api/v1/challenge returned ${res.status}: ${text}`);
+    }
+    const challengeJWT = readBearerToken(res.headers.get("Authorization"), "Challenge response missing Authorization bearer token.");
+    const payload = decodeJwtPayload(challengeJWT);
+    if (typeof payload.jti !== "string" ||
+        typeof payload.difficulty !== "number") {
+        throw new Error("Challenge JWT payload malformed (missing jti or difficulty).");
+    }
+    return {
+        challengeJWT,
+        challenge: payload.jti,
+        difficulty: payload.difficulty,
+    };
+}
+export async function exchangeSession(authUrl, body) {
+    const { challengeJWT, ...payload } = body;
+    const res = await fetch(`${authUrl}/api/v1/session`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${challengeJWT}`,
+        },
+        body: JSON.stringify(payload),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`auth-service /api/v1/session returned ${res.status}: ${text}`);
+    }
+    const sessionJWT = readBearerToken(res.headers.get("Authorization"), "Session response missing Authorization bearer token.");
+    let data = {};
+    if (text.trim().length > 0) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            throw new Error("auth-service /api/v1/session returned non-JSON body.");
+        }
+    }
+    return {
+        sessionJWT,
+        apiKey: typeof data.apiKey === "string" ? data.apiKey : undefined,
+    };
+}
+export async function fetchCapability(authUrl, sessionJWT) {
+    const res = await fetch(`${authUrl}/api/v1/capability`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${sessionJWT}` },
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`auth-service /api/v1/capability returned ${res.status}: ${text}`);
+    }
+    return readBearerToken(res.headers.get("Authorization"), "Capability response missing Authorization bearer token.");
+}
+export async function performPoWAndSession(input) {
+    const { authUrl, scryptSalt } = input;
+    const { challengeJWT, challenge, difficulty } = await fetchChallenge(authUrl);
+    const { powHex, nonce } = await solvePow(challenge, difficulty, scryptSalt, input.onPowProgress);
+    return exchangeSession(authUrl, {
+        challengeJWT,
+        powHex,
+        nonce,
+        apiKey: input.apiKey,
+        username: input.username,
+    });
+}
+function readBearerToken(headerValue, missingError) {
+    if (!headerValue) {
+        throw new Error(missingError);
+    }
+    const match = /^\s*Bearer\s+(.+?)\s*$/i.exec(headerValue);
+    if (!match || !match[1]) {
+        throw new Error("Authorization header must use Bearer scheme.");
+    }
+    return match[1];
+}

package/esm/lib/agent/auth/agent-jwt.d.ts

@@ -0,0 +1,12 @@
+export declare const SESSION_SAFETY_MARGIN_MS = 60000;
+export declare const CAPABILITY_SAFETY_MARGIN_MS = 20000;
+export interface JwtPayload {
+    exp?: number;
+    iat?: number;
+    jti?: string;
+    inboxId?: string;
+    [key: string]: unknown;
+}
+export declare function decodeJwtPayload<T = JwtPayload>(jwt: string): T;
+export declare function isJwtExpired(jwt: string, marginMs: number): boolean;
+//# sourceMappingURL=agent-jwt.d.ts.map

package/esm/lib/agent/auth/agent-jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-jwt.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/auth/agent-jwt.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAc/D;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQnE"}