@amalgm/tools 0.1.1 → 0.1.2

package/PURPOSE.md

@@ -28,6 +28,8 @@ registry or execution implementation.
 - A **driver** executes actions for one tool type.
 - A **system tool** is an embedder-owned definition projected into the catalog;
   it is not user state.
+- A **notification** is one request to inform the current user; a channel
+  adapter turns that intent into delivery.
 
 ## Axioms
 
@@ -74,6 +76,11 @@ registry or execution implementation.
 18. Tools may store opaque references owned by another product, but neither
     Tools nor a Core adapter silently rewrites that product. A cross-product
     workflow has one explicit product owner.
+19. `notifications.notify_user` addresses only the current user. Callers may
+    supply content and severity, never a recipient or delivery credential.
+20. Notification channels are host capabilities. Tools owns validation and
+    result semantics; an injected channel adapter owns formatting, recipient
+    lookup, credentials, and delivery.
 
 ## Predictable behavior
 

package/README.md

@@ -65,6 +65,14 @@ The read adapter serves the Engine-compatible `GET /toolbox`,
 the same live Toolbox used by CLI and MCP consumers. Mutation routes return
 405 until their legacy record fields can be represented without data loss.
 
+## Notifications
+
+`Notifications` projects the first-party `notifications.notify_user` action
+into the Toolbox. The action validates one channel-neutral request and hands
+it to an injected email delivery adapter; recipient lookup and credentials
+never enter the tool record. `createNotificationsHttpServer` exposes
+`GET /email` as the channel capability document used by the shell.
+
 ## Tool types
 
 - `cli`: executed directly with `spawn`; a shell is never involved.

package/dist/http.d.ts

@@ -29,3 +29,5 @@ declare function createToolboxHttpServer(options?: ToolboxOptions & {
 }): ToolboxHttpServer;
 export { catalogDocument, createToolboxHttpServer };
 export type { ToolboxHttpServer };
+export { createNotificationsHttpServer } from './notifications-http.js';
+export type { NotificationsHttpServer } from './notifications-http.js';

package/dist/http.js

@@ -113,3 +113,4 @@ function createToolboxHttpServer(options = {}) {
     };
 }
 export { catalogDocument, createToolboxHttpServer };
+export { createNotificationsHttpServer } from './notifications-http.js';

package/dist/index.d.ts

@@ -7,5 +7,9 @@ export type { ToolboxHttpServer } from './http.js';
 export { actionId, actionName, id, mcpName } from './ids.js';
 export { actionTools, callMcpTool, createMcpTools, findMcpTool, managementTools, } from './mcp.js';
 export { createMcpServer } from './mcp-server.js';
+export { Notifications, createNotificationsDriver, notificationToolDefinition, } from './notifications.js';
+export type { EmailDelivery, EmailDeliveryReceipt, EmailNotificationRequest, NotificationLevel, NotificationsOptions, } from './notifications.js';
+export { createProxyEmailDelivery } from './proxy-email.js';
+export type { ProxyEmailDeliveryOptions } from './proxy-email.js';
 export { Toolbox } from './toolbox.js';
 export type * from './types.js';

package/dist/index.js

@@ -5,4 +5,6 @@ export { catalogDocument, createToolboxHttpServer } from './http.js';
 export { actionId, actionName, id, mcpName } from './ids.js';
 export { actionTools, callMcpTool, createMcpTools, findMcpTool, managementTools, } from './mcp.js';
 export { createMcpServer } from './mcp-server.js';
+export { Notifications, createNotificationsDriver, notificationToolDefinition, } from './notifications.js';
+export { createProxyEmailDelivery } from './proxy-email.js';
 export { Toolbox } from './toolbox.js';

package/dist/notifications-http.d.ts

@@ -0,0 +1,12 @@
+import type { Notifications } from './notifications.js';
+interface NotificationsHttpServer {
+    listen(port?: number, host?: string): Promise<{
+        port: number;
+    }>;
+    close(): Promise<void>;
+}
+declare function createNotificationsHttpServer(options: {
+    notifications: Notifications;
+}): NotificationsHttpServer;
+export { createNotificationsHttpServer };
+export type { NotificationsHttpServer };

package/dist/notifications-http.js

