@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.
- package/PURPOSE.md +16 -15
- package/README.md +32 -33
- package/dist/artifacts.d.ts +9 -31
- package/dist/artifacts.js +8 -45
- package/dist/http.d.ts +5 -5
- package/dist/http.js +1 -6
- package/dist/index.d.ts +2 -6
- package/dist/index.js +1 -4
- package/dist/mcp-server.d.ts +5 -7
- package/dist/mcp-server.js +4 -26
- package/dist/results.d.ts +1 -4
- package/dist/results.js +1 -9
- package/dist/store.d.ts +0 -3
- package/dist/store.js +0 -13
- package/dist/tool-files.d.ts +40 -0
- package/dist/tool-files.js +136 -0
- package/dist/toolbox-deployments.d.ts +0 -3
- package/dist/toolbox-deployments.js +0 -17
- package/dist/toolbox-projection.d.ts +9 -5
- package/dist/toolbox-projection.js +27 -18
- package/dist/toolbox.d.ts +2 -1
- package/dist/toolbox.js +9 -12
- package/dist/types.d.ts +7 -11
- package/docs/SHELL_INTEGRATION.md +21 -7
- package/package.json +7 -14
- package/skills/tools/SKILL.md +28 -41
- package/dist/artifact-files.d.ts +0 -30
- package/dist/artifact-files.js +0 -123
- package/dist/bin/mcp.d.ts +0 -2
- package/dist/bin/mcp.js +0 -13
- package/dist/bin/tools.d.ts +0 -2
- package/dist/bin/tools.js +0 -3
- package/dist/cli.d.ts +0 -18
- package/dist/cli.js +0 -125
- package/dist/commands.d.ts +0 -27
- package/dist/commands.js +0 -16
- package/dist/deployment-files.d.ts +0 -10
- package/dist/deployment-files.js +0 -38
- package/dist/module.d.ts +0 -3
- package/dist/module.js +0 -22
- package/dist/toolbox-state-dir.d.ts +0 -2
- package/dist/toolbox-state-dir.js +0 -18
|
@@ -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 {
|
|
2
|
-
import type { Catalog, ToolboxOptions } from './types.js';
|
|
3
|
-
/**
|
|
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
|
|
5
|
+
private readonly files;
|
|
6
6
|
private readonly catalog;
|
|
7
|
+
private readonly history;
|
|
7
8
|
private readonly onChange?;
|
|
8
|
-
constructor(
|
|
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
|
-
/**
|
|
1
|
+
/** Writes the catalog out to the Toolbox's files; the database remains authority. */
|
|
2
2
|
class ToolboxProjection {
|
|
3
|
-
|
|
3
|
+
files;
|
|
4
4
|
catalog;
|
|
5
|
+
history;
|
|
5
6
|
onChange;
|
|
6
|
-
constructor(
|
|
7
|
-
this.
|
|
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.
|
|
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.
|
|
20
|
-
|
|
21
|
-
|
|
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.
|
|
32
|
+
this.files.removeTool(toolId);
|
|
36
33
|
}
|
|
37
|
-
this.
|
|
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
|
-
|
|
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
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
const
|
|
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(
|
|
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
|
-
|
|
177
|
-
|
|
178
|
-
/**
|
|
179
|
-
|
|
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
|
-
|
|
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,
|
|
5
|
-
|
|
6
|
-
|
|
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
|
-
-
|
|
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
|
|
29
|
-
in
|
|
30
|
-
|
|
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.
|
|
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
|
|
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.
|
|
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": "
|
|
84
|
+
"gitHead": "f2ebe4eb48c85a64818bf91db5c3c92e17cc7182",
|
|
92
85
|
"amalgmSource": {
|
|
93
86
|
"repository": "amalgm-inc/amalgm-tools",
|
|
94
87
|
"branch": "preview",
|
|
95
|
-
"commit": "
|
|
96
|
-
"occurrence": "
|
|
88
|
+
"commit": "f2ebe4eb48c85a64818bf91db5c3c92e17cc7182",
|
|
89
|
+
"occurrence": "44182693708"
|
|
97
90
|
}
|
|
98
91
|
}
|
package/skills/tools/SKILL.md
CHANGED
|
@@ -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
|
|
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({
|
|
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
|
-
|
|
91
|
-
|
|
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
|
-
|
|
98
|
-
|
|
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
|
-
|
|
103
|
-
|
|
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
|
-
##
|
|
135
|
+
## App links
|
|
136
136
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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()`
|
|
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
|
-
|
|
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({
|
|
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
|
|
179
|
-
|
|
180
|
-
|
|
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
|
|