@intx/tools-mail 0.2.2 → 0.4.0

package/README.md

@@ -14,7 +14,11 @@ its definitions alongside other bundles.
 import { createMailTools } from "@intx/tools-mail";
 import { defineMailTools } from "@intx/harness";
 
-const mailFactory = defineMailTools(() => createMailTools({ capabilities }));
+const mailTools = createMailTools({ capabilities });
+const mailFactory = defineMailTools(
+  () => mailTools,
+  mailTools.definitions.map((def) => ({ name: def.name })),
+);
 const def = defineAgent({ ..., tools: [mailFactory, posixFactory] });
 ```
 

package/dist/definitions.d.ts

@@ -1,3 +1,3 @@
 import type { ToolDefinition } from "@intx/types/runtime";
-export type MailToolName = "mail_send" | "mail_reply" | "mail_search" | "mail_read" | "mail_wait";
+export type MailToolName = "mail_send" | "mail_reply" | "mail_search" | "mail_read" | "mail_wait" | "mail_flag" | "mail_expunge";
 export declare const TOOL_DEFINITIONS: ToolDefinition[];

package/dist/definitions.js

@@ -1,4 +1,4 @@
-// Static definitions for the five mail tools. The catalog generator and the
+// Static definitions for the mail tools. The catalog generator and the
 // inference director both consume these as inert data — no factory calls,
 // no runtime side effects.
 //
@@ -134,4 +134,42 @@ export const TOOL_DEFINITIONS = [
             required: ["query"],
         },
     },
+    {
+        name: "mail_flag",
+        description: "Set or clear IMAP flags on a message (system flags like \\Seen or \\Deleted, or custom keywords). Provide EITHER 'set' to add flags OR 'clear' to remove them -- one direction per call. To consume a message, flag it \\Deleted then call mail_expunge. An error result means the mailbox was NOT changed.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ref: {
+                    type: "object",
+                    description: "Mail reference { uid, mailbox }",
+                    properties: {
+                        uid: { type: "number" },
+                        mailbox: { type: "string" },
+                    },
+                    required: ["uid", "mailbox"],
+                },
+                set: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: 'Flags to add (e.g. ["\\\\Deleted"])',
+                },
+                clear: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Flags to remove",
+                },
+            },
+            required: ["ref"],
+        },
+    },
+    {
+        name: "mail_expunge",
+        description: "Permanently remove every message flagged \\Deleted from the INBOX and return the uids removed. Flag a message \\Deleted with mail_flag first. An error result means nothing was removed.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
 ];

package/dist/handlers.d.ts

@@ -5,3 +5,5 @@ export declare function makeMailReplyHandler(transport: MessageTransport): ToolH
 export declare function makeMailSearchHandler(transport: MessageTransport): ToolHandler;
 export declare function makeMailReadHandler(transport: MessageTransport): ToolHandler;
 export declare function makeMailWaitHandler(transport: MessageTransport): ToolHandler;
+export declare function makeMailFlagHandler(transport: MessageTransport): ToolHandler;
+export declare function makeMailExpungeHandler(transport: MessageTransport): ToolHandler;

package/dist/handlers.js

@@ -1,4 +1,4 @@
-// Per-tool handler factories for the five mail tools. Each factory takes
+// Per-tool handler factories for the mail tools. Each factory takes
 // the bound MessageTransport and returns a closed-over ToolHandler.
 //
 // Keeping the factories at this granularity (one per tool, pure
@@ -42,6 +42,12 @@ const WaitArgs = type({
     "timeout?": "number",
     "mailbox?": "string",
 });
+const FlagArgs = type({
+    ref: { uid: "number", mailbox: "string" },
+    "set?": "string[]",
+    "clear?": "string[]",
+});
+const ExpungeArgs = type({});
 // ---------------------------------------------------------------------------
 // Individual tool handlers
 // ---------------------------------------------------------------------------
@@ -104,6 +110,15 @@ export function makeMailReplyHandler(transport) {
             to: parentHeaders.from,
             type: args.type ?? "conversation.message",
             inReplyTo: parentHeaders.messageId,
+            // The full RFC 5322 References chain for a reply is the parent's own
+            // References plus the parent's Message-Id. The parent is in hand here
+            // (fetched above for its threading headers), so build the complete
+            // ancestry rather than leaving the transport to derive a single-element
+            // chain from inReplyTo alone.
+            references: [
+                ...(parentHeaders.references ?? []),
+                parentHeaders.messageId,
+            ],
         };
         // Carry forward the subject if available.
         if (parentHeaders.subject !== undefined) {
@@ -115,9 +130,6 @@ export function makeMailReplyHandler(transport) {
         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);
@@ -317,6 +329,65 @@ export function makeMailWaitHandler(transport) {
         });
     };
 }
+export function makeMailFlagHandler(transport) {
+    return async (call, signal) => {
+        const args = FlagArgs(call.arguments);
+        if (args instanceof type.errors) {
+            return errorResult(call.id, args.summary);
+        }
+        const set = args.set ?? [];
+        const clear = args.clear ?? [];
+        // Reject an empty mutation at the boundary: a call with neither direction
+        // does nothing, and firing an empty flag write would still round-trip to
+        // the supervisor as a pointless commit.
+        if (set.length === 0 && clear.length === 0) {
+            return errorResult(call.id, "provide flags in 'set' or 'clear'");
+        }
+        // One direction per call. Adding and removing flags in one call would be
+        // two separate supervisor round-trips; if the first landed and the second
+        // failed, the error's "mailbox unchanged" contract would be a lie. Keeping
+        // each call a single mutation makes that contract unconditionally true.
+        if (set.length > 0 && clear.length > 0) {
+            return errorResult(call.id, "provide 'set' or 'clear', not both -- call mail_flag once per direction");
+        }
+        try {
+            if (set.length > 0) {
+                await transport.setFlags(args.ref, set, signal);
+            }
+            else {
+                await transport.clearFlags(args.ref, clear, signal);
+            }
+        }
+        catch (cause) {
+            // A rejection means the supervisor did not apply the mutation, so the
+            // mailbox is unchanged. Surface that so the model does not assume the
+            // flag stuck (and then expunge expecting the message gone).
+            return errorResult(call.id, `flag not applied: ${cause instanceof Error ? cause.message : String(cause)}`, "flag_failed");
+        }
+        return { callId: call.id, content: { ok: true } };
+    };
+}
+export function makeMailExpungeHandler(transport) {
+    return async (call, signal) => {
+        const args = ExpungeArgs(call.arguments);
+        if (args instanceof type.errors) {
+            return errorResult(call.id, args.summary);
+        }
+        // The warm agent owns exactly one mailbox; expunge sweeps its INBOX.
+        let outcome;
+        try {
+            outcome = await transport.expunge("INBOX", signal);
+        }
+        catch (cause) {
+            // A rejection means nothing was removed; the mailbox is unchanged.
+            return errorResult(call.id, `expunge not applied: ${cause instanceof Error ? cause.message : String(cause)}`, "expunge_failed");
+        }
+        return {
+            callId: call.id,
+            content: { ok: true, expungedUids: outcome.expungedUids },
+        };
+    };
+}
 // ---------------------------------------------------------------------------
 // Helper
 // ---------------------------------------------------------------------------

package/dist/index.js

@@ -1,11 +1,11 @@
 // 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
+// supplied RuntimeCapabilities once at handler-init and wires the 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";
+import { makeMailExpungeHandler, makeMailFlagHandler, 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
@@ -19,6 +19,8 @@ export function createMailTools(opts) {
         ["mail_search", makeMailSearchHandler(transport)],
         ["mail_read", makeMailReadHandler(transport)],
         ["mail_wait", makeMailWaitHandler(transport)],
+        ["mail_flag", makeMailFlagHandler(transport)],
+        ["mail_expunge", makeMailExpungeHandler(transport)],
     ]);
     let disposed = false;
     return {

package/dist/sidecar-bundle.d.ts

@@ -1,13 +1,12 @@
 import { type BaseEnv } from "@intx/agent";
-import type { MessageTransport } from "@intx/types/runtime";
+import type { RuntimeCapabilities } from "@intx/types/runtime-capabilities";
 /**
  * Env contract for the mail tool bundle. Extends `BaseEnv` with the
- * harness-level fields the mail tools depend on at handler-init time.
- * Compatible by structure with `@intx/harness`'s `MailEnv` so a host
- * that already provides that env can pass it straight through.
+ * host-assembled `capabilities` -- from which the mail tools resolve
+ * `mail.transport` -- and the agent `address`.
  */
 export interface MailToolEnv extends BaseEnv {
-    transport: MessageTransport;
+    capabilities: RuntimeCapabilities;
     address: string;
 }
 /**

package/dist/sidecar-bundle.js

@@ -1,13 +1,15 @@
 // Sidecar-bundle entry for `@intx/tools-mail` — the convention-compliant
 // factory the tool-package loader invokes.
 //
-// The factory declares the env keys it touches (`transport`, `address`)
-// via `defineTool`'s `requires`. The host populates those slots in the
-// per-instance env; the factory wraps the existing `createMailTools`
-// implementation.
+// 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 { createRuntimeCapabilities } from "@intx/types/runtime-capabilities";
 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
@@ -15,12 +17,10 @@ import { createMailTools } from "./index.js";
  */
 export const mail = defineTool({
     id: "@intx/tools-mail/sidecar-bundle",
-    requires: ["transport", "address"],
+    requires: ["capabilities", "address"],
+    definitions: TOOL_DEFINITIONS.map((def) => ({ name: def.name })),
     factory: (env) => {
-        const capabilities = createRuntimeCapabilities({
-            "mail.transport": env.transport,
-        });
-        const tools = createMailTools({ capabilities });
+        const tools = createMailTools({ capabilities: env.capabilities });
         return {
             definitions: tools.definitions,
             run: (call, signal) => tools.run(call, signal),

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@intx/tools-mail",
-  "version": "0.2.2",
+  "description": "Mail tool runner giving agents mail_send, mail_reply, mail_search, mail_read, and mail_wait",
+  "version": "0.4.0",
   "license": "LGPL-2.1-only",
   "type": "module",
   "interchange": {
@@ -19,10 +20,13 @@
     }
   },
   "dependencies": {
-    "@intx/agent": "0.2.2",
-    "@intx/types": "0.2.2",
+    "@intx/agent": "0.4.0",
+    "@intx/types": "0.4.0",
     "arktype": "^2.1.29"
   },
+  "devDependencies": {
+    "@intx/storage-isogit": "0.4.0"
+  },
   "files": [
     "dist",
     "README.md",