@@ -0,0 +1,38 @@
+import { createServer } from 'node:http';
+function createNotificationsHttpServer(options) {
+    const server = createServer((request, response) => {
+        const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+        const send = (status, body) => {
+            response.writeHead(status, { 'content-type': 'application/json' });
+            response.end(JSON.stringify(body));
+        };
+        if (request.method === 'GET' && url.pathname === '/email') {
+            send(200, options.notifications.document());
+            return;
+        }
+        send(404, { error: 'not found' });
+    });
+    return {
+        listen(port = 0, host = '127.0.0.1') {
+            return new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(port, host, () => {
+                    server.off('error', reject);
+                    const address = server.address();
+                    if (!address || typeof address === 'string')
+                        throw new Error('Notifications HTTP server has no port');
+                    resolve({ port: address.port });
+                });
+            });
+        },
+        close() {
+            return new Promise((resolve, reject) => {
+                server.close((error) => { if (error)
+                    reject(error);
+                else
+                    resolve(); });
+            });
+        },
+    };
+}
+export { createNotificationsHttpServer };

package/dist/notifications.d.ts

@@ -0,0 +1,42 @@
+import type { ToolDefinition, ToolDriver, ToolResult } from './types.js';
+/**
+ * Outbound notification law ported from Engine
+ * `runtime/scripts/amalgm-mcp/notify/index.js` and its canonical Toolbox ids
+ * in `runtime/scripts/amalgm-mcp/server/core-tools.js`.
+ */
+type NotificationLevel = 'info' | 'warning' | 'error' | 'success';
+interface EmailNotificationRequest {
+    subject: string;
+    message: string;
+    level: NotificationLevel;
+    link?: string;
+    sessionId?: string;
+}
+interface EmailDeliveryReceipt {
+    email: string;
+    replyTo?: string;
+    id?: string;
+}
+interface EmailDelivery {
+    send(request: EmailNotificationRequest): Promise<EmailDeliveryReceipt>;
+}
+interface NotificationsOptions {
+    email?: EmailDelivery;
+}
+declare function notificationToolDefinition(): ToolDefinition;
+declare class Notifications {
+    #private;
+    constructor(options?: NotificationsOptions);
+    document(): {
+        service: string;
+        actions: string[];
+        channels: {
+            id: string;
+            configured: boolean;
+        }[];
+    };
+    notify(input: Record<string, unknown>, context?: unknown): Promise<ToolResult>;
+}
+declare function createNotificationsDriver(notifications: Notifications): ToolDriver;
+export { Notifications, createNotificationsDriver, notificationToolDefinition };
+export type { EmailDelivery, EmailDeliveryReceipt, EmailNotificationRequest, NotificationLevel, NotificationsOptions, };

package/dist/notifications.js

