@amalgm/tools 0.1.1 → 0.1.3

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,11 +76,21 @@ 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.
+21. Reopening a Toolbox preserves the temporal fields of every semantically
+    unchanged system projection already present in its portable index; boot
+    never rewrites tracked bytes merely to stamp the current machine's time.
 
 ## Predictable behavior
 
-Applying the same definition twice produces the same catalog. Applying a
-changed action set replaces the old set atomically. Selecting a whole tool
+Applying the same definition twice produces the same catalog. Reopening the
+same system projection produces the same portable index bytes on every
+machine. Applying a changed action set replaces the old set atomically.
+Selecting a whole tool
 grants all of its enabled actions; selecting one action grants only that
 action. Disabling or deleting a tool immediately removes all of its actions
 from list and call surfaces. CLI arguments are passed directly to a process,

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/artifact-files.d.ts

@@ -1,3 +1,4 @@
+import type { ToolboxIndexDocument } from './artifacts.js';
 import type { ActionRecord, Catalog, ToolRecord } from './types.js';
 declare class ArtifactFiles {
     private readonly directory;
@@ -9,6 +10,7 @@ declare class ArtifactFiles {
     }): string;
     removeTool(toolId: string): void;
     writeIndex(catalog: Catalog): void;
+    readIndex(): ToolboxIndexDocument | null;
     /** Give every persisted user tool its portable artifact and refresh the
      * index. Additive only: a file for a tool this catalog does not know is
      * never deleted here — removal is an explicit mutation. */

package/dist/artifact-files.js

