@amalgm/shell 0.1.126 → 0.1.128

package/skills/shell/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: shell
+description: Install, authenticate, run, inspect, and integrate the @amalgm/shell machine runtime. Use when enrolling a computer, starting or diagnosing the local Amalgm runtime, recovering its device key, registering or materializing Files workspaces, embedding Shell host composition, or determining which published product versions make up a machine release.
+---
+
+# Amalgm Shell
+
+Shell is the installable Amalgm machine runtime. It composes exact published
+versions of the product SDKs with the operating-system, network, SQLite, and
+cloud effects they need. The products own their laws and data; Shell owns boot,
+host adapters, authenticated routing, process lifetime, and the tested version
+combination that ships to a machine.
+
+## Installation and first login
+
+Shell requires Node.js 20.19 or newer and installs the `amalgm` command:
+
+```bash
+npx --package @amalgm/shell amalgm login --no-open
+```
+
+Login enrolls the computer, obtains browser approval or redeems a setup code,
+persists the installation identity, converges the user's portable ground, and
+starts the runtime. Omit `--no-open` to let the command open the approval page,
+or pass `--setup-code CODE` when you already have a setup code.
+
+Private device keys use the native macOS Keychain or Windows DPAPI where
+available, with a verified mode-0600 file fallback. Key material is never put
+in a process argument. Missing, corrupt, or rejected keys fail closed instead
+of silently changing the machine's identity.
+
+## Run and inspect the runtime
+
+```bash
+# Start or resume one enrolled user.
+npx --package @amalgm/shell amalgm run --user person@example.com
+
+# Read registration and authenticated runtime health without starting it.
+npx --package @amalgm/shell amalgm status --user person@example.com
+```
+
+Use `--user` when a machine has more than one enrolled Amalgm user. Other
+global options include `--app-url URL`, `--amalgm-root PATH`, `--home PATH`,
+and `--name NAME`.
+
+The running host publishes an authenticated loopback boundary. Every protected
+HTTP or WebSocket request crosses the shared Core token and routing laws;
+narrowly exempt routes must establish their own session-scoped authority before
+an effect runs.
+
+## Recover a device key
+
+Recovery is explicit and preserves machine identity:
+
+```bash
+npx --package @amalgm/shell amalgm auth recover --user person@example.com
+```
+
+Shell stages a separate candidate key, requires browser approval or a setup
+code, proves possession of the candidate, and promotes it only after the
+control plane accepts it. A failed recovery leaves the previous identity and a
+clean retry boundary.
+
+## Register and materialize Files workspaces
+
+Files commands execute inside the already-running runtime so registration,
+SQLite state, cloud transfer, and Watch share one lifecycle:
+
+```bash
+# Declare, capture, upload, and watch an external workspace.
+npx --package @amalgm/shell amalgm files register ./project \
+  --user person@example.com
+
+# Materialize an owned cloud workspace into the current directory and watch it.
+npx --package @amalgm/shell amalgm files add <workspace-id> \
+  --user person@example.com
+```
+
+`files register` waits until the graph is reconciled, watcher coverage is
+healthy, required immutable content is uploaded, and the graph head commits.
+`files add` proves the selected ready machine and asks that runtime to download
+the workspace; it does not perform a second login or create a second watcher.
+
+Live owns the portable Files and transfer decisions. Shell supplies the real
+filesystem, Git, watcher, cache, authenticated wire, and object-storage effects.
+Ordinary file content, symlinks, and Git repositories keep their distinct
+transfer contracts, and portable state remains separate from machine-only
+control state.
+
+## What a Shell release contains
+
+Every `@amalgm/*` dependency is pinned to one exact registry version. A Shell
+release therefore identifies one combination that was built and tested
+together rather than allowing product versions to drift independently on a
+user's machine.
+
+The current signed baseline starts Core, Files, Agents, Tools, and Chat.
+Shell also carries the published Apps, Automations, Browser, Channels, and Live
+SDKs needed for routed, lazy, hosted, or direct product integrations. A package
+being installed is not by itself proof that it is a baseline boot service: the
+verified release catalog is the authority for that graph.
+
+Products projected into the Toolbox keep their own ownership:
+
+- Agents owns agent identities, installations, and immutable revisions.
+- Apps owns versioned application releases, deployments, and supervision.
+- Automations owns schedules, event triggers, leases, action plans, and run
+  journals.
+- Browser owns persistent, observable browser operation.
+- Channels owns durable notification delivery.
+- Chat owns durable conversations, turns, reconnect, and interrupt.
+- Tools owns tool identity, immutable deployments, loadouts, and execution.
+- Live owns portable entities, Files convergence, transfer, and presence law.
+
+Shell projects or routes those capabilities; it does not become their data
+owner.
+
+Hosted Automations uses `https://automations.amalgm.ai`. Machine authorization
+proofs are bound to that exact canonical origin; do not substitute the Fly
+deployment hostname. A queued `chat.chat_agent_run` step resolves the installed
+agent on this machine, starts its own durable Chat conversation, and rejoins
+that same turn when Automations retries the step.
+
+## Embedding Shell
+
+Install the package when building a host or an examination around the same
+composition:
+
+```bash
+npm install @amalgm/shell
+```
+
+The root export includes `bootShell`, `composeShell`, `createGateway`,
+`MachineHost`, `UserGroundHost`, `NodeWatchHost`, `WireClient`, the signed
+`shellReleaseCatalog`, and their public types. Authorization helpers are also
+available from the focused `@amalgm/shell/authorization` entry point.
+
+Use `bootShell` for the complete host, `composeShell` for an injected
+composition, and `createGateway` when mounting authenticated brick routes in a
+custom host. Host effects should be created once and injected; product code
+should continue to live in its owning package.
+
+## Historical Engine reference
+
+`amalgm-engine` is deprecated. It remains useful as read-only historical
+evidence for parity, migration, and contract archaeology, but Shell never
+starts it beside a released service and never falls back to its implementation
+at runtime. Current behavior is determined by the published product packages,
+Shell's code, tests, and verified release catalog.

