@aimail/mail 0.1.0-rc.8 → 0.1.7

package/README.md

@@ -0,0 +1,49 @@
+# @aimail/mail
+
+Platform-neutral AIMail config resolution for TypeScript: session id / email
+/ recipient → `agentmail.json` → `AgentConfig`. Pure functions — no framework
+imports, no host wiring.
+
+[![npm](https://img.shields.io/npm/v/@aimail/mail)](https://www.npmjs.com/package/@aimail/mail)
+
+## Install
+
+```bash
+pnpm add @aimail/mail
+```
+
+## What it does
+
+Every adapter needs the same three lookups, sourced from the per-address
+`agentmail.json` bindings under `$AIMAIL_HOME` (default `~/.aimail`):
+
+- `resolveBySessionId(sessionId)` — session-file match first, then agent_id
+  field match. For dsh session uuids and OpenClaw/pi agent ids.
+- `resolveByEmail(email)` — exact registered-address match. Throws when
+  unbound.
+- `resolveByRecipient(recipient)` — exact match first, then persona-strip
+  fallback (recipient local part ends with `.<registered local part>`),
+  mirroring the Python `route_agent_for_email` semantics. Inbound routing for
+  single-in-multi-out platforms (one gateway hosts many agents; mail can
+  arrive at role aliases).
+- `resolveConfig()`-style composition is left to each adapter: the identity
+  source (pointer file / factory ctx / env) is platform-specific by design.
+
+## Scope narrowing
+
+`ResolveOptions.systemId` narrows the scan to one system; when omitted the
+`AIMAIL_SYSTEM_ID` env is used; when that is also empty, all systems under
+`$AIMAIL_HOME/systems/` are scanned (two-level traversal:
+`systems/{system_id}/{address_dir}/agentmail.json`).
+
+Unbound resolutions throw loudly (`no aimail binding for …`) — callers
+surface that to the model/user instead of guessing an identity.
+
+## Related repositories
+
+- [metercai/aimail](https://github.com/metercai/aimail) — the AIMail monorepo:
+  CLI (`cli/`), Python SDK (`pysdk/`), TypeScript SDK (`tssdk/`, you are here),
+  bridge distributions.
+- [metercai/aimail-gateway](https://github.com/metercai/aimail-gateway) — the
+  AIMail gateway: SMTP/HTTP mail service and the address & activation APIs
+  that create the bindings being resolved here.

package/lib/index.d.ts

@@ -1,34 +1,31 @@
-/**
- * @aimail/mail — host-layer AgentMail service (ctx.mail).
- *
- * Provides per-session agentmail config resolution for tool-mail / mail-inbound:
- *   session_id (exec.agent.id) → agentmail.json → ToolCtx {systemId, email}.
- * Config identity = agentmail.json only (single source of truth); the optional
- * AMAIL_SYSTEM_ID env narrows the scan scope.
- */
-import type { Context } from '@deepseek-ai/cordis';
 import { type AgentConfig } from '@aimail/mail-core';
-export declare const name = "mail";
-export declare const inject: never[];
-/** Session-level tool context handed to mail-core tool functions. */
+/** Tool context handed to mail-core tool functions. */
 export interface MailToolCtx {
     systemId: string;
     email?: string;
 }
-/** The ctx.mail service surface. */
-export interface MailService {
-    /** Optional explicit system scope (AMAIL_SYSTEM_ID); empty = scan all. */
-    readonly systemId: string;
-    /** Resolve config for a dsh session id (uuid). Throws when unbound. */
-    resolveConfig(sessionId: string): Promise<AgentConfig>;
-    /** Resolve config by agent email address (inbound routing). Throws when unbound. */
-    resolveByEmail(email: string): Promise<AgentConfig>;
-    /** Resolve a tool context for a session id. Throws when unbound. */
-    resolveCtx(sessionId: string): Promise<MailToolCtx>;
-}
-/** Service identity used by consumers (ctx.get('mail')). */
-export declare const MAIL_SERVICE = "mail";
-export declare function apply(ctx: Context, config?: {
+/** Resolution options shared by every resolver. */
+export interface ResolveOptions {
+    /** Explicit system scope; defaults to the AIMAIL_SYSTEM_ID env (empty = scan all). */
     systemId?: string;
-}): void;
+}
+/**
+ * Resolve config for a platform session/agent id (dsh session uuid, or an
+ * openclaw agentId). Session-file match first, then agent_id field match.
+ * Throws when unbound.
+ */
+export declare function resolveBySessionId(sessionId: string, opts?: ResolveOptions): Promise<AgentConfig>;
+/** Resolve config by the agent's registered email address. Throws when unbound. */
+export declare function resolveByEmail(email: string, opts?: ResolveOptions): Promise<AgentConfig>;
+/**
+ * Inbound recipient routing (mirrors Python route_agent_for_email):
+ *   1. exact registered-address match
+ *   2. persona-prefix fallback: `persona.profile@…` → `profile@…`
+ *      (single-in-multi-out platforms; PERSONA_SUPPORTED=false semantics)
+ * Returns the bound AgentConfig, or undefined when the recipient matches
+ * no agent (caller decides — typically `no_agent` intercept).
+ */
+export declare function resolveByRecipient(email: string, opts?: ResolveOptions): Promise<AgentConfig | undefined>;
+/** Tool context for a session id: {systemId, email}. Throws when unbound. */
+export declare function resolveCtx(sessionId: string, opts?: ResolveOptions): Promise<MailToolCtx>;
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -1,40 +1,117 @@
-import { loadConfigByAgentId, loadConfigByEmail, loadConfigBySessionId, } from '@aimail/mail-core';
-export const name = 'mail';
-export const inject = [];
-/** Service identity used by consumers (ctx.get('mail')). */
-export const MAIL_SERVICE = 'mail';
-export function apply(ctx, config = {}) {
-    const systemId = config.systemId ?? process.env.AMAIL_SYSTEM_ID ?? '';
-    const service = {
-        systemId,
-        async resolveConfig(sessionId) {
-            if (!sessionId)
-                throw new Error('no session id to resolve agentmail config');
-            let cfg = systemId
-                ? await loadConfigBySessionId(systemId, sessionId)
-                : await loadConfigBySessionId('', sessionId);
-            if (!cfg && systemId) {
-                cfg = await loadConfigByAgentId(systemId, sessionId);
-            }
-            if (!cfg) {
-                throw new Error(`no agentmail binding for session ${sessionId} — run bind_agent.py first`);
+/**
+ * @aimail/mail — platform-neutral AIMail config resolution.
+ *
+ * Pure functions: sessionId / email / agentId → agentmail.json → AgentConfig.
+ * No framework imports (no cordis, no dsh-sdk); each platform adapter
+ * (dsh-aimail, openclaw-aimail) binds these to its own identity source.
+ *
+ * Identity = agentmail.json only (single source of truth); the optional
+ * AIMAIL_SYSTEM_ID env narrows the scan scope. Unbound resolutions throw.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { cleanAddr, loadConfigByAgentId, loadConfigByEmail, loadConfigBySessionId, systemDir, } from '@aimail/mail-core';
+function systemIdFrom(opts) {
+    return opts.systemId ?? process.env.AIMAIL_SYSTEM_ID ?? '';
+}
+function unbound(what) {
+    return new Error(`no aimail binding for ${what} — run bind_agent.py first`);
+}
+/** Scan one system dir (or all systems) for every bound AgentConfig. */
+async function scanAllConfigs(systemId) {
+    const root = systemId ? systemDir(systemId) : systemDir('');
+    let names;
+    try {
+        const entries = await fs.readdir(root, { withFileTypes: true });
+        names = entries.filter(e => e.isDirectory()).map(e => e.name);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        const dir = systemId ? root : path.join(root, name);
+        let agentDirs;
+        try {
+            agentDirs = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const ent of agentDirs) {
+            if (!ent.isDirectory())
+                continue;
+            const p = path.join(dir, ent.name, 'agentmail.json');
+            try {
+                out.push(JSON.parse(await fs.readFile(p, 'utf-8')));
             }
-            return cfg;
-        },
-        async resolveCtx(sessionId) {
-            const cfg = await service.resolveConfig(sessionId);
-            return { systemId: cfg.system_id, email: cfg.email };
-        },
-        async resolveByEmail(email) {
-            const cfg = systemId
-                ? await loadConfigByEmail(email, systemId)
-                : await loadConfigByEmail(email);
-            if (!cfg) {
-                throw new Error(`no agentmail binding for ${email} — run bind_agent.py first`);
+            catch {
+                /* skip unreadable */
             }
+        }
+    }
+    return out;
+}
+/**
+ * Resolve config for a platform session/agent id (dsh session uuid, or an
+ * openclaw agentId). Session-file match first, then agent_id field match.
+ * Throws when unbound.
+ */
+export async function resolveBySessionId(sessionId, opts = {}) {
+    if (!sessionId)
+        throw new Error('no session id to resolve aimail config');
+    const systemId = systemIdFrom(opts);
+    let cfg = await loadConfigBySessionId(systemId, sessionId);
+    if (!cfg && systemId)
+        cfg = await loadConfigByAgentId(systemId, sessionId);
+    if (!cfg)
+        throw unbound(`session ${sessionId}`);
+    return cfg;
+}
+/** Resolve config by the agent's registered email address. Throws when unbound. */
+export async function resolveByEmail(email, opts = {}) {
+    const systemId = systemIdFrom(opts);
+    const cfg = await loadConfigByEmail(email, systemId);
+    if (!cfg)
+        throw unbound(email);
+    return cfg;
+}
+/**
+ * Inbound recipient routing (mirrors Python route_agent_for_email):
+ *   1. exact registered-address match
+ *   2. persona-prefix fallback: `persona.profile@…` → `profile@…`
+ *      (single-in-multi-out platforms; PERSONA_SUPPORTED=false semantics)
+ * Returns the bound AgentConfig, or undefined when the recipient matches
+ * no agent (caller decides — typically `no_agent` intercept).
+ */
+export async function resolveByRecipient(email, opts = {}) {
+    const addr = cleanAddr(email);
+    if (!addr)
+        return undefined;
+    // local part from the ORIGINAL address (cleanAddr maps '@' → '_')
+    const local = email.includes('@') ? email.split('@')[0] ?? '' : '';
+    const systemId = systemIdFrom(opts);
+    const cfgs = await scanAllConfigs(systemId);
+    if (!cfgs.length)
+        return undefined;
+    const exact = cfgs.find(c => cleanAddr(c.email ?? '') === addr);
+    if (exact)
+        return exact;
+    // Persona strip: recipient local part ends with ".<registered local part>".
+    if (!local)
+        return undefined;
+    for (const cfg of cfgs) {
+        const baseLocal = (cfg.email ?? '').includes('@')
+            ? cfg.email.split('@')[0] ?? ''
+            : '';
+        if (baseLocal && local.endsWith(`.${baseLocal}`))
             return cfg;
-        },
-    };
-    ctx.provide(MAIL_SERVICE, service);
+    }
+    return undefined;
+}
+/** Tool context for a session id: {systemId, email}. Throws when unbound. */
+export async function resolveCtx(sessionId, opts = {}) {
+    const cfg = await resolveBySessionId(sessionId, opts);
+    return { systemId: cfg.system_id, email: cfg.email };
 }
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@aimail/mail",
-  "description": "AgentMail host service: config resolution + gateway client provisioning for dsh sessions.",
-  "version": "0.1.0-rc.8",
+  "description": "AIMail platform-neutral config resolution: sessionId/email/recipient → agentmail.json → AgentConfig (pure functions, no framework deps).",
+  "version": "0.1.7",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/metercai/dsh-aimail.git",
-    "directory": "packages/mail"
+    "url": "https://github.com/metercai/aimail"
   },
   "type": "module",
   "main": "lib/index.js",
@@ -25,13 +25,16 @@
     "lib/**/*.d.ts"
   ],
   "license": "MIT",
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1"
-  },
+  "peerDependencies": {},
   "dependencies": {
-    "@aimail/mail-core": "^0.1.0-rc.8"
+    "@aimail/mail-core": "^0.1.7"
   },
-  "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1"
-  }
-}
+  "devDependencies": {},
+  "keywords": [
+    "aimail",
+    "agent-mail",
+    "config",
+    "resolution",
+    "binding"
+  ]
+}