@amalgm/shell 0.1.119 → 0.1.121

package/dist/platform-product-host.js

@@ -0,0 +1,114 @@
+import { AutomationRunExecutor, createAutomationClient, createMachineRunsClient, } from '@amalgm/automations';
+import { createChannelsClient } from '@amalgm/channels';
+export function createPlatformProductHost(options) {
+    const automations = createAutomationClient({
+        baseUrl: options.automationsBaseUrl,
+        headers: headersFor(options.authorization, 'amalgm-automations', automationScopes),
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+    const channels = createChannelsClient({
+        baseUrl: options.channelsBaseUrl,
+        headers: headersFor(options.authorization, 'amalgm-channels', channelScopes),
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+    const runs = createMachineRunsClient({
+        baseUrl: options.automationsBaseUrl,
+        headers: headersFor(options.authorization, 'amalgm-automations', () => ['runs:execute']),
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+    const executor = new AutomationRunExecutor(runs, actionRegistry({
+        'channels.notify_user': channelNotification(channels),
+    }));
+    const runner = createRunner({
+        claim: () => runs.claim({ limit: 8, leaseSeconds: 60 }),
+        execute: (run) => executor.execute(run),
+        intervalMs: options.pollIntervalMs ?? 1_000,
+        log: options.log,
+    });
+    return Object.freeze({ automations, channels, runner });
+}
+function headersFor(authorization, audience, scopes) {
+    return async (method, url) => {
+        const grant = await authorization.authorize({ audience, scopes: scopes(method, url), method, url });
+        return { authorization: grant.authorization, dpop: grant.dpop };
+    };
+}
+function automationScopes(method, url) {
+    if (method.toUpperCase() !== 'GET')
+        return ['automations:write'];
+    return new URL(url).pathname.includes('/runs') ? ['runs:read'] : ['automations:read'];
+}
+function channelScopes(method) {
+    return [method.toUpperCase() === 'GET' ? 'channels:read' : 'channels:send'];
+}
+function actionRegistry(actions) {
+    return Object.freeze({
+        async call(input) {
+            const { actionId, payload, idempotencyKey } = input;
+            const action = actions[actionId];
+            if (!action)
+                throw new Error(`Automation action is not installed: ${actionId}`);
+            return action(payload, idempotencyKey);
+        },
+    });
+}
+function channelNotification(channels) {
+    return async (payload, idempotencyKey) => {
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+            throw new Error('channels.notify_user input must be an object');
+        }
+        const delivery = await channels.notify({
+            ...payload,
+            idempotencyKey,
+        });
+        return delivery;
+    };
+}
+function createRunner(options) {
+    let active = null;
+    let timer = null;
+    const drain = () => {
+        if (active)
+            return active;
+        active = options.claim()
+            .then(async (runs) => {
+            if (runs.length)
+                options.log?.('automations.claimed', { count: runs.length });
+            const settled = await Promise.allSettled(runs.map(options.execute));
+            settled.forEach((result) => {
+                if (result.status === 'rejected')
+                    options.log?.('automations.run.failed', { error: safe(result.reason) });
+            });
+        })
+            .catch((error) => options.log?.('automations.poll.failed', { error: safe(error) }))
+            .finally(() => { active = null; });
+        return active;
+    };
+    return Object.freeze({
+        start() {
+            if (timer)
+                return;
+            timer = setInterval(drain, options.intervalMs);
+            timer.unref();
+            void drain();
+        },
+        async close() {
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            await active;
+        },
+    });
+}
+function safe(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const details = error && typeof error === 'object'
+        ? [field(error, 'code'), field(error, 'status')].filter(Boolean).join(' ')
+        : '';
+    return `${message}${details ? ` (${details})` : ''}`.replace(/[\r\n]+/g, ' ').slice(0, 500);
+}
+function field(value, key) {
+    const item = Reflect.get(value, key);
+    return typeof item === 'string' || typeof item === 'number' ? `${key}=${item}` : '';
+}
+//# sourceMappingURL=platform-product-host.js.map

package/dist/platform-product-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-product-host.js","sourceRoot":"","sources":["../src/platform-product-host.ts"],"names":[],"mappings":"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"}

package/dist/platform-tools.d.ts

@@ -0,0 +1,20 @@
+import { type ToolDefinition } from '@amalgm/tools';
+interface ToolServerLike {
+    readonly tools: readonly {
+        readonly name: string;
+        readonly description?: string;
+        readonly inputSchema?: Readonly<Record<string, unknown>>;
+    }[];
+}
+export interface PlatformToolDefinitionOptions {
+    readonly agents: ToolServerLike;
+    readonly apps: ToolServerLike;
+    readonly browser: ToolServerLike;
+    readonly products?: Readonly<{
+        automations: boolean;
+        channels: boolean;
+    }>;
+}
+/** One system Toolbox record per public Amalgm product capability. */
+export declare function platformToolDefinitions(options: PlatformToolDefinitionOptions): Promise<readonly ToolDefinition[]>;
+export {};

package/dist/platform-tools.js

@@ -0,0 +1,108 @@
+import { createAutomationMcpServer } from '@amalgm/automations/mcp';
+import { createChannelsMcpServer } from '@amalgm/channels/mcp';
+import { chatMcpToolDescriptors } from '@amalgm/chat/mcp';
+import { defineHostMcpTool, managementToolDescriptors, } from '@amalgm/tools';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+function descriptors(server) {
+    return server.tools.map((tool) => ({
+        name: tool.name,
+        ...(tool.description ? { description: tool.description } : {}),
+        inputSchema: (tool.inputSchema || {
+            type: 'object', properties: {}, additionalProperties: false,
+        }),
+    }));
+}
+function platformTool(input) {
+    return defineHostMcpTool({
+        id: input.id,
+        name: input.name,
+        description: input.description,
+        serverName: input.id,
+        route: input.route,
+        tools: input.tools,
+        metadata: { repository: input.repository },
+    });
+}
+/** Project an owning SDK's official MCP descriptors into one Toolbox record. */
+async function officialDescriptors(server) {
+    const client = new Client({ name: 'amalgm-shell-tool-projection', version: '1.0.0' });
+    const [serverTransport, clientTransport] = InMemoryTransport.createLinkedPair();
+    try {
+        await server.connect(serverTransport);
+        await client.connect(clientTransport);
+        const listed = await client.listTools();
+        return listed.tools.map((tool) => ({
+            name: tool.name,
+            ...(tool.description ? { description: tool.description } : {}),
+            inputSchema: tool.inputSchema,
+        }));
+    }
+    finally {
+        await client.close().catch(() => undefined);
+        await server.close().catch(() => undefined);
+    }
+}
+/** One system Toolbox record per public Amalgm product capability. */
+export async function platformToolDefinitions(options) {
+    const products = options.products ?? { automations: true, channels: true };
+    return Object.freeze([
+        platformTool({
+            id: 'browser',
+            name: 'Browser',
+            description: 'Browse and operate the web in visible Electron or isolated headless Chromium sessions.',
+            repository: 'amalgm-browser',
+            route: '/mcp/browser',
+            tools: descriptors(options.browser),
+        }),
+        ...(products.automations ? [platformTool({
+                id: 'automations',
+                name: 'Automations',
+                description: 'Create, inspect, change, and review durable Amalgm automations.',
+                repository: 'amalgm-automations',
+                route: '/mcp/automations',
+                tools: await officialDescriptors(createAutomationMcpServer({})),
+            })] : []),
+        platformTool({
+            id: 'agents',
+            name: 'Agents',
+            description: 'Manage Amalgm agent identities, installations, and immutable revisions.',
+            repository: 'amalgm-agents',
+            route: '/mcp/agents',
+            tools: descriptors(options.agents),
+        }),
+        ...(products.channels ? [platformTool({
+                id: 'channels',
+                name: 'Channels',
+                description: 'Send and inspect durable notifications for the current Amalgm user.',
+                repository: 'amalgm-channels',
+                route: '/mcp/channels',
+                tools: await officialDescriptors(createChannelsMcpServer({})),
+            })] : []),
+        platformTool({
+            id: 'chat',
+            name: 'Chat',
+            description: 'Inspect durable conversations and send messages to existing agent conversations.',
+            repository: 'amalgm-chat',
+            route: '/mcp/chat',
+            tools: chatMcpToolDescriptors(),
+        }),
+        platformTool({
+            id: 'apps',
+            name: 'Apps',
+            description: 'Validate, deploy, inspect, start, and stop versioned Amalgm applications.',
+            repository: 'amalgm-apps',
+            route: '/mcp/apps',
+            tools: descriptors(options.apps),
+        }),
+        platformTool({
+            id: 'tools',
+            name: 'Tools',
+            description: 'Inspect and manage the canonical Toolbox catalog and immutable tool deployments.',
+            repository: 'amalgm-tools',
+            route: '/mcp/platform-tools',
+            tools: managementToolDescriptors(),
+        }),
+    ]);
+}
+//# sourceMappingURL=platform-tools.js.map

package/dist/platform-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-tools.js","sourceRoot":"","sources":["../src/platform-tools.ts"],"names":[],"mappings":"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"}

package/dist/user-ground-host.d.ts

@@ -197,6 +197,11 @@ export declare class UserGroundHost {
      * the inline bound; anything else returns null and the block upload path
      * runs unchanged. */
     private readInlineCargo;
+    /** One self-contained cargo segment on the wire: declared artifacts in
+     * header order, their bytes concatenated behind them, one verified round
+     * trip. Returns the authority's sealed hashes for the stream law to
+     * prove coverage. */
+    private putCargo;
     private uploadSnapshotContent;
     /** Download a set of immutable artifacts straight from content storage.
      * The set is the primitive: every storage object the set still needs —
@@ -229,8 +234,8 @@ export declare class UserGroundHost {
     private publishPendingSnapshots;
     /** Seal this publication's graph pages. Pages are immutable, content
      * addressed, and already in memory, so the authority's seal inventory alone
-     * decides what still has to move and whole pages ride cargo waves. The head
-     * may not commit until every page it newly names is sealed. */
+     * decides what still has to move and whole pages ride the cargo stream. The
+     * head may not commit until every page it newly names is sealed. */
     private uploadGraphPages;
     private publishLoadedSnapshot;
 }

package/dist/user-ground-host.js

@@ -3,7 +3,7 @@ import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlin
 import { open, readFile } from "node:fs/promises";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { buildUserHomeManifest, buildUserManifest, liveMachineStateDir, scopedAmalgmDir, shippedUserHomeDeclaration, } from "@amalgm/core/identity";
-import { CHUNK_BYTES, CONTENT_CONTRACT, INLINE_CARGO_MAX_BYTES, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, createLocalEntityRecord, createEntityRecordAuthorityPort, convergeUserGround, decodeAcceptedEntityRecord, deriveUploadManifest, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, indexRepositoryTerritory, downloadAll as downloadAllArtifacts, encodeEntityRecord, EntityApplyRail, EntityRecordRail, membershipHash, pathIsSuspect, planCargoWaves, PRESIGN_BATCH_OBJECTS, privateEntityResourceId, repositoryIdentityHash, sameRecords, snapshotFromRecords, stableJson, travelingRecords, upload as uploadArtifact, userGroundRecords, GRAPH_HEAD_OPERATION_KIND, } from "@amalgm/live";
+import { CHUNK_BYTES, CONTENT_CONTRACT, INLINE_CARGO_MAX_BYTES, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, createLocalEntityRecord, createEntityRecordAuthorityPort, convergeUserGround, decodeAcceptedEntityRecord, deriveUploadManifest, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, indexRepositoryTerritory, downloadAll as downloadAllArtifacts, encodeEntityRecord, EntityApplyRail, EntityRecordRail, membershipHash, pathIsSuspect, PRESIGN_BATCH_OBJECTS, privateEntityResourceId, repositoryIdentityHash, sameRecords, snapshotFromRecords, stableJson, streamCargo, travelingRecords, upload as uploadArtifact, userGroundRecords, GRAPH_HEAD_OPERATION_KIND, } from "@amalgm/live";
 import Database from "better-sqlite3";
 import { atomicCopy, atomicWrite, ensurePrivateDir, ensureUserDir } from "./filesystem.js";
 import { emitFilesStage, } from "./files-observability.js";
@@ -27,9 +27,10 @@ import { NodeWatchHost, } from "./watching/index.js";
 import { GroundCoordinator } from "./ground-coordination.js";
 import { adoptSnapshotDeliveryBaseline } from "./snapshot-delivery-baseline.js";
 import { WireClient, WireRequestError } from "./wire-client.js";
-/** Cargo waves hold up to 16MiB of payload each; two in flight bounds the
- * upload path's memory while keeping the wire busy. */
-const CARGO_UPLOAD_CONCURRENCY = 2;
+/** One cargo segment loads its ground bytes across this many concurrent
+ * reads. Reading and hashing overlap the wire without letting a
+ * 256-artifact segment claim hundreds of file descriptors at once. */
+const CARGO_SEGMENT_LOAD_CONCURRENCY = 8;
 /** Storage-object lanes for one download set. Tiny objects use the wide
  * request window, while the separate byte budget narrows large chunks so
  * request concurrency can never silently become an unbounded memory claim. */
@@ -1309,6 +1310,25 @@ export class UserGroundHost {
         }
         return inline;
     }
+    /** One self-contained cargo segment on the wire: declared artifacts in
+     * header order, their bytes concatenated behind them, one verified round
+     * trip. Returns the authority's sealed hashes for the stream law to
+     * prove coverage. */
+    async putCargo(resourceId, artifacts, payload) {
+        const encoded = await encodeContentWireBytes(payload);
+        const frame = await retryContent(() => this.wire.requestBinary({
+            type: "private.entity-content.put-cargo",
+            resource_id: resourceId,
+            artifacts,
+            bytes: payload.byteLength,
+            wire_bytes: encoded.bytes.byteLength,
+            ...(encoded.encoding ? { content_encoding: encoded.encoding } : {}),
+        }, encoded.bytes, ["private.entity-content.stored-cargo"]));
+        return {
+            sealed: Array.isArray(frame.sealed) ? frame.sealed.map(String) : [],
+            wireBytes: encoded.bytes.byteLength,
+        };
+    }
     async uploadSnapshotContent(identity, resourceId, records, trace, manifestHints) {
         const cache = this.cacheDir(identity);
         const byHash = new Map();
@@ -1401,19 +1421,22 @@ export class UserGroundHost {
             }
             throw new StaleCaptureError(`${source.artifact.contentHash} no longer matches its source`, { cause: error });
         };
-        // Complete small artifacts ride cargo waves: whole artifacts per frame,
-        // verified and sealed by the authority in the same round trip, so the
-        // frame count scales with bytes moved, never with file count. Large
-        // artifacts keep per-artifact transfer where chunk reuse pays.
+        // Complete small artifacts ride the cargo stream: whole artifacts per
+        // self-contained segment, each verified and sealed by the authority in
+        // its own round trip, so the frame count scales with bytes moved, never
+        // with file count — and Live's bounded window keeps later segments on
+        // the wire while earlier durability acknowledgements are still
+        // outstanding. Large artifacts keep per-artifact transfer where chunk
+        // reuse pays.
         const small = sources.filter((source) => source.bytes <= CHUNK_BYTES);
         const large = sources.filter((source) => source.bytes > CHUNK_BYTES);
-        let cargoWaves = 0;
-        const transferCargoWave = async (wave) => {
-            const loaded = await Promise.all(wave.items.map(async (source) => {
+        let cargoSegments = 0;
+        const sendCargoSegment = async (segment) => {
+            const loaded = new Array(segment.items.length);
+            await boundedForEach(segment.items.map((item, index) => ({ source: item.source, index })), CARGO_SEGMENT_LOAD_CONCURRENCY, async ({ source, index }) => {
                 try {
                     const bytes = source.linkTarget ?? await readFile(source.file);
-                    return {
-                        source,
+                    loaded[index] = {
                         bytes,
                         manifest: deriveUploadManifest(source.artifact, bytes, sha256Hex),
                     };
@@ -1423,30 +1446,17 @@ export class UserGroundHost {
                         stale(source, error);
                     throw error;
                 }
-            }));
-            const payload = Buffer.concat(loaded.map((item) => item.bytes));
-            const encoded = await encodeContentWireBytes(payload);
-            const frame = await retryContent(() => this.wire.requestBinary({
-                type: "private.entity-content.put-cargo",
-                resource_id: resourceId,
-                artifacts: loaded.map((item) => ({
-                    content_hash: item.source.artifact.contentHash,
-                    bytes: item.manifest.bytes,
-                    chunks: item.manifest.chunks.map((chunk) => ({ sha256: chunk.sha256, bytes: chunk.bytes })),
-                })),
-                bytes: payload.byteLength,
-                wire_bytes: encoded.bytes.byteLength,
-                ...(encoded.encoding ? { content_encoding: encoded.encoding } : {}),
-            }, encoded.bytes, ["private.entity-content.stored-cargo"]));
-            const sealed = new Set(Array.isArray(frame.sealed) ? frame.sealed.map(String) : []);
-            for (const item of loaded) {
-                if (!sealed.has(item.source.artifact.contentHash)) {
-                    throw new Error(`content authority did not seal ${item.source.artifact.contentHash}`);
-                }
+            });
+            const { sealed, wireBytes } = await this.putCargo(resourceId, loaded.map((item, index) => ({
+                content_hash: segment.items[index].contentHash,
+                bytes: item.manifest.bytes,
+                chunks: item.manifest.chunks.map((chunk) => ({ sha256: chunk.sha256, bytes: chunk.bytes })),
+            })), Buffer.concat(loaded.map((item) => item.bytes)));
+            for (const item of loaded)
                 uploadedChunks += item.manifest.chunks.length;
-            }
-            uploadedBytes += encoded.bytes.byteLength;
-            cargoWaves += 1;
+            uploadedBytes += wireBytes;
+            cargoSegments += 1;
+            return sealed;
         };
         const transfer = async (source) => {
             const { artifact, file, manifest: knownManifest, bytes: fileBytes } = source;
@@ -1546,7 +1556,11 @@ export class UserGroundHost {
             }
         };
         try {
-            await boundedForEach([...planCargoWaves(small)], CARGO_UPLOAD_CONCURRENCY, transferCargoWave);
+            await streamCargo(small.map((source) => ({
+                contentHash: source.artifact.contentHash,
+                bytes: source.bytes,
+                source,
+            })), { send: sendCargoSegment });
             for (const source of large) {
                 await transfer(source);
             }
@@ -1565,7 +1579,7 @@ export class UserGroundHost {
                     uploadedChunks,
                     reusedChunks,
                     inventoryRequests,
-                    cargoWaves,
+                    cargoSegments,
                 },
             });
         }
@@ -2291,8 +2305,8 @@ export class UserGroundHost {
     }
     /** Seal this publication's graph pages. Pages are immutable, content
      * addressed, and already in memory, so the authority's seal inventory alone
-     * decides what still has to move and whole pages ride cargo waves. The head
-     * may not commit until every page it newly names is sealed. */
+     * decides what still has to move and whole pages ride the cargo stream. The
+     * head may not commit until every page it newly names is sealed. */
     async uploadGraphPages(resourceId, pages, trace) {
         if (pages.length === 0)
             return;
@@ -2300,32 +2314,21 @@ export class UserGroundHost {
         const sealed = await this.sealedContentHashes(resourceId, pages.map((page) => page.sha256));
         const unsealed = pages
             .filter((page) => !sealed.has(page.sha256))
-            .map((page) => ({ page, bytes: page.bytes.byteLength }));
+            .map((page) => ({ contentHash: page.sha256, bytes: page.bytes.byteLength, page }));
         let uploadedBytes = 0;
-        await boundedForEach([...planCargoWaves(unsealed)], CARGO_UPLOAD_CONCURRENCY, async (wave) => {
-            const payload = Buffer.concat(wave.items.map((item) => item.page.bytes));
-            const encoded = await encodeContentWireBytes(payload);
-            const frame = await retryContent(() => this.wire.requestBinary({
-                type: "private.entity-content.put-cargo",
-                resource_id: resourceId,
+        await streamCargo(unsealed, {
+            send: async (segment) => {
+                const { sealed: stored, wireBytes } = await this.putCargo(resourceId, 
                 // A page is a single-chunk artifact: its identity, its only chunk,
                 // and its bytes are one and the same sha.
-                artifacts: wave.items.map((item) => ({
-                    content_hash: item.page.sha256,
+                segment.items.map((item) => ({
+                    content_hash: item.contentHash,
                     bytes: item.bytes,
-                    chunks: [{ sha256: item.page.sha256, bytes: item.bytes }],
-                })),
-                bytes: payload.byteLength,
-                wire_bytes: encoded.bytes.byteLength,
-                ...(encoded.encoding ? { content_encoding: encoded.encoding } : {}),
-            }, encoded.bytes, ["private.entity-content.stored-cargo"]));
-            const stored = new Set(Array.isArray(frame.sealed) ? frame.sealed.map(String) : []);
-            for (const item of wave.items) {
-                if (!stored.has(item.page.sha256)) {
-                    throw new Error(`content authority did not seal graph page ${item.page.sha256}`);
-                }
-            }
-            uploadedBytes += encoded.bytes.byteLength;
+                    chunks: [{ sha256: item.contentHash, bytes: item.bytes }],
+                })), Buffer.concat(segment.items.map((item) => item.page.bytes)));
+                uploadedBytes += wireBytes;
+                return stored;
+            },
         });
         this.stage({
             primitive: "upload",