@amalgm/tools 0.1.7-preview.37556891038 → 0.1.7-preview.44182693708

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,136 @@
1
+ import crypto from 'node:crypto';
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import { entityFolderName, entityLayout, parkedDir } from '@amalgm/core/identity';
5
+ import { TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, safeToolId, } from './artifacts.js';
6
+ import { canonicalJson } from './deployments.js';
7
+ const HISTORY_DIR_NAME = 'history';
8
+ /**
9
+ * The Toolbox's files, written from `tools.db` (the catalog of record) and
10
+ * never read back as catalog:
11
+ *
12
+ * <root>/<Tool Name>/.amalgm-tool.json the tool and every action it owns
13
+ * <root>/<Tool Name>/history/<id>.json each of its deployments, immutable
14
+ * <root>/<Tool Name>/.private/ computer-only; parked when it is deleted
15
+ * <dir>/index.json the whole catalog, system tools included
16
+ *
17
+ * A tool's folder is found by the id in its identity file and follows the
18
+ * tool's name. Writes go through a temporary file and are skipped when the
19
+ * bytes are unchanged.
20
+ */
21
+ class ToolFiles {
22
+ folders;
23
+ constructor(folders) {
24
+ this.folders = folders;
25
+ }
26
+ writeTool(entry, history) {
27
+ const layout = this.place(entry.tool);
28
+ fs.mkdirSync(layout.private, { recursive: true });
29
+ writeIfChanged(layout.identity, JSON.stringify(artifactDocument(entry), null, 2), layout.private);
30
+ for (const deployment of history)
31
+ writeDeployment(layout, deployment);
32
+ }
33
+ /** Park the tool's `.private/`, then remove the files Tools wrote. The
34
+ * folder goes too unless the user keeps files of their own in it. */
35
+ removeTool(toolId) {
36
+ const folder = this.folderOf(toolId, this.entries());
37
+ if (!folder)
38
+ return;
39
+ const layout = entityLayout('tool', this.folders.root, folder);
40
+ if (fs.existsSync(layout.private) && fs.readdirSync(layout.private).length) {
41
+ const target = this.parkTarget(toolId);
42
+ fs.mkdirSync(path.dirname(target), { recursive: true });
43
+ fs.renameSync(layout.private, target);
44
+ }
45
+ for (const file of [layout.private, layout.identity, path.join(layout.dir, HISTORY_DIR_NAME)]) {
46
+ fs.rmSync(file, { recursive: true, force: true });
47
+ }
48
+ if (!fs.readdirSync(layout.dir).length)
49
+ fs.rmdirSync(layout.dir);
50
+ }
51
+ writeIndex(catalog) {
52
+ const file = this.indexFile();
53
+ writeIfChanged(file, JSON.stringify(catalogIndexDocument(catalog), null, 2), path.dirname(file));
54
+ }
55
+ readIndex() {
56
+ const value = readJson(this.indexFile());
57
+ if (!value || value.version !== 1 || !value.tools || typeof value.tools !== 'object'
58
+ || !value.toolActions || typeof value.toolActions !== 'object')
59
+ return null;
60
+ return value;
61
+ }
62
+ indexFile() { return path.join(this.folders.dir, TOOLBOX_INDEX_FILE_NAME); }
63
+ /** The tool's folder, created or renamed to follow its name. */
64
+ place(tool) {
65
+ const entries = this.entries();
66
+ const current = this.folderOf(tool.id, entries);
67
+ const folder = entityFolderName(tool.name, entries.filter((entry) => entry !== current));
68
+ if (current && current !== folder) {
69
+ fs.renameSync(path.join(this.folders.root, current), path.join(this.folders.root, folder));
70
+ }
71
+ return entityLayout('tool', this.folders.root, folder);
72
+ }
73
+ entries() {
74
+ try {
75
+ return fs.readdirSync(this.folders.root, { withFileTypes: true })
76
+ .filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
77
+ }
78
+ catch (error) {
79
+ if (error.code === 'ENOENT')
80
+ return [];
81
+ throw error;
82
+ }
83
+ }
84
+ folderOf(toolId, entries) {
85
+ return entries.find((entry) => {
86
+ const document = readJson(entityLayout('tool', this.folders.root, entry).identity);
87
+ return isToolArtifactDocument(document) && safeToolId(document.tool.id) === toolId;
88
+ });
89
+ }
90
+ /** Tool ids can be used again, so a second parking of one id gets "-2", "-3", …. */
91
+ parkTarget(toolId) {
92
+ let target = parkedDir(this.folders.parked, 'tool', toolId);
93
+ for (let n = 2; fs.existsSync(target); n += 1)
94
+ target = parkedDir(this.folders.parked, 'tool', `${toolId}-${n}`);
95
+ return target;
96
+ }
97
+ }
98
+ function readJson(file) {
99
+ try {
100
+ return JSON.parse(fs.readFileSync(file, 'utf8'));
101
+ }
102
+ catch {
103
+ return null;
104
+ }
105
+ }
106
+ function writeAtomic(file, bytes, temporaryDir) {
107
+ fs.mkdirSync(path.dirname(file), { recursive: true });
108
+ fs.mkdirSync(temporaryDir, { recursive: true });
109
+ const temporary = path.join(temporaryDir, `.write-${crypto.randomUUID()}`);
110
+ fs.writeFileSync(temporary, bytes);
111
+ fs.renameSync(temporary, file);
112
+ }
113
+ function writeIfChanged(file, bytes, temporaryDir) {
114
+ try {
115
+ if (fs.readFileSync(file, 'utf8') === bytes)
116
+ return;
117
+ }
118
+ catch { }
119
+ writeAtomic(file, bytes, temporaryDir);
120
+ }
121
+ /** A deployment record never changes: an existing file must hold the same deployment. */
122
+ function writeDeployment(layout, deployment) {
123
+ const file = path.join(layout.dir, HISTORY_DIR_NAME, `${deployment.id}.json`);
124
+ try {
125
+ if (canonicalJson(JSON.parse(fs.readFileSync(file, 'utf8'))) !== canonicalJson(deployment)) {
126
+ throw new Error(`Deployment file is immutable: ${deployment.id}`);
127
+ }
128
+ return;
129
+ }
130
+ catch (error) {
131
+ if (error.code !== 'ENOENT')
132
+ throw error;
133
+ }
134
+ writeAtomic(file, `${JSON.stringify(deployment, null, 2)}\n`, layout.private);
135
+ }
136
+ export { ToolFiles };
@@ -1,9 +1,7 @@
1
- import { DeploymentFiles } from './deployment-files.js';
2
1
  import { Store } from './store.js';