@@ -0,0 +1,108 @@
+import { errorResult } from './results.js';
+const LEVELS = new Set(['info', 'warning', 'error', 'success']);
+function nonempty(value, label) {
+    const result = typeof value === 'string' ? value.trim() : '';
+    if (!result)
+        throw new Error(`${label} is required`);
+    return result;
+}
+function optional(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function contextSessionId(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const context = value;
+    return optional(context.callerSessionId) || optional(context.sessionId);
+}
+function notificationToolDefinition() {
+    return {
+        id: 'notifications',
+        name: 'Notifications',
+        description: 'Notify the current user about important results, completions, and failures.',
+        owner: 'amalgm',
+        origin: 'system',
+        source: { type: 'mcp', transport: 'host', serverName: 'notifications' },
+        actions: [{
+                name: 'notify_user',
+                description: 'Send the current user an email notification. Keep it concise and actionable.',
+                target: { name: 'notify_user' },
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        subject: { type: 'string', description: 'Short subject; defaults to the first 80 message characters.' },
+                        message: { type: 'string', description: 'Notification body.' },
+                        level: { type: 'string', enum: [...LEVELS], description: 'Severity; defaults to info.' },
+                        link: { type: 'string', description: 'Optional HTTP(S) details URL.' },
+                    },
+                    required: ['message'],
+                    additionalProperties: false,
+                },
+            }],
+    };
+}
+class Notifications {
+    #email;
+    constructor(options = {}) {
+        this.#email = options.email;
+    }
+    document() {
+        return {
+            service: 'notifications',
+            actions: ['notifications.notify_user'],
+            channels: [{ id: 'email', configured: Boolean(this.#email) }],
+        };
+    }
+    async notify(input, context) {
+        const message = nonempty(input.message, 'message');
+        const rawLevel = optional(input.level) || 'info';
+        if (!LEVELS.has(rawLevel))
+            throw new Error(`Unsupported notification level: ${rawLevel}`);
+        const subject = (optional(input.subject) || message.slice(0, 80).replace(/\n/g, ' ')).slice(0, 80);
+        const link = optional(input.link);
+        if (link && !['http:', 'https:'].includes(new URL(link).protocol)) {
+            throw new Error('link must use http or https');
+        }
+        if (!this.#email)
+            throw new Error('Email notification delivery is not configured');
+        const level = rawLevel;
+        const sessionId = contextSessionId(context);
+        const receipt = await this.#email.send({
+            subject,
+            message,
+            level,
+            ...(link ? { link } : {}),
+            ...(sessionId ? { sessionId } : {}),
+        });
+        const reply = receipt.replyTo ? ' (replies route to this session)' : '';
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Notification sent to ${receipt.email}${reply}.\n\nMessage: ${message}\nLevel: ${level}${link ? `\nLink: ${link}` : ''}`,
+                }],
+            structuredContent: { ok: true, channel: 'email', ...receipt },
+        };
+    }
+}
+function createNotificationsDriver(notifications) {
+    return {
+        type: 'mcp',
+        supports(tool) {
+            return tool.id === 'notifications'
+                && tool.source.type === 'mcp'
+                && tool.source.transport === 'host'
+                && tool.source.serverName === 'notifications';
+        },
+        async call({ action, input, options }) {
+            if (action.id !== 'notifications.notify_user')
+                return errorResult(`Unknown notification action: ${action.id}`);
+            try {
+                return await notifications.notify(input, options.context);
+            }
+            catch (error) {
+                return errorResult(error);
+            }
+        },
+    };
+}
+export { Notifications, createNotificationsDriver, notificationToolDefinition };

package/dist/proxy-email.d.ts

@@ -0,0 +1,9 @@
+import type { EmailDelivery } from './notifications.js';
+interface ProxyEmailDeliveryOptions {
+    baseUrl: string;
+    token: string;
+    fetch?: typeof globalThis.fetch;
+}
+declare function createProxyEmailDelivery(options: ProxyEmailDeliveryOptions): EmailDelivery;
+export { createProxyEmailDelivery };
+export type { ProxyEmailDeliveryOptions };

package/dist/proxy-email.js

@@ -0,0 +1,62 @@
+function escapeHtml(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+function emailHtml(message, link) {
+    const body = escapeHtml(message).replace(/\n/g, '<br>');
+    const details = link
+        ? `<p><a href="${escapeHtml(link)}">View details</a></p>`
+        : '';
+    return `<div>${body}</div>${details}`;
+}
+function notifyEndpoint(raw) {
+    const value = raw.trim().replace(/\/+$/, '').replace(/\/anthropic$/, '');
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol))
+        throw new Error('Notification proxy must use http or https');
+    if (url.username || url.password)
+        throw new Error('Notification proxy URL cannot contain credentials');
+    return `${value}/notify`;
+}
+function createProxyEmailDelivery(options) {
+    const endpoint = notifyEndpoint(options.baseUrl);
+    const token = options.token.trim();
+    if (!token)
+        throw new Error('Notification proxy token is required');
+    const request = options.fetch ?? globalThis.fetch;
+    return {
+        async send(notification) {
+            const response = await request(endpoint, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${token}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({
+                    subject: notification.subject,
+                    html: emailHtml(notification.message, notification.link),
+                    text: notification.message,
+                    ...(notification.sessionId ? { sessionId: notification.sessionId } : {}),
+                }),
+            });
+            if (!response.ok) {
+                const detail = (await response.text().catch(() => '')).slice(0, 200);
+                throw new Error(`Notification proxy failed: ${response.status}${detail ? ` ${detail}` : ''}`);
+            }
+            const body = await response.json();
+            const email = typeof body.email === 'string' && body.email.trim() ? body.email.trim() : '';
+            if (!email)
+                throw new Error('Notification proxy response did not identify the recipient');
+            return {
+                email,
+                ...(typeof body.replyTo === 'string' && body.replyTo ? { replyTo: body.replyTo } : {}),
+                ...(typeof body.id === 'string' && body.id ? { id: body.id } : {}),
+            };
+        },
+    };
+}
+export { createProxyEmailDelivery };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/tools",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Local-first tool definitions, Toolbox registry, and agent execution surfaces.",
   "license": "UNLICENSED",
   "private": false,