@amalgm/agents 0.2.3-preview.37556893493 → 0.2.3-preview.39017157677

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.
Files changed (93) hide show
  1. package/PURPOSE.md +21 -19
  2. package/README.md +25 -36
  3. package/dist/agent-folder.d.ts +32 -0
  4. package/dist/agent-folder.js +100 -0
  5. package/dist/agent-store.d.ts +23 -12
  6. package/dist/agent-store.js +144 -117
  7. package/dist/agents.d.ts +10 -10
  8. package/dist/agents.js +14 -26
  9. package/dist/bundles/create.d.ts +1 -0
  10. package/dist/bundles/create.js +1 -1
  11. package/dist/bundles/graph.d.ts +1 -0
  12. package/dist/bundles/graph.js +1 -1
  13. package/dist/bundles/install.d.ts +1 -0
  14. package/dist/bundles/install.js +1 -2
  15. package/dist/bundles/validate.d.ts +1 -0
  16. package/dist/bundles/validate.js +1 -1
  17. package/dist/config/import.d.ts +1 -1
  18. package/dist/config/import.js +2 -2
  19. package/dist/config/native.d.ts +5 -1
  20. package/dist/config/native.js +12 -11
  21. package/dist/config/schema.d.ts +1 -0
  22. package/dist/config/schema.js +1 -1
  23. package/dist/config/store.js +7 -7
  24. package/dist/errors.d.ts +1 -1
  25. package/dist/errors.js +0 -1
  26. package/dist/http/agent-routes.js +2 -4
  27. package/dist/http/bundle-routes.js +2 -23
  28. package/dist/http/config-routes.js +1 -4
  29. package/dist/http/server.d.ts +1 -1
  30. package/dist/http/server.js +3 -9
  31. package/dist/http/skill-routes.d.ts +0 -1
  32. package/dist/http/skill-routes.js +2 -3
  33. package/dist/http-types.d.ts +2 -8
  34. package/dist/ids.d.ts +0 -4
  35. package/dist/ids.js +0 -23
  36. package/dist/index.d.ts +0 -2
  37. package/dist/index.js +0 -1
  38. package/dist/json.d.ts +1 -4
  39. package/dist/json.js +0 -23
  40. package/dist/mcp/agent-tools.js +11 -12
  41. package/dist/mcp/server.d.ts +3 -4
  42. package/dist/mcp/server.js +3 -41
  43. package/dist/mcp/types.d.ts +0 -1
  44. package/dist/revisions.d.ts +9 -0
  45. package/dist/revisions.js +39 -0
  46. package/dist/skills/roots.d.ts +6 -7
  47. package/dist/skills/roots.js +16 -29
  48. package/dist/skills/scanner.d.ts +2 -2
  49. package/dist/skills/scanner.js +2 -2
  50. package/dist/types.d.ts +9 -6
  51. package/docs/ARCHITECTURE.md +24 -25
  52. package/docs/DATA_MODEL.md +27 -21
  53. package/docs/DEFINITIONS.md +11 -9
  54. package/docs/MCP.md +5 -5
  55. package/docs/REST.md +7 -7
  56. package/docs/SDK.md +17 -13
  57. package/docs/SECURITY.md +4 -3
  58. package/docs/SHELL_INTEGRATION.md +22 -2
  59. package/examples/basic.ts +15 -11
  60. package/package.json +9 -20
  61. package/skills/amalgm-agents/SKILL.md +69 -171
  62. package/dist/bin/agents.d.ts +0 -2
  63. package/dist/bin/agents.js +0 -5
  64. package/dist/bin/fatal.d.ts +0 -1
  65. package/dist/bin/fatal.js +0 -5
  66. package/dist/bin/mcp.d.ts +0 -2
  67. package/dist/bin/mcp.js +0 -19
  68. package/dist/bin/rest.d.ts +0 -2
  69. package/dist/bin/rest.js +0 -26
  70. package/dist/bundles/copy.d.ts +0 -12
  71. package/dist/bundles/copy.js +0 -144
  72. package/dist/cli/agent-commands.d.ts +0 -3
  73. package/dist/cli/agent-commands.js +0 -27
  74. package/dist/cli/args.d.ts +0 -7
  75. package/dist/cli/args.js +0 -31
  76. package/dist/cli/files.d.ts +0 -2
  77. package/dist/cli/files.js +0 -21
  78. package/dist/cli/help.d.ts +0 -1
  79. package/dist/cli/help.js +0 -15
  80. package/dist/cli/open.d.ts +0 -3
  81. package/dist/cli/open.js +0 -8
  82. package/dist/cli/run.d.ts +0 -1
  83. package/dist/cli/run.js +0 -33
  84. package/dist/cli.d.ts +0 -2
  85. package/dist/cli.js +0 -2
  86. package/dist/database.d.ts +0 -9
  87. package/dist/database.js +0 -35
  88. package/dist/rows.d.ts +0 -4
  89. package/dist/rows.js +0 -28
  90. package/dist/schema.d.ts +0 -2
  91. package/dist/schema.js +0 -162
  92. package/docs/CLI.md +0 -23
  93. package/docs/ENGINE_INTEGRATION.md +0 -12
