@amalgm/agents 0.2.0 → 0.2.1

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 (55) hide show
  1. package/PURPOSE.md +27 -25
  2. package/README.md +46 -19
  3. package/dist/agents.d.ts +26 -4
  4. package/dist/agents.js +87 -4
  5. package/dist/bin/mcp.js +1 -1
  6. package/dist/cli/help.d.ts +1 -1
  7. package/dist/cli/help.js +13 -2
  8. package/dist/cli/open.d.ts +1 -1
  9. package/dist/cli/open.js +5 -1
  10. package/dist/cli/run.js +8 -3
  11. package/dist/cli/session-commands.d.ts +4 -0
  12. package/dist/cli/session-commands.js +54 -0
  13. package/dist/drivers.d.ts +4 -0
  14. package/dist/drivers.js +25 -0
  15. package/dist/errors.d.ts +1 -1
  16. package/dist/errors.js +2 -0
  17. package/dist/event-store.d.ts +13 -0
  18. package/dist/event-store.js +50 -0
  19. package/dist/http/server.js +7 -1
  20. package/dist/http/session-routes.d.ts +2 -0
  21. package/dist/http/session-routes.js +67 -0
  22. package/dist/http/stream.d.ts +3 -0
  23. package/dist/http/stream.js +30 -0
  24. package/dist/index.d.ts +2 -0
  25. package/dist/index.js +2 -0
  26. package/dist/mcp/agent-tools.js +1 -1
  27. package/dist/mcp/session-tools.d.ts +3 -0
  28. package/dist/mcp/session-tools.js +81 -0
  29. package/dist/mcp/tools.js +2 -1
  30. package/dist/messages.d.ts +3 -0
  31. package/dist/messages.js +56 -0
  32. package/dist/rows.d.ts +4 -1
  33. package/dist/rows.js +39 -0
  34. package/dist/runtime.d.ts +29 -0
  35. package/dist/runtime.js +176 -0
  36. package/dist/schema.js +101 -53
  37. package/dist/session-store.d.ts +15 -0
  38. package/dist/session-store.js +83 -0
  39. package/dist/turn-store.d.ts +31 -0
  40. package/dist/turn-store.js +164 -0
  41. package/dist/types.d.ts +106 -0
  42. package/docs/ARCHITECTURE.md +33 -21
  43. package/docs/CLI.md +43 -3
  44. package/docs/DATA_MODEL.md +46 -7
  45. package/docs/DEFINITIONS.md +4 -4
  46. package/docs/DRIVERS.md +72 -0
  47. package/docs/ENGINE_INTEGRATION.md +67 -22
  48. package/docs/MCP.md +19 -3
  49. package/docs/REST.md +97 -14
  50. package/docs/SDK.md +61 -12
  51. package/docs/SECURITY.md +35 -6
  52. package/examples/basic.ts +22 -8
  53. package/package.json +5 -5
  54. package/skills/amalgm-agents/SKILL.md +12 -3
  55. package/skills/amalgm-agents/agents/openai.yaml +2 -2
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@amalgm/agents",
3
- "version": "0.2.0",
4
- "description": "Local-first agent identities, installations, and immutable revisions.",
3
+ "version": "0.2.1",
4
+ "description": "Local-first agent definitions, immutable revisions, and durable sessions.",
5
5
  "license": "UNLICENSED",
6
6
  "private": false,
7
7
  "repository": {
@@ -42,17 +42,17 @@
42
42
  "README.md"
43
43
  ],
44
44
  "scripts": {
45
- "build": "rm -rf dist && tsc -p tsconfig.build.json && tsx scripts/mark-executables.ts",
45
+ "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsx scripts/mark-executables.ts",
46
46
  "check": "tsx scripts/check-tree.ts && tsc -p tsconfig.json && tsc -p tsconfig.test.json",
47
47
  "test": "tsx --test --test-concurrency=1 --test-timeout=30000 test/*.test.ts",
48
48
  "verify": "npm run check && npm run build && npm test",
49
49
  "prepack": "npm run build"
50
50
  },
51
51
  "engines": {
52
- "node": ">=20"
52
+ "node": ">=24"
53
53
  },
54
54
  "dependencies": {
55
- "@amalgm/core": "^0.1.0",
55
+ "@amalgm/core": "0.4.7",
56
56
  "@types/better-sqlite3": "^7.6.13",
57
57
  "@types/node": "^20.19.43",
58
58
  "better-sqlite3": "^12.6.2"
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: amalgm-agents
3
- description: Create, inspect, edit, delete, install, and resolve persistent Amalgm agent identities and immutable revisions. Use when a user wants to manage an agent definition or discover available agents.
3
+ description: Create, inspect, edit, delete, and talk to persistent Amalgm agents and their existing sessions. Use when a user wants to manage an agent definition, discover available agents, delegate work to an agent, continue an agent session, or inspect its transcript. Agents are separate from Chat conversations.
4
4
  ---
5
5
 
6
6
  # Amalgm Agents
@@ -17,5 +17,14 @@ Use the available Agents MCP tools. If MCP is unavailable, use the equivalent
17
17
  5. Keep tool, skill, file, credential, and subagent values as references; do
18
18
  not copy those products into the agent definition.
19
19
 
20
- To run an agent, resolve its identity here and use Chat. Agents has no
21
- conversation, execution, transcript, interrupt, or reconnect operation.
20
+ ## Talk to an agent
21
+
22
+ 1. Resolve the agent with `agents_list` or `agents_get` when its identity is
23
+ ambiguous.
24
+ 2. Call `talk_to_agent` without a session ID to start a session.
25
+ 3. Preserve and return the resulting session ID.
26
+ 4. Pass that ID to continue the same session.
27
+ 5. Use conversation/session inspection to recover durable results or history.
28
+ 6. Use background execution for work likely to outlive one MCP request.
29
+
30
+ Never create a Chat conversation merely to represent an Agents session.
@@ -1,4 +1,4 @@
1
1
  interface:
2
2
  display_name: "Amalgm Agents"
3
- short_description: "Create and manage Amalgm agents"
4
- default_prompt: "Use $amalgm-agents to create or manage an agent."
3
+ short_description: "Create, manage, and talk to Amalgm agents"
4
+ default_prompt: "Use $amalgm-agents to create or talk to an agent."