@@ -51,6 +51,13 @@ class ArtifactFiles {
     writeIndex(catalog) {
         writeJsonIfChanged(this.file(TOOLBOX_INDEX_FILE_NAME), catalogIndexDocument(catalog));
     }
+    readIndex() {
+        const value = readJson(this.file(TOOLBOX_INDEX_FILE_NAME));
+        if (!value || value.version !== 1 || !value.tools || typeof value.tools !== 'object'
+            || !value.toolActions || typeof value.toolActions !== 'object')
+            return null;
+        return value;
+    }
     /** Give every persisted user tool its portable artifact and refresh the
      * index. Additive only: a file for a tool this catalog does not know is
      * never deleted here — removal is an explicit mutation. */

package/dist/artifacts.d.ts

@@ -57,10 +57,12 @@ declare function artifactDocument(input: {
 declare function isToolArtifactDocument(value: unknown): value is ToolArtifactDocument;
 declare function toolboxIndexDocument(tools: Record<string, unknown>, toolActions: Record<string, unknown>): ToolboxIndexDocument;
 declare function catalogIndexDocument(catalog: Pick<Catalog, 'tools' | 'actions'>): ToolboxIndexDocument;
+declare function portableRecordSemantic(value: ToolRecord | ActionRecord): string;
+declare function preserveProjectionTime<T extends ToolRecord | ActionRecord>(candidate: T, previous: unknown): T;
 /** The migration of one legacy aggregate `toolbox.json` catalog, as a pure
  * plan: every user tool becomes a per-tool artifact write, the whole legacy
  * catalog becomes the index, and the aggregate file is renamed out of the
  * way only after each record has a per-tool replacement. */
 declare function legacyMigrationPlan(legacy: unknown): LegacyMigrationPlan;
-export { LEGACY_TOOLBOX_BACKUP_FILE_NAME, LEGACY_TOOLBOX_FILE_NAME, TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, legacyMigrationPlan, safeToolId, toolboxIndexDocument, userArtifactFileName, };
+export { LEGACY_TOOLBOX_BACKUP_FILE_NAME, LEGACY_TOOLBOX_FILE_NAME, TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, legacyMigrationPlan, safeToolId, portableRecordSemantic, preserveProjectionTime, toolboxIndexDocument, userArtifactFileName, };
 export type { ArtifactFileWrite, LegacyMigrationPlan, ToolArtifactDocument, ToolboxIndexDocument };

package/dist/artifacts.js

@@ -81,6 +81,19 @@ function toolboxIndexDocument(tools, toolActions) {
 function catalogIndexDocument(catalog) {
     return toolboxIndexDocument(Object.fromEntries(catalog.tools.map((tool) => [tool.id, tool])), Object.fromEntries(catalog.actions.map((action) => [action.id, action])));
 }
+function portableRecordSemantic(value) {
+    const { createdAt, updatedAt, ...portable } = value;
+    return JSON.stringify(portable);
+}
+function preserveProjectionTime(candidate, previous) {
+    if (!previous || typeof previous !== 'object')
+        return candidate;
+    const record = previous;
+    if (typeof record.createdAt !== 'string' || typeof record.updatedAt !== 'string'
+        || portableRecordSemantic(record) !== portableRecordSemantic(candidate))
+        return candidate;
+    return { ...candidate, createdAt: record.createdAt, updatedAt: record.updatedAt };
+}
 /** The migration of one legacy aggregate `toolbox.json` catalog, as a pure
  * plan: every user tool becomes a per-tool artifact write, the whole legacy
  * catalog becomes the index, and the aggregate file is renamed out of the
@@ -109,4 +122,4 @@ function legacyMigrationPlan(legacy) {
         rename: { from: LEGACY_TOOLBOX_FILE_NAME, to: LEGACY_TOOLBOX_BACKUP_FILE_NAME },
     };
 }
-export { LEGACY_TOOLBOX_BACKUP_FILE_NAME, LEGACY_TOOLBOX_FILE_NAME, TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, legacyMigrationPlan, safeToolId, toolboxIndexDocument, userArtifactFileName, };
+export { LEGACY_TOOLBOX_BACKUP_FILE_NAME, LEGACY_TOOLBOX_FILE_NAME, TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, legacyMigrationPlan, safeToolId, portableRecordSemantic, preserveProjectionTime, toolboxIndexDocument, userArtifactFileName, };

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/dist/toolbox.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { resolveProductStateDir } from '@amalgm/core/identity';
 import { apiDriver } from './api-driver.js';
 import { ArtifactFiles } from './artifact-files.js';
+import { portableRecordSemantic, preserveProjectionTime } from './artifacts.js';
 import { cliDriver } from './cli-driver.js';
 import { normalizeDefinition } from './definition.js';
 import { assertMcpNamesUnique, id, mcpName } from './ids.js';
@@ -11,10 +12,6 @@ import { callableActions, queryTools, resolveAction, resolveCallableAction } fro
 import { findSelected, selected } from './selection.js';
 import { Store } from './store.js';
 import { updateAction, updateTool, upsertAction } from './updates.js';
-function semantic(value) {
-    const { createdAt, updatedAt, ...record } = value;
-    return JSON.stringify(record);
-}
 function defaultDatabase(options) {
     if (options.databaseFile)
         return path.resolve(options.databaseFile);
@@ -40,6 +37,7 @@ class Toolbox {
         const databaseFile = defaultDatabase(options);
         this.store = new Store(databaseFile);
         this.artifacts = new ArtifactFiles(path.dirname(databaseFile));
+        const priorIndex = this.artifacts.readIndex();
         this.onChange = options.onChange;
         for (const driver of [cliDriver, apiDriver, ...(options.drivers || [])])
             this.drivers.set(driver.type, driver);
@@ -49,8 +47,8 @@ class Toolbox {
             const normalized = normalizeDefinition({ ...definition, origin: 'system' });
             if (tools.some((tool) => tool.id === normalized.tool.id))
                 throw new Error(`Duplicate system tool: ${normalized.tool.id}`);
-            tools.push(normalized.tool);
-            actions.push(...normalized.actions);
+            tools.push(preserveProjectionTime(normalized.tool, priorIndex?.tools[normalized.tool.id]));
+            actions.push(...normalized.actions.map((action) => preserveProjectionTime(action, priorIndex?.toolActions[action.id])));
         }
         assertMcpNamesUnique(actions);
         this.system = { version: 1, revision: 0, tools, actions };
@@ -116,9 +114,10 @@ class Toolbox {
             ...normalized.actions,
         ];
         assertMcpNamesUnique(candidateActions);
-        const unchanged = existing && semantic(existing) === semantic(normalized.tool)
+        const unchanged = existing && portableRecordSemantic(existing) === portableRecordSemantic(normalized.tool)
             && normalized.actions.length === oldActions.size
-            && normalized.actions.every((action) => semantic(action) === semantic(oldActions.get(action.id)));
+            && normalized.actions.every((action) => portableRecordSemantic(action)
+                === portableRecordSemantic(oldActions.get(action.id)));
         if (unchanged)
             return { tool: existing, actions: [...oldActions.values()].sort((a, b) => a.id.localeCompare(b.id)) };
         const result = this.store.apply(normalized);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/tools",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local-first tool definitions, Toolbox registry, and agent execution surfaces.",
   "license": "UNLICENSED",
   "private": false,
@@ -49,7 +49,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@amalgm/core": "^0.1.0",
+    "@amalgm/core": "0.2.0",
     "better-sqlite3": "^12.6.2"
   },
   "devDependencies": {