@intx/tools-mail 0.1.2 → 0.3.0

package/dist/handlers.js

@@ -0,0 +1,329 @@
+// Per-tool handler factories for the five mail tools. Each factory takes
+// the bound MessageTransport and returns a closed-over ToolHandler.
+//
+// Keeping the factories at this granularity (one per tool, pure
+// (MessageTransport) → ToolHandler) is deliberate: the package's
+// public surface in index.ts resolves the transport once at handler-init
+// and wires the handlers in a single place. The factories themselves
+// carry no resolver vocabulary, so a future per-tool composition can
+// reuse them unchanged.
+//
+// (MESSAGE.md § Mail Tools)
+import { type } from "arktype";
+import { InterchangeType } from "@intx/types/runtime";
+// ---------------------------------------------------------------------------
+// Argument schemas
+// ---------------------------------------------------------------------------
+const SendArgs = type({
+    to: "string | string[]",
+    "type?": InterchangeType,
+    "content?": "string",
+    "payload?": "Record<string, unknown>",
+    "subject?": "string",
+    "inReplyTo?": "string",
+});
+const ReplyArgs = type({
+    ref: { uid: "number", mailbox: "string" },
+    "type?": InterchangeType,
+    "content?": "string",
+    "payload?": "Record<string, unknown>",
+});
+const SearchArgs = type({
+    "mailbox?": "string",
+    "query?": "Record<string, unknown>",
+    "limit?": "number",
+});
+const ReadArgs = type({
+    ref: { uid: "number", mailbox: "string" },
+    "parts?": "string",
+});
+const WaitArgs = type({
+    "query?": "Record<string, unknown>",
+    "timeout?": "number",
+    "mailbox?": "string",
+});
+// ---------------------------------------------------------------------------
+// Individual tool handlers
+// ---------------------------------------------------------------------------
+export function makeMailSendHandler(transport) {
+    return async (call, signal) => {
+        const args = SendArgs(call.arguments);
+        if (args instanceof type.errors) {
+            return errorResult(call.id, args.summary);
+        }
+        const { content, payload } = args;
+        if (content !== undefined && payload !== undefined) {
+            return errorResult(call.id, "provide either 'content' or 'payload', not both");
+        }
+        const outbound = {
+            to: args.to,
+            type: args.type ?? "conversation.message",
+        };
+        if (args.subject !== undefined) {
+            outbound.subject = args.subject;
+        }
+        if (content !== undefined) {
+            outbound.content = content;
+        }
+        if (payload !== undefined) {
+            outbound.payload = payload;
+        }
+        if (args.inReplyTo !== undefined) {
+            outbound.inReplyTo = args.inReplyTo;
+        }
+        let receipt;
+        try {
+            receipt = await transport.send(outbound, signal);
+        }
+        catch (cause) {
+            return errorResult(call.id, `send_failed: ${cause instanceof Error ? cause.message : String(cause)}`, "send_failed");
+        }
+        return { callId: call.id, content: { messageId: receipt.messageId } };
+    };
+}
+export function makeMailReplyHandler(transport) {
+    return async (call, signal) => {
+        const args = ReplyArgs(call.arguments);
+        if (args instanceof type.errors) {
+            return errorResult(call.id, args.summary);
+        }
+        const messageRef = args.ref;
+        // Fetch the parent message to retrieve threading headers.
+        let parentHeaders;
+        try {
+            parentHeaders = await transport.fetchHeaders(messageRef, signal);
+        }
+        catch (cause) {
+            return errorResult(call.id, `failed to fetch parent message: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        const { content, payload } = args;
+        if (content !== undefined && payload !== undefined) {
+            return errorResult(call.id, "provide either 'content' or 'payload', not both");
+        }
+        const outbound = {
+            to: parentHeaders.from,
+            type: args.type ?? "conversation.message",
+            inReplyTo: parentHeaders.messageId,
+        };
+        // Carry forward the subject if available.
+        if (parentHeaders.subject !== undefined) {
+            outbound.subject = parentHeaders.subject;
+        }
+        if (content !== undefined) {
+            outbound.content = content;
+        }
+        if (payload !== undefined) {
+            outbound.payload = payload;
+        }
+        // OutboundMessage does not carry a References field; the transport
+        // builds the threading chain from inReplyTo when delivering the
+        // reply.
+        let receipt;
+        try {
+            receipt = await transport.send(outbound, signal);
+        }
+        catch (cause) {
+            return errorResult(call.id, `send_failed: ${cause instanceof Error ? cause.message : String(cause)}`, "send_failed");
+        }
+        return { callId: call.id, content: { messageId: receipt.messageId } };
+    };
+}
+export function makeMailSearchHandler(transport) {
+    return async (call, signal) => {
+        const args = SearchArgs(call.arguments);
+        if (args instanceof type.errors) {
+            return errorResult(call.id, args.summary);
+        }
+        const mailbox = args.mailbox ?? "INBOX";
+        const query = args.query ?? {};
+        const limit = args.limit ?? 20;
+        let refs;
+        try {
+            refs = await transport.search(mailbox, query, signal);
+        }
+        catch (cause) {
+            const msg = cause instanceof Error ? cause.message : String(cause);
+            const code = msg.includes("does not exist")
+                ? "invalid_mailbox"
+                : "invalid_query";
+            return errorResult(call.id, msg, code);
+        }
+        const limited = refs.slice(0, limit);
+        // Fetch summary headers for each result.
+        const summaries = await Promise.all(limited.map(async (ref) => {
+            try {
+                const headers = await transport.fetchHeaders(ref, signal);
+                return {
+                    ref,
+                    from: headers.from,
+                    subject: headers.subject,
+                    date: headers.date,
+                    interchangeType: headers.interchangeType,
+                    messageId: headers.messageId,
+                };
+            }
+            catch {
+                return { ref };
+            }
+        }));
+        return { callId: call.id, content: { results: summaries } };
+    };
+}
+export function makeMailReadHandler(transport) {
+    return async (call, signal) => {
+        const args = ReadArgs(call.arguments);
+        if (args instanceof type.errors) {
+            return errorResult(call.id, args.summary);
+        }
+        const messageRef = args.ref;
+        const parts = args.parts ?? "payload";
+        if (parts === "headers") {
+            let headers;
+            try {
+                headers = await transport.fetchHeaders(messageRef, signal);
+            }
+            catch (cause) {
+                return errorResult(call.id, `not_found: ${cause instanceof Error ? cause.message : String(cause)}`, "not_found");
+            }
+            return { callId: call.id, content: { headers } };
+        }
+        if (parts === "full") {
+            let message;
+            try {
+                message = await transport.fetchFull(messageRef, signal);
+            }
+            catch (cause) {
+                return errorResult(call.id, `not_found: ${cause instanceof Error ? cause.message : String(cause)}`, "not_found");
+            }
+            return {
+                callId: call.id,
+                content: {
+                    headers: message.headers,
+                    content: message.content,
+                    payload: message.payload,
+                    signatureStatus: message.signatureStatus,
+                    flags: message.flags,
+                },
+            };
+        }
+        if (parts === "payload") {
+            let message;
+            try {
+                message = await transport.fetchFull(messageRef, signal);
+            }
+            catch (cause) {
+                return errorResult(call.id, `not_found: ${cause instanceof Error ? cause.message : String(cause)}`, "not_found");
+            }
+            if (message.payload !== undefined) {
+                return { callId: call.id, content: { payload: message.payload } };
+            }
+            // Conversation message — return content field.
+            return {
+                callId: call.id,
+                content: {
+                    content: message.content,
+                    interchangeType: message.headers.interchangeType,
+                },
+            };
+        }
+        // Specific MIME part path (e.g. "1.3").
+        let part;
+        try {
+            part = await transport.fetchPart(messageRef, parts, signal);
+        }
+        catch (cause) {
+            return errorResult(call.id, `invalid_part: ${cause instanceof Error ? cause.message : String(cause)}`, "invalid_part");
+        }
+        return {
+            callId: call.id,
+            content: {
+                contentType: part.contentType,
+                encoding: part.encoding,
+                content: new TextDecoder().decode(part.content),
+            },
+        };
+    };
+}
+export function makeMailWaitHandler(transport) {
+    return async (call, signal) => {
+        const args = WaitArgs(call.arguments);
+        if (args instanceof type.errors) {
+            return errorResult(call.id, args.summary);
+        }
+        const query = args.query ?? {};
+        const timeoutSeconds = args.timeout ?? 120;
+        const mailbox = args.mailbox ?? "INBOX";
+        // Check for an existing match first.
+        const existing = await transport.search(mailbox, query, signal);
+        const firstMatch = existing[0];
+        if (firstMatch !== undefined) {
+            const message = await transport.fetchFull(firstMatch, signal);
+            return {
+                callId: call.id,
+                content: {
+                    ref: firstMatch,
+                    from: message.headers.from,
+                    subject: message.headers.subject,
+                    content: message.content,
+                },
+            };
+        }
+        // No match yet — watch for new arrivals.
+        return new Promise((resolve) => {
+            let settled = false;
+            const unsubscribe = transport.watch(mailbox, (event) => {
+                if (settled)
+                    return;
+                if (event.type !== "exists")
+                    return;
+                // Match against the query's 'from' field (the primary use case).
+                if (typeof query.from === "string" &&
+                    event.headers.from !== query.from) {
+                    return;
+                }
+                settled = true;
+                unsubscribe();
+                clearTimeout(timer);
+                void (async () => {
+                    const ref = { uid: event.uid, mailbox };
+                    const message = await transport.fetchFull(ref, signal);
+                    resolve({
+                        callId: call.id,
+                        content: {
+                            ref,
+                            from: message.headers.from,
+                            subject: message.headers.subject,
+                            content: message.content,
+                        },
+                    });
+                })();
+            });
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                unsubscribe();
+                resolve(errorResult(call.id, `Timed out after ${timeoutSeconds}s waiting for a matching message`, "timeout"));
+            }, timeoutSeconds * 1000);
+            // Respect the abort signal.
+            signal.addEventListener("abort", () => {
+                if (settled)
+                    return;
+                settled = true;
+                unsubscribe();
+                clearTimeout(timer);
+                resolve(errorResult(call.id, "aborted", "aborted"));
+            }, { once: true });
+        });
+    };
+}
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+function errorResult(callId, message, code) {
+    const content = { error: message };
+    if (code !== undefined) {
+        content["code"] = code;
+    }
+    return { callId, content, isError: true };
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import type { ToolDefinition, ToolRunner } from "@intx/types/runtime";
+import type { RuntimeCapabilities } from "@intx/types/runtime-capabilities";
+export { TOOL_DEFINITIONS } from "./definitions.js";
+export type { MailToolName } from "./definitions.js";
+export interface MailToolsOptions {
+    capabilities: RuntimeCapabilities;
+}
+export interface MailTools extends ToolRunner {
+    readonly definitions: ToolDefinition[];
+    dispose(): Promise<void>;
+}
+export declare function createMailTools(opts: MailToolsOptions): MailTools;

package/dist/index.js

@@ -0,0 +1,71 @@
+// Public surface for @intx/tools-mail.
+//
+// createMailTools resolves the bound agent's MessageTransport from the
+// supplied RuntimeCapabilities once at handler-init and wires the five
+// mail handlers around it. The returned MailTools satisfies the
+// ToolRunner contract the harness consumes.
+import { TOOL_DEFINITIONS } from "./definitions.js";
+import { makeMailReadHandler, makeMailReplyHandler, makeMailSearchHandler, makeMailSendHandler, makeMailWaitHandler, } from "./handlers.js";
+export { TOOL_DEFINITIONS } from "./definitions.js";
+export function createMailTools(opts) {
+    // Resolve the transport once at handler-init. The lifecycle contract is
+    // "request once at handler-init, hold the handle for the deploy
+    // lifetime"; the handler factories below close over the resolved
+    // handle and do not re-consult capabilities.
+    const transport = opts.capabilities.resolve("mail.transport");
+    const handlers = new Map([
+        ["mail_send", makeMailSendHandler(transport)],
+        ["mail_reply", makeMailReplyHandler(transport)],
+        ["mail_search", makeMailSearchHandler(transport)],
+        ["mail_read", makeMailReadHandler(transport)],
+        ["mail_wait", makeMailWaitHandler(transport)],
+    ]);
+    let disposed = false;
+    return {
+        definitions: TOOL_DEFINITIONS,
+        async run(call, signal) {
+            const handler = handlers.get(call.name);
+            if (handler === undefined) {
+                // This branch is unreachable in the sidecar composition: the
+                // agent's `resolveTools` dispatches `call.name` to the owning
+                // bundle by definition.name, so only names this runner
+                // declared can ever reach `run`. It exists so callers that
+                // use createMailTools as a standalone ToolRunner (rather than
+                // through `defineMailTools`) get the package's native
+                // object-shaped error.
+                return {
+                    callId: call.id,
+                    content: { error: `Unknown tool: "${call.name}"` },
+                    isError: true,
+                };
+            }
+            try {
+                return await handler(call, signal);
+            }
+            catch (err) {
+                // Match the per-handler errorResult shape so consumers see a
+                // single error-content shape regardless of which path produced
+                // it: { error: <string>, code?: <string> }.
+                const message = err instanceof Error ? err.message : `unknown error: ${String(err)}`;
+                return {
+                    callId: call.id,
+                    content: { error: message },
+                    isError: true,
+                };
+            }
+        },
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            // No-op today: the transport is owned by the host that
+            // constructed it, and the only handler with active resources
+            // (mail_wait subscribes via transport.watch and registers a
+            // setTimeout / abort listener) releases them through the
+            // per-call AbortSignal rather than through this dispose hook.
+            // dispose exists for symmetry with createPosixTools and as a
+            // seam for any future per-package resources; callers must not
+            // rely on it to cancel in-flight tool calls.
+        },
+    };
+}

package/dist/sidecar-bundle.d.ts

@@ -0,0 +1,17 @@
+import { type BaseEnv } from "@intx/agent";
+import type { RuntimeCapabilities } from "@intx/types/runtime-capabilities";
+/**
+ * Env contract for the mail tool bundle. Extends `BaseEnv` with the
+ * host-assembled `capabilities` -- from which the mail tools resolve
+ * `mail.transport` -- and the agent `address`.
+ */
+export interface MailToolEnv extends BaseEnv {
+    capabilities: RuntimeCapabilities;
+    address: string;
+}
+/**
+ * Named export the loader picks up. The id is package-namespaced per
+ * the convention; the model-facing tool names are synthesized by the
+ * loader as `@intx/tools-mail/sidecar-bundle:<def.name>`.
+ */
+export declare const mail: import("@intx/agent").AnnotatedToolFactory<MailToolEnv>;

package/dist/sidecar-bundle.js

@@ -0,0 +1,30 @@
+// Sidecar-bundle entry for `@intx/tools-mail` — the convention-compliant
+// factory the tool-package loader invokes.
+//
+// The bundle consumes the host-assembled runtime capabilities rather than
+// building its own. The host (the sidecar's step-env builder) owns the
+// `RuntimeCapabilities` and puts it on `env.capabilities`; this factory
+// resolves `mail.transport` from it through `createMailTools` instead of
+// re-wrapping a raw transport it was handed separately. The env keys it
+// touches (`capabilities`, `address`) are declared in `requires`.
+import { defineTool } from "@intx/agent";
+import { createMailTools } from "./index.js";
+import { TOOL_DEFINITIONS } from "./definitions.js";
+/**
+ * Named export the loader picks up. The id is package-namespaced per
+ * the convention; the model-facing tool names are synthesized by the
+ * loader as `@intx/tools-mail/sidecar-bundle:<def.name>`.
+ */
+export const mail = defineTool({
+    id: "@intx/tools-mail/sidecar-bundle",
+    requires: ["capabilities", "address"],
+    definitions: TOOL_DEFINITIONS.map((def) => ({ name: def.name })),
+    factory: (env) => {
+        const tools = createMailTools({ capabilities: env.capabilities });
+        return {
+            definitions: tools.definitions,
+            run: (call, signal) => tools.run(call, signal),
+            dispose: () => tools.dispose(),
+        };
+    },
+});

package/package.json

@@ -1,16 +1,39 @@
 {
   "name": "@intx/tools-mail",
-  "version": "0.1.2",
+  "description": "Mail tool runner giving agents mail_send, mail_reply, mail_search, mail_read, and mail_wait",
+  "version": "0.3.0",
   "license": "LGPL-2.1-only",
   "type": "module",
+  "interchange": {
+    "tools": "./dist/sidecar-bundle.js"
+  },
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "intx-src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./sidecar-bundle": {
+      "intx-src": "./src/sidecar-bundle.ts",
+      "types": "./dist/sidecar-bundle.d.ts",
+      "default": "./dist/sidecar-bundle.js"
     }
   },
   "dependencies": {
-    "@intx/types": "0.0.0",
+    "@intx/agent": "0.3.0",
+    "@intx/types": "0.3.0",
     "arktype": "^2.1.29"
+  },
+  "devDependencies": {
+    "@intx/storage-isogit": "0.3.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/definitions.ts

@@ -1,153 +0,0 @@
-// Static definitions for the five mail tools. The catalog generator and the
-// inference director both consume these as inert data — no factory calls,
-// no runtime side effects.
-//
-// (MESSAGE.md § Mail Tools)
-
-import type { ToolDefinition } from "@intx/types/runtime";
-
-export type MailToolName =
-  | "mail_send"
-  | "mail_reply"
-  | "mail_search"
-  | "mail_read"
-  | "mail_wait";
-
-export const TOOL_DEFINITIONS: ToolDefinition[] = [
-  {
-    name: "mail_send",
-    description:
-      "Send mail to another agent or address. Use this to initiate conversations or send mail to other agents.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        to: {
-          type: "string",
-          description: "Recipient address (e.g. agent@local.interchange)",
-        },
-        content: {
-          type: "string",
-          description: "Mail text content",
-        },
-        type: {
-          type: "string",
-          description: "Mail type (default: conversation.message)",
-          default: "conversation.message",
-        },
-        subject: {
-          type: "string",
-          description: "Optional subject line",
-        },
-        inReplyTo: {
-          type: "string",
-          description: "Message-ID of the mail being replied to",
-        },
-      },
-      required: ["to", "content"],
-    },
-  },
-  {
-    name: "mail_reply",
-    description:
-      "Reply to a mail by reference. Addresses the reply to the original sender and sets inReplyTo for threading.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        ref: {
-          type: "object",
-          description: "Mail reference { uid, mailbox }",
-          properties: {
-            uid: { type: "number" },
-            mailbox: { type: "string" },
-          },
-          required: ["uid", "mailbox"],
-        },
-        content: {
-          type: "string",
-          description: "Reply mail text content",
-        },
-        type: {
-          type: "string",
-          description: "Mail type (default: conversation.message)",
-          default: "conversation.message",
-        },
-      },
-      required: ["ref", "content"],
-    },
-  },
-  {
-    name: "mail_search",
-    description: "Search mail in a mailbox. Returns mail summaries.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        mailbox: {
-          type: "string",
-          description: "Mailbox to search",
-          default: "INBOX",
-        },
-        query: {
-          type: "object",
-          description: "Search query (e.g. { from: 'agent@...' })",
-        },
-        limit: {
-          type: "number",
-          description: "Maximum results to return",
-          default: 20,
-        },
-      },
-    },
-  },
-  {
-    name: "mail_read",
-    description: "Read a specific mail by reference.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        ref: {
-          type: "object",
-          description: "Mail reference { uid, mailbox }",
-          properties: {
-            uid: { type: "number" },
-            mailbox: { type: "string" },
-          },
-          required: ["uid", "mailbox"],
-        },
-        parts: {
-          type: "string",
-          description:
-            "What to fetch: 'full', 'headers', 'payload', or a MIME part path",
-          default: "payload",
-        },
-      },
-      required: ["ref"],
-    },
-  },
-  {
-    name: "mail_wait",
-    description:
-      "Wait for mail matching a query to arrive. Blocks until matching mail is delivered or the timeout expires. Use this instead of polling mail_search in a loop.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: {
-          type: "object",
-          description:
-            "Search criteria for the mail to wait for (e.g. { from: 'agent@...' })",
-        },
-        timeout: {
-          type: "number",
-          description:
-            "Maximum seconds to wait before returning a timeout error",
-          default: 120,
-        },
-        mailbox: {
-          type: "string",
-          description: "Mailbox to watch",
-          default: "INBOX",
-        },
-      },
-      required: ["query"],
-    },
-  },
-];