@@ -4,8 +4,7 @@ export async function routeAgents(context) {
4
4
  if (resource !== 'agents')
5
5
  return false;
6
6
  if (!id && context.method === 'GET') {
7
- const includeDeleted = context.url.searchParams.get('include_deleted') === 'true';
8
- context.json(200, { agents: context.agents.listAgents(includeDeleted) });
7
+ context.json(200, { agents: context.agents.listAgents() });
9
8
  return true;
10
9
  }
11
10
  if (!id && context.method === 'POST') {
@@ -23,8 +22,7 @@ export async function routeAgents(context) {
23
22
  if (child)
24
23
  return false;
25
24
  if (context.method === 'GET') {
26
- const includeDeleted = context.url.searchParams.get('include_deleted') === 'true';
27
- const agent = context.agents.getAgent(id, includeDeleted);
25
+ const agent = context.agents.getAgent(id);
28
26
  if (!agent)
29
27
  throw new AgentError('not_found', `Agent not found: ${id}`);
30
28
  context.json(200, { agent });
@@ -1,8 +1,5 @@
1
- import { copyAgentBundle } from '../bundles/copy.js';
2
1
  import { createAgentBundle } from '../bundles/create.js';
3
2
  import { installAgentBundle } from '../bundles/install.js';
4
- import { BUNDLE_KIND, BUNDLE_SCHEMA_VERSION } from '../bundles/util.js';
5
- import { validateAgentBundle } from '../bundles/validate.js';
6
3
  import { scanInstalledSkills } from '../skills/scanner.js';
7
4
  function ids(...values) {
8
5
  const result = [];
@@ -21,22 +18,12 @@ export async function routeAgentBundles(context) {
21
18
  const [resource, action, child] = context.path;
22
19
  if (resource !== 'agent-bundles')
23
20
  return false;
24
- if (!action && context.method === 'GET') {
25
- context.json(200, {
26
- kind: BUNDLE_KIND,
27
- schemaVersion: BUNDLE_SCHEMA_VERSION,
28
- available: { agents: context.agents.listAgents().map((agent) => ({
29
- id: agent.id, name: agent.definition.name, description: agent.definition.description,
30
- })) },
31
- });
32
- return true;
33
- }
34
- if (child || context.method !== 'POST')
21
+ if (!action || child || context.method !== 'POST')
35
22
  return false;
36
23
  const body = await context.body();
37
24
  try {
38
25
  if (action === 'preview') {
39
- const installedSkills = scanInstalledSkills({ ...context.skillRoots, includeContent: true }).skills;
26
+ const installedSkills = scanInstalledSkills({ osHome: context.agents.osHome, includeContent: true }).skills;
40
27
  const result = await createAgentBundle(context.agents, {
41
28
  agentIds: ids(body.agent_id, body.agent_ids),
42
29
  automationIds: ids(body.automation_id, body.automation_ids),
@@ -46,14 +33,6 @@ export async function routeAgentBundles(context) {
46
33
  context.json(200, { ok: true, ...result });
47
34
  return true;
48
35
  }
49
- if (action === 'copy') {
50
- if (!body.bundle) {
51
- context.json(400, { error: 'bundle is required' });
52
- return true;
53
- }
54
- context.json(200, { ok: true, bundle: copyAgentBundle(validateAgentBundle(body.bundle)) });
55
- return true;
56
- }
57
36
  if (action === 'install') {
58
37
  if (!body.bundle) {
59
38
  context.json(400, { error: 'bundle is required' });
@@ -35,10 +35,7 @@ export async function routeAgentConfig(context) {
35
35
  return true;
36
36
  }
37
37
  if (action === 'import-native') {
38
- const result = importAgentConfig(context.agents, id, {
39
- ...(context.nativeHomeDir ? { homeDir: context.nativeHomeDir } : {}),
40
- replace: body.replace === true,
41
- });
38
+ const result = importAgentConfig(context.agents, id, { replace: body.replace === true });
42
39
  context.json(200, { ok: true, ...result });
43
40
  return true;
44
41
  }
@@ -1,2 +1,2 @@
1
1
  import type { RestServer, RestServerOptions } from '../http-types.js';
2
- export declare function createRestServer(options?: RestServerOptions): RestServer;
2
+ export declare function createRestServer(options: RestServerOptions): RestServer;
@@ -1,14 +1,12 @@
1
1
  import http from 'node:http';
2
- import { Agents } from '../agents.js';
3
2
  import { asAgentError } from '../errors.js';
4
3
  import { routeAgentConfig } from './config-routes.js';
5
4
  import { routeAgentBundles } from './bundle-routes.js';
6
5
  import { routeAgents } from './agent-routes.js';
7
6
  import { guardRequest, readJson, sendJson } from './request.js';
8
7
  import { routeSkills } from './skill-routes.js';
9
- export function createRestServer(options = {}) {
10
- const agents = options.agents || new Agents(options);
11
- const owned = !options.agents;
8
+ export function createRestServer(options) {
9
+ const { agents } = options;
12
10
  const bodyLimit = options.bodyLimitBytes || 512_000;
13
11
  const server = http.createServer((request, response) => {
14
12
  void dispatch(request, response).catch((error) => {
@@ -25,7 +23,7 @@ export function createRestServer(options = {}) {
25
23
  async function dispatch(request, response) {
26
24
  const url = new URL(request.url || '/', 'http://localhost');
27
25
  if (url.pathname === '/healthz') {
28
- sendJson(response, 200, agents.health());
26
+ sendJson(response, 200, { ok: true });
29
27
  return;
30
28
  }
31
29
  const verdict = guardRequest(request, options.token);
@@ -43,8 +41,6 @@ export function createRestServer(options = {}) {
43
41
  method: request.method || 'GET',
44
42
  path,
45
43
  url,
46
- skillRoots: options.skillRoots || {},
47
- ...(options.nativeHomeDir ? { nativeHomeDir: options.nativeHomeDir } : {}),
48
44
  ...(options.bundlePort ? { bundlePort: options.bundlePort } : {}),
49
45
  body: () => readJson(request, bodyLimit),
50
46
  json: (status, value) => sendJson(response, status, value),
@@ -77,8 +73,6 @@ export function createRestServer(options = {}) {
77
73
  return resolve();
78
74
  server.close((error) => error ? reject(error) : resolve());
79
75
  });
80
- if (owned)
81
- await agents.close();
82
76
  },
83
77
  };
84
78
  }
@@ -1,3 +1,2 @@
1
- /** HTTP laws from Engine `server/routes/agents.js` and `skills/rest.js`. */
2
1
  import type { RouteContext } from '../http-types.js';
3
2
  export declare function routeSkills(context: RouteContext): Promise<boolean>;
@@ -1,4 +1,3 @@
1
- /** HTTP laws from Engine `server/routes/agents.js` and `skills/rest.js`. */
2
1
  import { scanInstalledSkills } from '../skills/scanner.js';
3
2
  function truthy(value) {
4
3
  return value === '1' || value?.toLowerCase() === 'true';
@@ -10,14 +9,14 @@ export async function routeSkills(context) {
10
9
  const includeContent = truthy(context.url.searchParams.get('include_content'));
11
10
  if ((!action || action === 'list') && context.method === 'GET') {
12
11
  context.json(200, {
13
- skills: scanInstalledSkills({ ...context.skillRoots, includeContent }).skills,
12
+ skills: scanInstalledSkills({ osHome: context.agents.osHome, includeContent }).skills,
14
13
  });
15
14
  return true;
16
15
  }
17
16
  if (action === 'refresh' && context.method === 'POST') {
18
17
  context.json(200, {
19
18
  ok: true,
20
- skills: scanInstalledSkills(context.skillRoots).skills,
19
+ skills: scanInstalledSkills({ osHome: context.agents.osHome }).skills,
21
20
  });
22
21
  return true;
23
22
  }
@@ -1,15 +1,11 @@
1
1
  import type { Server } from 'node:http';
2
2
  import type { AddressInfo } from 'node:net';
3
3
  import type { Agents } from './agents.js';
4
- import type { AgentsOptions } from './types.js';
5
- import type { SkillRootOptions } from './skills/roots.js';
6
4
  import type { AgentBundlePort } from './bundles/types.js';
7
- export interface RestServerOptions extends AgentsOptions {
8
- agents?: Agents;
5
+ export interface RestServerOptions {
6
+ agents: Agents;
9
7
  token?: string;
10
8
  bodyLimitBytes?: number;
11
- skillRoots?: SkillRootOptions;
12
- nativeHomeDir?: string;
13
9
  bundlePort?: AgentBundlePort;
14
10
  }
15
11
  export interface RestServer {
@@ -23,8 +19,6 @@ export interface RouteContext {
23
19
  method: string;
24
20
  path: string[];
25
21
  url: URL;
26
- skillRoots: SkillRootOptions;
27
- nativeHomeDir?: string;
28
22
  bundlePort?: AgentBundlePort;
29
23
  body(): Promise<Record<string, unknown>>;
30
24
  json(status: number, value: unknown): void;
package/dist/ids.d.ts CHANGED
@@ -1,5 +1 @@
1
- export declare function newId(prefix: string): string;
2
1
  export declare function requireId(value: unknown, field: string): string;
3
- export declare function optionalId(value: unknown, field: string): string | undefined;
4
- export declare function randomKey(prefix: string): string;
5
- export declare function optionalKey(value: unknown): string | undefined;
package/dist/ids.js CHANGED
@@ -1,9 +1,5 @@
1
- import crypto from 'node:crypto';
2
1
  import { AgentError } from './errors.js';
3
2
  const ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,127}$/;
4
- export function newId(prefix) {
5
- return `${prefix}-${crypto.randomUUID()}`;
6
- }
7
3
  export function requireId(value, field) {
8
4
  const id = typeof value === 'string' ? value.trim() : '';
9
5
  if (!ID_PATTERN.test(id)) {
@@ -11,22 +7,3 @@ export function requireId(value, field) {
11
7
  }
12
8
  return id;
13
9
  }
14
- export function optionalId(value, field) {
15
- if (value === undefined || value === null || value === '')
16
- return undefined;
17
- return requireId(value, field);
18
- }
19
- export function randomKey(prefix) {
20
- return newId(prefix);
21
- }
22
- export function optionalKey(value) {
23
- if (value === undefined || value === null || value === '')
24
- return undefined;
25
- if (typeof value !== 'string')
26
- throw new AgentError('invalid_input', 'idempotency key must be a string.');
27
- const key = value.trim();
28
- if (!key || key.length > 256 || /[\u0000-\u001f\u007f]/.test(key)) {
29
- throw new AgentError('invalid_input', 'idempotency key must be 1-256 printable characters.');
30
- }
31
- return key;
32
- }
package/dist/index.d.ts CHANGED
@@ -11,8 +11,6 @@ export { configFromAgent, listAgentConfigs, updateAgentConfig } from './config/s
11
11
  export { importAgentConfig } from './config/import.js';
12
12
  export { importNativeConfig } from './config/native.js';
13
13
  export type * from './config/types.js';
14
- export { copyAgentBundle } from './bundles/copy.js';
15
- export type { CopyBundleOptions } from './bundles/copy.js';
16
14
  export { createAgentBundle } from './bundles/create.js';
17
15
  export type { CreateBundleOptions } from './bundles/create.js';
18
16
  export { installAgentBundle } from './bundles/install.js';
package/dist/index.js CHANGED
@@ -7,7 +7,6 @@ export { normalizeAgentConfig, stableConfigId } from './config/schema.js';
7
7
  export { configFromAgent, listAgentConfigs, updateAgentConfig } from './config/store.js';
8
8
  export { importAgentConfig } from './config/import.js';
9
9
  export { importNativeConfig } from './config/native.js';
10
- export { copyAgentBundle } from './bundles/copy.js';
11
10
  export { createAgentBundle } from './bundles/create.js';
12
11
  export { installAgentBundle } from './bundles/install.js';
13
12
  export { buildBundleGraph } from './bundles/graph.js';
package/dist/json.d.ts CHANGED
@@ -1,7 +1,4 @@
1
- import type { JsonObject, JsonValue } from './types.js';
1
+ import type { JsonValue } from './types.js';
2
2
  export declare function isObject(value: unknown): value is Record<string, unknown>;
3
3
  export declare function jsonClone<T extends JsonValue>(value: T): T;
4
- export declare function parseObject(value: string): JsonObject;
5
4
  export declare function canonicalJson(value: JsonValue): string;
6
- export declare function assertJsonObject(value: unknown, field: string): JsonObject;
7
- export declare function assertByteLimit(value: JsonValue, limit: number, label: string): void;
package/dist/json.js CHANGED
@@ -1,16 +1,9 @@
1
- import { AgentError } from './errors.js';
2
1
  export function isObject(value) {
3
2
  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
4
3
  }
5
4
  export function jsonClone(value) {
6
5
  return JSON.parse(JSON.stringify(value));
7
6
  }
8
- export function parseObject(value) {
9
- const parsed = JSON.parse(value);
10
- if (!isObject(parsed))
11
- throw new AgentError('internal', 'Stored JSON is not an object.');
12
- return parsed;
13
- }
14
7
  function sortValue(value) {
15
8
  if (Array.isArray(value))
16
9
  return value.map(sortValue);
@@ -23,19 +16,3 @@ function sortValue(value) {
23
16
  export function canonicalJson(value) {
24
17
  return JSON.stringify(sortValue(value));
25
18
  }
26
- export function assertJsonObject(value, field) {
27
- if (!isObject(value))
28
- throw new AgentError('invalid_input', `${field} must be an object.`);
29
- try {
30
- return JSON.parse(JSON.stringify(value));
31
- }
32
- catch {
33
- throw new AgentError('invalid_input', `${field} must contain JSON values only.`);
34
- }
35
- }
36
- export function assertByteLimit(value, limit, label) {
37
- const bytes = Buffer.byteLength(JSON.stringify(value));
38
- if (bytes > limit) {
39
- throw new AgentError('too_large', `${label} is ${bytes} bytes; maximum is ${limit}.`, { bytes, limit });
40
- }
41
- }
@@ -4,24 +4,23 @@ export function agentTools(agents) {
4
4
  return [
5
5
  {
6
6
  name: 'agents_list',
7
- description: 'List persistent agent definitions. This does not list chats.',
8
- inputSchema: objectSchema({ include_deleted: { type: 'boolean' } }),
9
- handler(input) {
10
- return toolResult({ agents: agents.listAgents(input.include_deleted === true) });
7
+ description: 'List the agents in this user\'s agents folder. This does not list chats.',
8
+ inputSchema: objectSchema({}),
9
+ handler() {
10
+ return toolResult({ agents: agents.listAgents() });
11
11
  },
12
12
  },
13
13
  {
14
14
  name: 'agents_get',
15
- description: 'Read one agent and its current immutable revision.',
16
- inputSchema: objectSchema({ agent_id: string, include_deleted: { type: 'boolean' } }, ['agent_id']),
15
+ description: 'Read one agent: its definition, pinned state, and current revision id.',
16
+ inputSchema: objectSchema({ agent_id: string }, ['agent_id']),
17
17
  handler(input) {
18
- const id = stringArg(input, 'agent_id');
19
- return toolResult({ agent: agents.getAgent(id, input.include_deleted === true) });
18
+ return toolResult({ agent: agents.getAgent(stringArg(input, 'agent_id')) });
20
19
  },
21
20
  },
22
21
  {
23
22
  name: 'agents_create',
24
- description: 'Create an agent from a complete definition.',
23
+ description: 'Create an agent from a complete definition. Without definition.id the agent gets a new UUID.',
25
24
  inputSchema: objectSchema({ definition: { type: 'object' } }, ['definition']),
26
25
  handler(input) {
27
26
  return toolResult({
@@ -31,7 +30,7 @@ export function agentTools(agents) {
31
30
  },
32
31
  {
33
32
  name: 'agents_update',
34
- description: 'Patch an agent. Executable changes create an immutable revision.',
33
+ description: 'Patch an agent\'s definition. Renaming it renames its folder once the agent is idle.',
35
34
  inputSchema: objectSchema({ agent_id: string, patch: { type: 'object' } }, ['agent_id', 'patch']),
36
35
  handler(input) {
37
36
  return toolResult({
@@ -41,7 +40,7 @@ export function agentTools(agents) {
41
40
  },
42
41
  {
43
42
  name: 'agents_set_pinned',
44
- description: 'Pin or unpin an agent. Pinned agents appear wherever a user picks an agent; this creates no revision.',
43
+ description: 'Pin or unpin an agent. Pinned agents appear wherever a user picks an agent; the definition is unchanged.',
45
44
  inputSchema: objectSchema({ agent_id: string, pinned: { type: 'boolean' } }, ['agent_id', 'pinned']),
46
45
  handler(input) {
47
46
  return toolResult({
@@ -51,7 +50,7 @@ export function agentTools(agents) {
51
50
  },
52
51
  {
53
52
  name: 'agents_delete',
54
- description: 'Tombstone an agent identity while retaining its immutable revisions. Built-in agents cannot be deleted; unpin them instead.',
53
+ description: 'Delete an agent and its folder. Built-in agents cannot be deleted; unpin them instead.',
55
54
  inputSchema: objectSchema({ agent_id: string }, ['agent_id']),
56
55
  handler(input) {
57
56
  return toolResult({ agent: agents.deleteAgent(stringArg(input, 'agent_id')) });
@@ -1,6 +1,5 @@
1
- import { Agents } from '../agents.js';
2
- import type { AgentsOptions } from '../types.js';
1
+ import type { Agents } from '../agents.js';
3
2
  import type { McpServer } from './types.js';
4
- export declare function createMcpServer(options?: AgentsOptions & {
5
- agents?: Agents;
3
+ export declare function createMcpServer(options: {
4
+ agents: Agents;
6
5
  }): McpServer;
@@ -1,14 +1,10 @@
1
- import readline from 'node:readline';
2
- import { Agents } from '../agents.js';
3
- import { asAgentError } from '../errors.js';
4
1
  import { createMcpTools } from './tools.js';
5
2
  function descriptor(tool) {
6
3
  const { handler, ...definition } = tool;
7
4
  return definition;
8
5
  }
9
- export function createMcpServer(options = {}) {
10
- const agents = options.agents || new Agents(options);
11
- const owned = !options.agents;
6
+ export function createMcpServer(options) {
7
+ const { agents } = options;
12
8
  const tools = createMcpTools(agents);
13
9
  const byName = new Map(tools.map((tool) => [tool.name, tool]));
14
10
  async function handle(message) {
@@ -35,39 +31,5 @@ export function createMcpServer(options = {}) {
35
31
  return undefined;
36
32
  throw Object.assign(new Error(`Method not found: ${message.method}`), { rpcCode: -32601 });
37
33
  }
38
- async function start(input = process.stdin, output = process.stdout) {
39
- const lines = readline.createInterface({ input, crlfDelay: Infinity });
40
- lines.on('line', (line) => {
41
- void respond(line, output);
42
- });
43
- return async () => {
44
- lines.close();
45
- if (owned)
46
- await agents.close();
47
- };
48
- }
49
- async function respond(line, output) {
50
- let request;
51
- try {
52
- request = JSON.parse(line);
53
- const result = await handle(request);
54
- if (request.id === undefined || result === undefined)
55
- return;
56
- output.write(`${JSON.stringify({ jsonrpc: '2.0', id: request.id, result })}\n`);
57
- }
58
- catch (error) {
59
- if (request?.id === undefined)
60
- return;
61
- const normalized = asAgentError(error);
62
- const rpcCode = typeof error === 'object' && error && 'rpcCode' in error
63
- ? Number(error.rpcCode)
64
- : -32603;
65
- output.write(`${JSON.stringify({
66
- jsonrpc: '2.0',
67
- id: request.id,
68
- error: { code: rpcCode, message: normalized.message, data: { code: normalized.code } },
69
- })}\n`);
70
- }
71
- }
72
- return { tools, handle, start };
34
+ return { tools, handle };
73
35
  }
@@ -14,5 +14,4 @@ export interface JsonRpcRequest {
14
14
  export interface McpServer {
15
15
  tools: McpTool[];
16
16
  handle(message: JsonRpcRequest): Promise<unknown>;
17
- start(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Promise<() => Promise<void>>;
18
17
  }
@@ -0,0 +1,9 @@
1
+ /**
2
+ * A revision is one exact definition, named by its hash. Each one the store
3
+ * hands out is saved in `.private/revisions/<id>.json`, so a turn started from
4
+ * an older revision still resolves it after the agent is edited.
5
+ */
6
+ import type { AgentDefinition, AgentRevision } from './types.js';
7
+ /** Saves the definition as a revision unless it already is one; returns its id. */
8
+ export declare function keepRevision(privateDir: string, definition: AgentDefinition): string;
9
+ export declare function readRevision(privateDir: string, id: string): AgentRevision;
@@ -0,0 +1,39 @@
1
+ /**
2
+ * A revision is one exact definition, named by its hash. Each one the store
3
+ * hands out is saved in `.private/revisions/<id>.json`, so a turn started from
4
+ * an older revision still resolves it after the agent is edited.
5
+ */
6
+ import crypto from 'node:crypto';
7
+ import fs from 'node:fs';
8
+ import path from 'node:path';
9
+ import { definitionHash } from './definition.js';
10
+ import { AgentError } from './errors.js';
11
+ const REVISIONS_DIR = 'revisions';
12
+ const REVISION_ID = /^revision-[0-9a-f]{16}$/;
13
+ function revisionFile(privateDir, id) {
14
+ return path.join(privateDir, REVISIONS_DIR, `${id}.json`);
15
+ }
16
+ /** Saves the definition as a revision unless it already is one; returns its id. */
17
+ export function keepRevision(privateDir, definition) {
18
+ const hash = definitionHash(definition);
19
+ const id = `revision-${hash.slice(0, 16)}`;
20
+ const file = revisionFile(privateDir, id);
21
+ if (fs.existsSync(file))
22
+ return id;
23
+ const revision = { id, agentId: definition.id, hash, definition, createdAt: new Date().toISOString() };
24
+ const temp = `${file}.${crypto.randomUUID()}`;
25
+ fs.mkdirSync(path.dirname(file), { recursive: true });
26
+ fs.writeFileSync(temp, `${JSON.stringify(revision, null, 2)}\n`);
27
+ fs.renameSync(temp, file);
28
+ return id;
29
+ }
30
+ export function readRevision(privateDir, id) {
31
+ try {
32
+ if (REVISION_ID.test(id))
33
+ return JSON.parse(fs.readFileSync(revisionFile(privateDir, id), 'utf8'));
34
+ }
35
+ catch {
36
+ // A missing or unreadable revision is not found.
37
+ }
38
+ throw new AgentError('not_found', `Agent revision not found: ${id}`);
39
+ }
@@ -1,9 +1,8 @@
1
- /** Canonical installed-skill roots from Engine `skills/roots.js`. */
1
+ /** Where harness CLIs keep installed skills: the project's `.agents/skills` folders and the OS home. */
2
2
  export interface SkillRootOptions {
3
+ /** The OS account home, read only. */
4
+ osHome: string;
3
5
  selectedCwd?: string;
4
- homeDir?: string;
5
- codexHome?: string;
6
- claudeConfigDir?: string;
7
6
  }
8
7
  export interface SkillRootClassification {
9
8
  provider: 'shared' | 'codex' | 'claude_code' | 'opencode';
@@ -11,6 +10,6 @@ export interface SkillRootClassification {
11
10
  rootLabel: string;
12
11
  }
13
12
  export declare function normalizePath(value: unknown): string;
14
- export declare function buildCanonicalSkillRoots(options?: SkillRootOptions): string[];
15
- export declare function isCodexWorktreeRoot(rootPath: string, options?: SkillRootOptions): boolean;
16
- export declare function classifySkillRoot(rootPath: string, options?: SkillRootOptions): SkillRootClassification;
13
+ export declare function buildCanonicalSkillRoots(options: SkillRootOptions): string[];
14
+ export declare function isCodexWorktreeRoot(rootPath: string, options: SkillRootOptions): boolean;
15
+ export declare function classifySkillRoot(rootPath: string, options: SkillRootOptions): SkillRootClassification;
@@ -1,6 +1,5 @@
1
- /** Canonical installed-skill roots from Engine `skills/roots.js`. */
1
+ /** Where harness CLIs keep installed skills: the project's `.agents/skills` folders and the OS home. */
2
2
  import fs from 'node:fs';
3
- import os from 'node:os';
4
3
  import path from 'node:path';
5
4
  export function normalizePath(value) {
6
5
  return typeof value === 'string' && value.trim() ? path.resolve(value.trim()) : '';
@@ -19,9 +18,6 @@ function existingDirectory(value) {
19
18
  function uniquePaths(values) {
20
19
  return [...new Set(values.map(normalizePath).filter(Boolean))];
21
20
  }
22
- function nativeHome(options) {
23
- return normalizePath(options.homeDir || process.env.AMALGM_NATIVE_HOME || os.homedir());
24
- }
25
21
  function projectRoots(selectedCwd) {
26
22
  const roots = [];
27
23
  let current = existingDirectory(selectedCwd);
@@ -50,37 +46,30 @@ function worktreeRoots(home) {
50
46
  return [];
51
47
  }
52
48
  }
53
- export function buildCanonicalSkillRoots(options = {}) {
54
- const selectedCwd = normalizePath(options.selectedCwd);
55
- const home = nativeHome(options);
56
- const codexHome = normalizePath(options.codexHome || process.env.CODEX_HOME);
57
- const claudeConfig = normalizePath(options.claudeConfigDir || process.env.CLAUDE_CONFIG_DIR);
49
+ export function buildCanonicalSkillRoots(options) {
50
+ const home = normalizePath(options.osHome);
58
51
  return uniquePaths([
59
- ...projectRoots(selectedCwd),
60
- home && path.join(home, '.agents', 'skills'),
61
- codexHome && path.join(codexHome, 'skills'),
62
- home && path.join(home, '.codex', 'skills'),
52
+ ...projectRoots(normalizePath(options.selectedCwd)),
53
+ path.join(home, '.agents', 'skills'),
54
+ path.join(home, '.codex', 'skills'),
63
55
  ...worktreeRoots(home),
64
- claudeConfig && path.join(claudeConfig, 'skills'),
65
- home && path.join(home, '.claude', 'skills'),
66
- home && path.join(home, '.config', 'claude', 'skills'),
67
- home && path.join(home, '.config', 'opencode', 'skills'),
68
- home && path.join(home, '.opencode', 'skills'),
56
+ path.join(home, '.claude', 'skills'),
57
+ path.join(home, '.config', 'claude', 'skills'),
58
+ path.join(home, '.config', 'opencode', 'skills'),
59
+ path.join(home, '.opencode', 'skills'),
69
60
  ]).filter(existingDirectory);
70
61
  }
71
- export function isCodexWorktreeRoot(rootPath, options = {}) {
62
+ export function isCodexWorktreeRoot(rootPath, options) {
72
63
  const root = normalizePath(rootPath);
73
- const home = nativeHome(options);
64
+ const home = normalizePath(options.osHome);
74
65
  const worktrees = `${normalizePath(path.join(home, '.codex', 'worktrees'))}${path.sep}`;
75
66
  return Boolean(root && home && root.startsWith(worktrees)
76
67
  && root.endsWith(path.normalize(path.join('.agents', 'skills'))));
77
68
  }
78
- export function classifySkillRoot(rootPath, options = {}) {
69
+ export function classifySkillRoot(rootPath, options) {
79
70
  const root = normalizePath(rootPath);
80
71
  const selectedCwd = normalizePath(options.selectedCwd);
81
- const home = nativeHome(options);
82
- const codexHome = normalizePath(options.codexHome || process.env.CODEX_HOME);
83
- const claudeConfig = normalizePath(options.claudeConfigDir || process.env.CLAUDE_CONFIG_DIR);
72
+ const home = normalizePath(options.osHome);
84
73
  if ((selectedCwd && root.startsWith(path.join(selectedCwd, '.agents', 'skills')))
85
74
  || root.endsWith(path.normalize(path.join('.agents', 'skills')))) {
86
75
  return { provider: 'shared', scope: 'project', rootLabel: 'Project skills' };
@@ -88,12 +77,10 @@ export function classifySkillRoot(rootPath, options = {}) {
88
77
  if (root === normalizePath(path.join(home, '.agents', 'skills'))) {
89
78
  return { provider: 'shared', scope: 'global', rootLabel: 'Shared global skills' };
90
79
  }
91
- if ((codexHome && root === normalizePath(path.join(codexHome, 'skills')))
92
- || root === normalizePath(path.join(home, '.codex', 'skills'))) {
80
+ if (root === normalizePath(path.join(home, '.codex', 'skills'))) {
93
81
  return { provider: 'codex', scope: 'global', rootLabel: 'Codex skills' };
94
82
  }
95
- if ((claudeConfig && root === normalizePath(path.join(claudeConfig, 'skills')))
96
- || root === normalizePath(path.join(home, '.claude', 'skills'))
83
+ if (root === normalizePath(path.join(home, '.claude', 'skills'))
97
84
  || root === normalizePath(path.join(home, '.config', 'claude', 'skills'))) {
98
85
  return { provider: 'claude_code', scope: 'global', rootLabel: 'Claude Code skills' };
99
86
  }
@@ -1,4 +1,4 @@
1
- /** Installed-skill scanner from Engine `skills/scanner.js`. */
1
+ /** Lists the skills installed in the skill roots, each read from its `SKILL.md`. */
2
2
  import type { SkillRootOptions } from './roots.js';
3
3
  export interface InstalledSkill {
4
4
  id: string;
@@ -26,7 +26,7 @@ export interface SkillScanOptions extends SkillRootOptions {
26
26
  now?: () => string;
27
27
  }
28
28
  export declare function parseSkillFrontmatter(markdown: unknown): Record<string, string>;
29
- export declare function scanInstalledSkills(options?: SkillScanOptions): {
29
+ export declare function scanInstalledSkills(options: SkillScanOptions): {
30
30
  roots: string[];
31
31
  skills: InstalledSkill[];
32
32
  };
@@ -1,4 +1,4 @@
1
- /** Installed-skill scanner from Engine `skills/scanner.js`. */
1
+ /** Lists the skills installed in the skill roots, each read from its `SKILL.md`. */
2
2
  import crypto from 'node:crypto';
3
3
  import fs from 'node:fs';
4
4
  import path from 'node:path';
@@ -87,7 +87,7 @@ function entries(root) {
87
87
  return [];
88
88
  }
89
89
  }
90
- export function scanInstalledSkills(options = {}) {
90
+ export function scanInstalledSkills(options) {
91
91
  const roots = buildCanonicalSkillRoots(options);
92
92
  const paths = new Set();
93
93
  const resolved = new Set();