3
2
  import type { ActionRecord, ApplyResult, ToolDeployment, ToolDeploymentActivation, ToolDeploymentSnapshot, ToolDeploymentSurface, ToolRecord, ToolboxOptions } from './types.js';
4
3
  interface DeploymentServiceOptions {
5
4
  store: Store;
6
- files: DeploymentFiles;
7
5
  systemTools: readonly ToolRecord[];
8
6
  systemActions: readonly ActionRecord[];
9
7
  project(toolId: string): Promise<void>;
@@ -15,7 +13,6 @@ declare class ToolboxDeployments {
15
13
  private readonly options;
16
14
  private readonly observers;
17
15
  constructor(options: DeploymentServiceOptions);
18
- adoptLegacy(): void;
19
16
  activateLocal(definition: ApplyResult | null, deletedToolId?: string): Promise<void>;
20
17
  current(toolId: string): ToolDeployment | null;
21
18
  get(deploymentId: string): ToolDeployment | null;
@@ -7,20 +7,6 @@ class ToolboxDeployments {
7
7
  constructor(options) {
8
8
  this.options = options;
9
9
  }
10
- adoptLegacy() {
11
- const { store, systemTools, files } = this.options;
12
- for (const tool of store.catalog().tools) {
13
- if (store.currentDeploymentId(tool.id) || systemTools.some((system) => system.id === tool.id))
14
- continue;
15
- store.adoptDeployment(createToolDeployment({
16
- toolId: tool.id,
17
- previousDeploymentId: null,
18
- definition: { tool, actions: store.actionsFor(tool.id) },
19
- createdAt: tool.updatedAt,
20
- }));
21
- }
22
- files.materialize(store.allDeployments());
23
- }
24
10
  async activateLocal(definition, deletedToolId) {
25
11
  const toolId = definition?.tool.id || deletedToolId;
26
12
  if (!toolId)
@@ -34,7 +20,6 @@ class ToolboxDeployments {
34
20
  const applied = this.options.store.applyDeployment(activation);
35
21
  if (!applied.changed)
36
22
  return;
37
- this.options.files.write(activation.deployment);
38
23
  await this.options.project(toolId);
39
24
  for (const observer of this.observers)
40
25
  observer(activation);
@@ -59,7 +44,6 @@ class ToolboxDeployments {
59
44
  const applied = this.options.store.applyDeployment(activation);
60
45
  if (!applied.changed)
61
46
  return applied.result;
62
- this.options.files.write(activation.deployment);
63
47
  await this.options.project(activation.deployment.subjectId);
64
48
  return applied.result;
65
49
  }
@@ -88,7 +72,6 @@ class ToolboxDeployments {
88
72
  ]);
89
73
  const previousToolIds = this.options.store.catalog().tools.map((tool) => tool.id);
90
74
  this.options.store.replaceDeploymentSnapshot(snapshot);
91
- this.options.files.materialize(Object.values(snapshot.deployments));
92
75
  await this.options.replaceProjection(previousToolIds);
93
76
  }
94
77
  surface() {
@@ -1,13 +1,17 @@
1
- import { ArtifactFiles } from './artifact-files.js';
2
- import type { Catalog, ToolboxOptions } from './types.js';
3
- /** Current-catalog compatibility projections; deployments remain authority. */
1
+ import type { ToolFiles } from './tool-files.js';
2
+ import type { Catalog, ToolDeployment, ToolboxOptions } from './types.js';
3
+ /** Writes the catalog out to the Toolbox's files; the database remains authority. */
4
4
  declare class ToolboxProjection {
5
- private readonly artifacts;
5
+ private readonly files;
6
6
  private readonly catalog;
7
+ private readonly history;
7
8
  private readonly onChange?;
8
- constructor(artifacts: ArtifactFiles, catalog: () => Catalog, onChange?: ToolboxOptions['onChange']);
9
+ constructor(files: ToolFiles, catalog: () => Catalog, history: (toolId: string) => ToolDeployment[], onChange?: ToolboxOptions['onChange']);
10
+ /** Additive: a folder for a tool this catalog does not know is left alone. */
9
11
  boot(): void;
10
12
  changed(toolId: string): Promise<void>;
11
13
  replaced(previousToolIds: readonly string[]): Promise<void>;
14
+ private materialize;
15
+ private write;
12
16
  }
13
17
  export { ToolboxProjection };
@@ -1,30 +1,27 @@
1
- /** Current-catalog compatibility projections; deployments remain authority. */
1
+ /** Writes the catalog out to the Toolbox's files; the database remains authority. */
2
2
  class ToolboxProjection {
3
- artifacts;
3
+ files;
4
4
  catalog;
5
+ history;
5
6
  onChange;
6
- constructor(artifacts, catalog, onChange) {
7
- this.artifacts = artifacts;
7
+ constructor(files, catalog, history, onChange) {
8
+ this.files = files;
8
9
  this.catalog = catalog;
10
+ this.history = history;
9
11
  this.onChange = onChange;
10
12
  }
13
+ /** Additive: a folder for a tool this catalog does not know is left alone. */
11
14
  boot() {
12
- this.artifacts.migrateLegacy();
13
- this.artifacts.materialize(this.catalog());
15
+ this.materialize(this.catalog());
14
16
  }
15
17
  async changed(toolId) {
16
18
  const catalog = this.catalog();
17
19
  const tool = catalog.tools.find((candidate) => candidate.id === toolId);
18
- if (tool && tool.origin !== 'system') {
19
- this.artifacts.writeTool({
20
- tool,
21
- actions: catalog.actions.filter((action) => action.toolId === toolId),
22
- });
23
- }
24
- else if (!tool) {
25
- this.artifacts.removeTool(toolId);
26
- }
27
- this.artifacts.writeIndex(catalog);
20
+ if (tool && tool.origin !== 'system')
21
+ this.write(catalog, tool);
22
+ else if (!tool)
23
+ this.files.removeTool(toolId);
24
+ this.files.writeIndex(catalog);
28
25
  await this.onChange?.(catalog);
29
26
  }
30
27
  async replaced(previousToolIds) {
@@ -32,10 +29,22 @@ class ToolboxProjection {
32
29
  const currentToolIds = new Set(catalog.tools.map((tool) => tool.id));
33
30
  for (const toolId of previousToolIds) {
34
31
  if (!currentToolIds.has(toolId))
35
- this.artifacts.removeTool(toolId);
32
+ this.files.removeTool(toolId);
36
33
  }
37
- this.artifacts.materialize(catalog);
34
+ this.materialize(catalog);
38
35
  await this.onChange?.(catalog);
39
36
  }
37
+ materialize(catalog) {
38
+ for (const tool of catalog.tools)
39
+ if (tool.origin !== 'system')
40
+ this.write(catalog, tool);
41
+ this.files.writeIndex(catalog);
42
+ }
43
+ write(catalog, tool) {
44
+ this.files.writeTool({
45
+ tool,
46
+ actions: catalog.actions.filter((action) => action.toolId === tool.id),
47
+ }, this.history(tool.id));
48
+ }
40
49
  }
41
50
  export { ToolboxProjection };
package/dist/toolbox.d.ts CHANGED
@@ -12,7 +12,8 @@ declare class Toolbox {
12
12
  private readonly view;
13
13
  private readonly connectionService;
14
14
  private readonly authentication;
15
- constructor(options?: ToolboxOptions);
15
+ /** `root`, `dir` and `parked` are handed over by the host; Tools never picks a folder. */
16
+ constructor(options: ToolboxOptions);
16
17
  catalog(): Catalog;
17
18
  list(loadout?: LoadoutInput): Array<{
18
19
  tool: ToolRecord;
package/dist/toolbox.js CHANGED
@@ -1,19 +1,17 @@
1
1
  import path from 'node:path';
2
- import { defaultDatabase } from './toolbox-state-dir.js';
3
2
  import { apiDriver, graphqlDriver } from './api-driver.js';
4
3
  import { ToolAuthentication } from './connection-auth.js';
5
4
  import { ToolConnections } from './connections.js';
6
5
  import { ToolAuthorization } from './oauth.js';
7
6
  import { applyDefinition } from './apply-definition.js';
8
- import { ArtifactFiles } from './artifact-files.js';
9
7
  import { preserveProjectionTime } from './artifacts.js';
10
8
  import { createCliDriver } from './cli-driver.js';
11
- import { DeploymentFiles } from './deployment-files.js';
12
9
  import { deploymentRevisionId } from './deployments.js';
13
10
  import { normalizeDefinition } from './definition.js';
14
11
  import { preparedView } from './prepared-catalog.js';
15
12
  import { assertMcpNamesUnique, id } from './ids.js';
16
13
  import { Store } from './store.js';
14
+ import { ToolFiles } from './tool-files.js';
17
15
  import { ToolboxDeployments } from './toolbox-deployments.js';
18
16
  import { ToolboxProjection } from './toolbox-projection.js';
19
17
  import { ToolboxView } from './toolbox-view.js';
@@ -28,12 +26,13 @@ class Toolbox {
28
26
  view;
29
27
  connectionService;
30
28
  authentication;
31
- constructor(options = {}) {
32
- const databaseFile = defaultDatabase(options);
33
- this.store = new Store(databaseFile);
34
- const artifacts = new ArtifactFiles(path.dirname(databaseFile));
35
- const deploymentFiles = new DeploymentFiles(path.resolve(options.deploymentDir || options.stateDir || path.dirname(databaseFile)));
36
- const priorIndex = artifacts.readIndex();
29
+ /** `root`, `dir` and `parked` are handed over by the host; Tools never picks a folder. */
30
+ constructor(options) {
31
+ if (!options?.root || !options.dir || !options.parked)
32
+ throw new Error('Toolbox requires root, dir and parked folders');
33
+ this.store = new Store(path.join(options.dir, 'tools.db'));
34
+ const files = new ToolFiles(options);
35
+ const priorIndex = files.readIndex();
37
36
  for (const driver of [createCliDriver(options.environment), apiDriver, graphqlDriver, ...(options.drivers || [])])
38
37
  this.drivers.set(driver.type, driver);
39
38
  this.authentication = new ToolAuthentication(options.credentials, options.resolveSecret);
@@ -57,17 +56,15 @@ class Toolbox {
57
56
  tools,
58
57
  actions,
59
58
  };
60
- this.projection = new ToolboxProjection(artifacts, () => this.catalog(), options.onChange);
59
+ this.projection = new ToolboxProjection(files, () => this.catalog(), (toolId) => this.store.deploymentsFor(toolId), options.onChange);
61
60
  this.deploymentService = new ToolboxDeployments({
62
61
  store: this.store,
63
- files: deploymentFiles,
64
62
  systemTools: this.system.tools,
65
63
  systemActions: this.system.actions,
66
64
  project: (toolId) => this.projection.changed(toolId),
67
65
  replaceProjection: (previousToolIds) => this.projection.replaced(previousToolIds),
68
66
  ...(options.onDeployment ? { onDeployment: options.onDeployment } : {}),
69
67
  });
70
- this.deploymentService.adoptLegacy();
71
68
  this.view = new ToolboxView(() => this.catalog(), this.drivers, { resolveSecret: this.authentication.resolve });
72
69
  this.projection.boot();
73
70
  }
package/dist/types.d.ts CHANGED
@@ -1,5 +1,4 @@
1
1
  import type { McpOptions, McpTool } from './mcp-types.js';
2
- import type { Writable } from 'node:stream';
3
2
  import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
4
3
  import type { ToolDeploymentActivation } from './deployment-types.js';
5
4
  type JsonSchema = {
@@ -173,10 +172,12 @@ interface ToolDriver {
173
172
  discover?(tool: ToolRecord, options: CallOptions): Promise<ActionDefinition[]>;
174
173
  }
175
174
  interface ToolboxOptions {
176
- stateDir?: string;
177
- databaseFile?: string;
178
- /** Portable immutable deployment documents; may differ from databaseFile. */
179
- deploymentDir?: string;
175
+ /** The user's toolbox folder: one `<Tool Name>/` folder per user tool. */
176
+ root: string;
177
+ /** This computer's Tools folder: `tools.db` and the catalog index. */
178
+ dir: string;
179
+ /** Where a deleted tool's `.private/` folder is moved. */
180
+ parked: string;
180
181
  systemTools?: ToolDefinition[];
181
182
  drivers?: ToolDriver[];
182
183
  /** Host-supplied process environment for one CLI tool call, such as where its linked app listens. */
@@ -187,11 +188,6 @@ interface ToolboxOptions {
187
188
  /** Outbound local Live operation. Remote application never calls it. */
188
189
  onDeployment?: (activation: ToolDeploymentActivation) => void | Promise<void>;
189
190
  }
190
- interface CliIo {
191
- stdout?: Writable;
192
- stderr?: Writable;
193
- commands?: import('./commands.js').ToolCommands;
194
- }
195
- export type { ActionDefinition, ActionRecord, ActionTarget, ApiSource, ApiTarget, ApplyResult, CallOptions, Catalog, CliIo, CliSource, CliTarget, DriverCall, JsonSchema, GraphqlSource, GraphqlTarget, Loadout, LoadoutInput, McpOptions, McpSource, McpTarget, McpTool, Origin, SecretResolver, Status, ToolDefinition, ToolDriver, ToolboxOptions, ToolRecord, ToolResult, ToolPatch, ActionPatch, ToolQuery, ToolSource, ToolType, ToolExposure, };
191
+ export type { ActionDefinition, ActionRecord, ActionTarget, ApiSource, ApiTarget, ApplyResult, CallOptions, Catalog, CliSource, CliTarget, DriverCall, JsonSchema, GraphqlSource, GraphqlTarget, Loadout, LoadoutInput, McpOptions, McpSource, McpTarget, McpTool, Origin, SecretResolver, Status, ToolDefinition, ToolDriver, ToolboxOptions, ToolRecord, ToolResult, ToolPatch, ActionPatch, ToolQuery, ToolSource, ToolType, ToolExposure, };
196
192
  export type { ToolDeployment, ToolDeploymentActivation, ToolDeploymentSnapshot, ToolDeploymentSurface, } from './deployment-types.js';
197
193
  export type { HostMcpToolDefinitionInput, HostMcpToolDescriptor } from './host-mcp-tool.js';
@@ -1,9 +1,23 @@
1
1
  # Shell integration
2
2
 
3
3
  `@amalgm/tools` is the canonical Toolbox product. `@amalgm/shell` constructs
4
- one Toolbox for a machine user, supplies its machine-local SQLite path and
5
- portable deployment directory, and mounts the product's public HTTP and MCP
6
- adapters.
4
+ one Toolbox for a machine user, hands it its folders, and mounts the product's
5
+ public HTTP and MCP adapters over that one instance:
6
+
7
+ ```ts
8
+ const user = userLayout(lane.user(email));
9
+ const toolbox = new Toolbox({
10
+ root: user.toolbox, // <Tool Name>/.amalgm-tool.json, history/, .private/
11
+ dir: user.computer.tools, // tools.db and index.json
12
+ parked: user.computer.parked, // a deleted tool's .private/
13
+ credentials, systemTools, drivers,
14
+ });
15
+ const mcp = createMcpServer({ toolbox });
16
+ const http = createToolboxHttpServer({ toolbox });
17
+ ```
18
+
19
+ The runtime serves that MCP surface at `/mcp/tools`; the `amalgm tools …`
20
+ command calls it there.
7
21
 
8
22
  ## Tools owns
9
23
 
@@ -18,16 +32,16 @@ adapters.
18
32
 
19
33
  - the exact `@amalgm/tools` package version in the Shell release;
20
34
  - the one host MCP driver and authenticated loopback routes;
21
- - machine-local SQLite placement and the portable deployment directory;
35
+ - the Toolbox's `root`, `dir` and `parked` folders (from `@amalgm/core/identity`);
22
36
  - encrypted credential persistence and upstream MCP transports;
23
37
  - projection of owning products' official MCP descriptors as immutable system
24
38
  tools; and
25
39
  - binding Tools' deployment surface to broader product state when enabled.
26
40
 
27
41
  Tools owns connection transitions and OAuth refresh; Shell supplies the encrypted
28
- vault without duplicating a connection registry. Definitions and actions remain
29
- in `users/<email>/toolbox/<tool-id>/deployments`; vault records remain under the
30
- machine boundary and never enter synced deployment documents.
42
+ vault without duplicating a connection registry. Definitions and actions live
43
+ in each tool's `.amalgm-tool.json` and `history/`; vault records stay on the
44
+ computer and never enter synced deployment documents.
31
45
 
32
46
  Agents stores loadout identifiers and direct/search/hidden exposure; Chat pins the exact Toolbox `revisionId`
33
47
  during preparation. Neither product writes Tools persistence.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@amalgm/tools",
3
- "version": "0.1.7-preview.37556891038",
3
+ "version": "0.1.7-preview.44182693708",
4
4
  "description": "Local-first tool definitions, Toolbox registry, and agent execution surfaces.",
5
5
  "license": "UNLICENSED",
6
6
  "private": false,
@@ -28,10 +28,6 @@
28
28
  "default": "./dist/http.js"
29
29
  }
30
30
  },
31
- "bin": {
32
- "amalgm-tools": "./dist/bin/tools.js",
33
- "amalgm-tools-mcp": "./dist/bin/mcp.js"
34
- },
35
31
  "files": [
36
32
  "docs",
37
33
  "dist",
@@ -40,7 +36,7 @@
40
36
  "skills"
41
37
  ],
42
38
  "scripts": {
43
- "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsx scripts/mark-executables.ts",
39
+ "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
44
40
  "check": "tsx scripts/check-tree.ts && tsc -p tsconfig.json && tsc -p tsconfig.test.json",
45
41
  "test": "tsx --test --test-concurrency=1 --test-timeout=30000 test/*.test.ts",
46
42
  "verify": "npm run check && npm run build && npm test",
@@ -56,7 +52,7 @@
56
52
  "node": ">=24"
57
53
  },
58
54
  "dependencies": {
59
- "@amalgm/core": "0.5.1-preview.37556608028",
55
+ "@amalgm/core": "0.5.1-preview.44182200738",
60
56
  "@modelcontextprotocol/sdk": "1.32.1",
61
57
  "better-sqlite3": "^12.6.2"
62
58
  },
@@ -72,10 +68,7 @@
72
68
  "jobs": [
73
69
  "verify"
74
70
  ],
75
- "verify": "verify",
76
- "cli": [
77
- "amalgm-tools"
78
- ]
71
+ "verify": "verify"
79
72
  },
80
73
  "allowScripts": {
81
74
  "better-sqlite3@12.11.1": true,
@@ -88,11 +81,11 @@
88
81
  "@amalgm/core"
89
82
  ]
90
83
  },
91
- "gitHead": "0dcfccd356ecd6c3bee20428ff1e7dd1abf01992",
84
+ "gitHead": "f2ebe4eb48c85a64818bf91db5c3c92e17cc7182",
92
85
  "amalgmSource": {
93
86
  "repository": "amalgm-inc/amalgm-tools",
94
87
  "branch": "preview",
95
- "commit": "0dcfccd356ecd6c3bee20428ff1e7dd1abf01992",
96
- "occurrence": "37556891038"
88
+ "commit": "f2ebe4eb48c85a64818bf91db5c3c92e17cc7182",
89
+ "occurrence": "44182693708"
97
90
  }
98
91
  }
@@ -22,16 +22,14 @@ Node.js 20 or newer is required. The package exposes:
22
22
  - `@amalgm/tools` for definitions, the `Toolbox`, deployments, MCP projection,
23
23
  ids, and driver contracts.
24
24
  - `@amalgm/tools/mcp` for MCP helpers.
25
- - `@amalgm/tools/http` for the read-only Toolbox HTTP adapter.
26
- - `amalgm-tools` for local catalog management and execution.
27
- - `amalgm-tools-mcp` for a newline-delimited stdio MCP server.
25
+ - `@amalgm/tools/http` for the Toolbox HTTP adapter.
28
26
 
29
27
  ## Define and run a tool
30
28
 
31
29
  ```js
32
30
  import { defineTool, Toolbox } from '@amalgm/tools';
33
31
 
34
- const toolbox = new Toolbox({ stateDir: './.tools' });
32
+ const toolbox = new Toolbox({ root: './toolbox', dir: './.tools', parked: './.tools/parked' });
35
33
 
36
34
  await toolbox.apply(defineTool({
37
35
  id: 'hello',
@@ -87,20 +85,22 @@ bytes resolves to the same content identity. `catalog()` exposes both:
87
85
  - `revisionId`, the digest of the exact current user deployments and system
88
86
  projections. Use this immutable id when preparing an agent run.
89
87
 
90
- By default state resolves through the shared Amalgm state-dir law:
91
- `AMALGM_TOOLS_DIR`, then `AMALGM_DIR/toolbox`, then the current user's scoped
92
- Toolbox directory. Pass `stateDir` for a self-contained Toolbox, or separate
93
- portable deployments from machine-local coordination state:
88
+ The Toolbox never picks a folder; its host hands it three. In Amalgm they
89
+ come from `@amalgm/core/identity`:
94
90
 
95
91
  ```js
92
+ const user = userLayout(userRoot);
96
93
  const toolbox = new Toolbox({
97
- deploymentDir: '/amalgm/users/person@example.com/toolbox',
98
- databaseFile: '/machine-state/services/tools/tools.db',
94
+ root: user.toolbox, // one <Tool Name>/ folder per user tool
95
+ dir: user.computer.tools, // tools.db and index.json
96
+ parked: user.computer.parked, // a deleted tool's .private/ moves here
99
97
  });
100
98
  ```
101
99
 
102
- Deployment documents are portable. The SQLite database, WAL, local index, and
103
- legacy flat artifacts are projections and should not be synchronized.
100
+ Each user tool is `<root>/<Tool Name>/` with `.amalgm-tool.json` (the tool and
101
+ its actions), `history/<deployment-id>.json` (one immutable record per
102
+ deployment) and `.private/` (computer-only). The folder follows the tool's
103
+ name. `tools.db`, its WAL and `index.json` stay on the computer.
104
104
 
105
105
  ## Loadouts
106
106
 
@@ -132,52 +132,39 @@ await toolbox.call('billing.lookup', { customerId: 'cus_123' }, {
132
132
  This keeps portable definitions and deployment documents safe to inspect and
133
133
  synchronize.
134
134
 
135
- ## CLI
135
+ ## App links
136
136
 
137
- The CLI prints JSON and exits non-zero on failure:
138
-
139
- ```bash
140
- amalgm-tools apply ./tool.mjs
141
- amalgm-tools list
142
- amalgm-tools catalog
143
- amalgm-tools show hello.say
144
- amalgm-tools enable hello.say
145
- amalgm-tools disable hello.say
146
- amalgm-tools remove hello
147
- amalgm-tools link canvas app-3f1c
148
- amalgm-tools unlink canvas
149
- amalgm-tools run hello.say --input '{"name":"Ada"}'
150
- amalgm-tools connections
151
- ```
152
-
153
- `link` records the app a tool belongs to (`appId`, the reverse edge of the app
154
- manifest's `toolIds`); sharing the app carries the tool and sharing the tool
155
- carries the app. The MCP twins are `toolbox_tool_link` and `toolbox_tool_unlink`.
156
-
157
- Use `--state-dir DIR` to select a Toolbox and `--loadout one,two` to bound
158
- `list`, `run`, or connection projection.
137
+ `toolbox_tool_link` records the app a tool belongs to (`appId`, the reverse
138
+ edge of the app manifest's `toolIds`); sharing the app carries the tool and
139
+ sharing the tool carries the app. `toolbox_tool_unlink` detaches it.
159
140
 
160
141
  ## MCP and HTTP surfaces
161
142
 
162
143
  `createMcpTools(toolbox)` projects management operations and enabled actions,
163
- while `createMcpServer()` creates a complete stdio server. A machine host can
144
+ while `createMcpServer({ toolbox })` answers MCP JSON-RPC requests over the
145
+ Toolbox the host already holds. A machine host can
164
146
  also use `defineHostMcpTool` to represent another product's official MCP
165
147
  descriptors as one system-owned Toolbox record.
166
148
 
167
- For read-only dashboards, mount the HTTP adapter:
149
+ Inside Amalgm the runtime serves this MCP surface at `/mcp/tools`; agents use
150
+ its `toolbox_*` tools and people use the `amalgm tools …` command, which calls
151
+ it there.
152
+
153
+ Dashboards mount the HTTP adapter over the same Toolbox:
168
154
 
169
155
  ```js
170
156
  import { Toolbox } from '@amalgm/tools';
171
157
  import { createToolboxHttpServer } from '@amalgm/tools/http';
172
158
 
173
- const toolbox = new Toolbox({ stateDir: './.tools' });
159
+ const toolbox = new Toolbox({ root: './toolbox', dir: './.tools', parked: './.tools/parked' });
174
160
  const server = createToolboxHttpServer({ toolbox });
175
161
  await server.listen(8083);
176
162
  ```
177
163
 
178
- It serves the legacy-compatible `GET /toolbox`, `GET /toolbox/tools?id=...`,
179
- and `GET /toolbox/actions?id=...` catalog routes. Mutations belong through the
180
- SDK, CLI, or MCP surface.
164
+ It serves `GET /toolbox`, `GET /toolbox/tools?id=...` and
165
+ `GET /toolbox/actions?id=...`, plus `POST`, `PATCH` and `DELETE /toolbox/tools`
166
+ to connect, disconnect and remove a tool and `POST /toolbox/actions/call` to
167
+ invoke an action.
181
168
 
182
169
  ## How Tools fits into Amalgam
183
170