package/dist/events-host.d.ts

@@ -1,9 +0,0 @@
-import { type AutomationEventsApiConfig } from "@amalgm/automations";
-import type { BrickMount } from "./gateway.js";
-export type AutomationEventsHostConfig = AutomationEventsApiConfig;
-/**
- * Node HTTP transport for the Automations brick's /events Fetch API. Target
- * identity and delivery capabilities are injected; all ingress decisions stay
- * in @amalgm/automations.
- */
-export declare function automationEventsMount(config: AutomationEventsHostConfig): BrickMount;

package/dist/events-host.js

@@ -1,34 +0,0 @@
-import { Readable } from "node:stream";
-import { createAutomationEventsApi, } from "@amalgm/automations";
-/**
- * Node HTTP transport for the Automations brick's /events Fetch API. Target
- * identity and delivery capabilities are injected; all ingress decisions stay
- * in @amalgm/automations.
- */
-export function automationEventsMount(config) {
-    const api = createAutomationEventsApi(config);
-    return {
-        prefix: "/events",
-        stream: async (req, res, pathname) => {
-            const source = new URL(req.url ?? pathname, "http://localhost");
-            const headers = new Headers();
-            for (const [name, value] of Object.entries(req.headers)) {
-                if (Array.isArray(value))
-                    headers.set(name, value.join(", "));
-                else if (value !== undefined)
-                    headers.set(name, value);
-            }
-            const method = req.method ?? "GET";
-            const init = { method, headers };
-            if (method !== "GET" && method !== "HEAD") {
-                init.body = Readable.toWeb(req);
-                init.duplex = "half";
-            }
-            const request = new Request(`http://automations.local${pathname}${source.search}`, init);
-            const response = await api(request);
-            res.writeHead(response.status, Object.fromEntries(response.headers.entries()));
-            res.end(Buffer.from(await response.arrayBuffer()));
-        },
-    };
-}
-//# sourceMappingURL=events-host.js.map

package/dist/events-host.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"events-host.js","sourceRoot":"","sources":["../src/events-host.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EACL,yBAAyB,GAE1B,MAAM,qBAAqB,CAAC;AAM7B;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAkC;IACtE,MAAM,GAAG,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAC9C,OAAO;QACL,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE;YACnC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,QAAQ,EAAE,kBAAkB,CAAC,CAAC;YAChE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;YAC9B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBACxD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;oBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;qBACzD,IAAI,KAAK,KAAK,SAAS;oBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACzD,CAAC;YACD,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC;YACnC,MAAM,IAAI,GAAsC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;YACpE,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;gBAC1C,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAA+B,CAAC;gBAC9D,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;YACvB,CAAC;YACD,MAAM,OAAO,GAAG,IAAI,OAAO,CACzB,2BAA2B,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,EACrD,IAAI,CACL,CAAC;YACF,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,CAAC;YACpC,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAC/E,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QACrD,CAAC;KACF,CAAC;AACJ,CAAC"}