melchizedek-agents 1.11.1 → 1.13.0

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 (63) hide show
  1. package/.env.example +53 -10
  2. package/AGENT_SETUP.md +4 -1
  3. package/CHANGELOG.md +125 -0
  4. package/DOCUMENTATION.md +108 -7
  5. package/ONBOARDING.md +15 -9
  6. package/QUICKSTART.md +5 -3
  7. package/README.md +7 -4
  8. package/config/agents/examples/classifier.yaml +104 -0
  9. package/config/agents/examples/model_zoo.yaml +5 -0
  10. package/config/agents/syndicate.schema.json +59 -1
  11. package/config/agents/syndicateSchema.yaml +9 -1
  12. package/config/agents/templates/README.md +2 -1
  13. package/config/agents/templates/prompt_writer.yaml +513 -0
  14. package/db/hardening.sql +5 -0
  15. package/db/migrations/0022_typesafe_jev_pricing.sql +36 -0
  16. package/db/migrations/0023_memory_embedder.sql +66 -0
  17. package/dist/lib/config.d.ts +6 -0
  18. package/dist/lib/config.js +6 -0
  19. package/dist/lib/doctor.d.ts +8 -0
  20. package/dist/lib/doctor.js +17 -0
  21. package/dist/lib/loadSyndicate.d.ts +1 -1
  22. package/dist/lib/memory/providers.d.ts +31 -0
  23. package/dist/lib/memory/providers.js +82 -2
  24. package/dist/lib/memory/reembed.d.ts +47 -0
  25. package/dist/lib/memory/reembed.js +71 -0
  26. package/dist/lib/memory/store.d.ts +22 -0
  27. package/dist/lib/memory/store.js +33 -0
  28. package/dist/lib/memory/supabaseMemoryService.d.ts +17 -0
  29. package/dist/lib/memory/supabaseMemoryService.js +55 -1
  30. package/dist/lib/model.d.ts +4 -0
  31. package/dist/lib/model.js +3 -0
  32. package/dist/lib/models/adapterResolver.js +5 -2
  33. package/dist/lib/models/capabilities.d.ts +2 -0
  34. package/dist/lib/models/capabilities.js +28 -6
  35. package/dist/lib/models/chatCompletionsAdapter.d.ts +6 -1
  36. package/dist/lib/models/chatCompletionsAdapter.js +35 -6
  37. package/dist/lib/models/contract.d.ts +7 -1
  38. package/dist/lib/models/endpoints.d.ts +3 -2
  39. package/dist/lib/models/endpoints.js +6 -2
  40. package/dist/lib/models/gateway.d.ts +123 -7
  41. package/dist/lib/models/gateway.js +204 -22
  42. package/dist/lib/models/gatewayAdapter.d.ts +17 -6
  43. package/dist/lib/models/gatewayAdapter.js +28 -10
  44. package/dist/lib/models/jev.d.ts +190 -0
  45. package/dist/lib/models/jev.js +316 -0
  46. package/dist/lib/models/jevAdapter.d.ts +79 -0
  47. package/dist/lib/models/jevAdapter.js +136 -0
  48. package/dist/lib/models/providerMap.d.ts +2 -1
  49. package/dist/lib/models/providerMap.js +4 -0
  50. package/dist/lib/models/registry.d.ts +3 -3
  51. package/dist/lib/models/registry.js +11 -4
  52. package/dist/lib/observability/tracer.d.ts +1 -1
  53. package/dist/lib/onboarding.js +9 -4
  54. package/dist/lib/storage/postgres/memoryStore.js +27 -0
  55. package/dist/lib/syndicateSchema.d.ts +16 -0
  56. package/dist/lib/syndicateSchema.js +2 -1
  57. package/dist/lib/tools/credentialEnv.js +1 -1
  58. package/package.json +2 -1
  59. package/skills/briefs/melchizedek-author.md +1 -1
  60. package/skills/briefs/melchizedek-models.md +6 -5
  61. package/skills/briefs/melchizedek.md +2 -2
  62. package/skills/melchizedek-onboard/SKILL.md +1 -1
  63. package/skills/melchizedek-onboard-keys/SKILL.md +2 -2
@@ -0,0 +1,104 @@
1
+ # tier: typesafe — needs only TYPESAFE_API_KEY, or one MODEL_GATEWAY key (Vercel AI Gateway or OpenRouter); `npm run doctor` shows what each key unlocks.
2
+ # ============================================================
3
+ # CLASSIFIER — one decision model, typed answers, calibrated confidence.
4
+ # ============================================================
5
+ #
6
+ # JOB: read one inbound support message and decide three things about it:
7
+ # which team it belongs to, how urgent it is, and whether a person must
8
+ # look before anything is sent back. The reply is one JSON object the
9
+ # `output.schema` below describes, so the software that calls this agent
10
+ # acts on fields, never on prose.
11
+ #
12
+ # WHY A DECISION MODEL: `model: jev-latest` is TypeSafe's Jev, a System One
13
+ # model (https://typesafe.ai). It writes no sentences and calls no tool: it
14
+ # answers typed questions with a probability for every option, in about a
15
+ # tenth of a second, at $0.042 per million input tokens and nothing for
16
+ # output. The engine turns this file's schema into Jev's questions
17
+ # (lib/models/jev.ts): a boolean property is a yes/no question, a string
18
+ # whose `oneOf` describes each constant is a choice, an integer whose
19
+ # `oneOf` describes the levels 0, 1, 2 in order is a score. The property's
20
+ # `description` is the question. The instruction below and the message are
21
+ # the state Jev decides about.
22
+ #
23
+ # WHAT COMES BACK: the schema's object, plus a `jev` key holding the raw
24
+ # answers: each question's probabilities and confidence. Act when the
25
+ # confidence is high and route to a person when it is not: that threshold
26
+ # is yours to set in the code that calls this agent, which is the point.
27
+ #
28
+ # {"department":"technical","urgency":2,"needs_human":false,
29
+ # "jev":{"department":{"type":"choice","choice":"technical","confidence":0.91,
30
+ # "probabilities":{"billing":0.03,"technical":0.91,"sales":0.01,"other":0.05}},
31
+ # "urgency":{"type":"score","score":1.8,"confidence":0.8,...},
32
+ # "needs_human":{"type":"noul","noul":0.12}}}
33
+ #
34
+ # ONE FILE, ANY MODEL: change `model:` to gemini-3.5-flash-lite,
35
+ # claude-haiku-5-5 or ollama/qwen3.5:9b and the same schema is answered by a
36
+ # chat model's structured output (the matrix's `structured_output` cell);
37
+ # the `jev` key then does not appear, since a chat model states no
38
+ # probabilities. The doctor shows what each path keeps.
39
+ #
40
+ # NOT A CONVERSATION: memory_system internal-only and includeContents none
41
+ # make every message stand alone; nothing is kept between calls.
42
+ #
43
+ # MAKE IT YOURS: rename the departments and their descriptions, change the
44
+ # urgency levels (up to 10, each described), add a boolean per policy you
45
+ # enforce. Every property must be a decision: a free string, an array or a
46
+ # nested object is refused before any call (TYPESAFE_SCHEMA_UNSUPPORTED),
47
+ # with the shapes Jev takes named in the error.
48
+ # ============================================================
49
+ syndicate_name: "Classifier"
50
+ memory_system: internal-only
51
+
52
+ orchestrator:
53
+ name: "Triage"
54
+ description: "Decides a support message's department, its urgency and whether a person must look, as typed answers with probabilities."
55
+ model: "jev-latest"
56
+ includeContents: none
57
+ instruction: |
58
+ You triage inbound messages for a software company's support desk. Each message was sent by a customer or a prospect through the help form or by email. You decide where it goes and how fast; you do not answer it.
59
+
60
+ Departments:
61
+ - billing handles charges, refunds, invoices, subscriptions and payment methods.
62
+ - technical handles bugs, outages, errors, integrations and anything about how the product behaves.
63
+ - sales handles pricing questions, quotes, upgrades, trials and new accounts.
64
+ - other is anything else: partnerships, press, job applications, spam.
65
+
66
+ Urgency is about the customer's situation, not their tone: an outage or a blocked payment is urgent however calmly it is written; a question with no deadline is not, however angrily.
67
+
68
+ A person must look before any automated reply when the message mentions legal action, a safety or security concern, a complaint about staff, a request to delete an account or data, or when it is unclear which department it belongs to.
69
+ output:
70
+ schema:
71
+ type: object
72
+ properties:
73
+ department:
74
+ type: string
75
+ description: "Which team should handle this message."
76
+ oneOf:
77
+ - const: billing
78
+ description: "Charges, refunds, invoices, subscriptions, payment methods."
79
+ - const: technical
80
+ description: "Bugs, outages, errors, integrations, product behaviour."
81
+ - const: sales
82
+ description: "Pricing, quotes, upgrades, trials, new accounts."
83
+ - const: other
84
+ description: "Partnerships, press, job applications, spam, or nothing above."
85
+ urgency:
86
+ type: integer
87
+ description: "How soon the company must act on this message."
88
+ oneOf:
89
+ - const: 0
90
+ description: "No deadline and nothing blocked: a question or a request that can wait days."
91
+ - const: 1
92
+ description: "Something is inconvenient or a date is near: within a day."
93
+ - const: 2
94
+ description: "Service is down, money is stuck, or a deadline is today: now."
95
+ needs_human:
96
+ type: boolean
97
+ description: "A person must read this message before any automated reply is sent."
98
+ oneOf:
99
+ - const: true
100
+ description: "Legal action, a safety or security concern, a complaint about staff, a deletion request, or an unclear department."
101
+ - const: false
102
+ description: "A routine message a department can answer on its own."
103
+ required: [department, urgency, needs_human]
104
+ mime: "application/json"
@@ -14,6 +14,11 @@
14
14
  # kimi-* → Moonshot (MOONSHOT_API_KEY)
15
15
  # deepseek-* → DeepSeek (DEEPSEEK_API_KEY)
16
16
  #
17
+ # (jev-* → TypeSafe Jev is the eighth provider, and not in this zoo: a
18
+ # decision model answers a schema, never a question in prose. Its proof
19
+ # is classifier.yaml.) With no direct key, one MODEL_GATEWAY key serves
20
+ # every cloud agent here.
21
+ #
17
22
  # Run the proof: npm run demo:models (scripts/demo_model_optionality.ts
18
23
  # sends "explain quantum mechanics" to every agent whose provider is
19
24
  # available, and prints input, thinking, output, and a token/latency trace.
@@ -22,7 +22,7 @@
22
22
  "model": {
23
23
  "type": "string",
24
24
  "minLength": 1,
25
- "description": "Model id; its prefix picks the provider (gemini-*, claude-*, gpt-*/o*, grok-*, ollama/*)."
25
+ "description": "Model id; its prefix picks the provider (gemini-*, claude-*, gpt-*/o*, grok-*, kimi-*, deepseek-*, jev-*, ollama/*)."
26
26
  },
27
27
  "fallback_model": {
28
28
  "description": "A model on another provider that answers when this agent's model fails provider-side (5xx, 429, network) before producing anything, or while that provider's circuit is open (ADR 0044).",
@@ -448,6 +448,35 @@
448
448
  }
449
449
  ]
450
450
  },
451
+ "typesafe": {
452
+ "type": "object",
453
+ "properties": {
454
+ "instruction": {
455
+ "description": "Replaces the agent's instruction on this provider.",
456
+ "type": "string",
457
+ "minLength": 1
458
+ },
459
+ "instruction_append": {
460
+ "description": "Appended to the agent's instruction, after a blank line, on this provider.",
461
+ "type": "string",
462
+ "minLength": 1
463
+ }
464
+ },
465
+ "additionalProperties": false,
466
+ "description": "The instruction on one provider: exactly one of instruction or instruction_append.",
467
+ "oneOf": [
468
+ {
469
+ "required": [
470
+ "instruction"
471
+ ]
472
+ },
473
+ {
474
+ "required": [
475
+ "instruction_append"
476
+ ]
477
+ }
478
+ ]
479
+ },
451
480
  "ollama": {
452
481
  "type": "object",
453
482
  "properties": {
@@ -1535,6 +1564,35 @@
1535
1564
  }
1536
1565
  ]
1537
1566
  },
1567
+ "typesafe": {
1568
+ "type": "object",
1569
+ "properties": {
1570
+ "instruction": {
1571
+ "description": "Replaces the agent's instruction on this provider.",
1572
+ "type": "string",
1573
+ "minLength": 1
1574
+ },
1575
+ "instruction_append": {
1576
+ "description": "Appended to the agent's instruction, after a blank line, on this provider.",
1577
+ "type": "string",
1578
+ "minLength": 1
1579
+ }
1580
+ },
1581
+ "additionalProperties": false,
1582
+ "description": "The instruction on one provider: exactly one of instruction or instruction_append.",
1583
+ "oneOf": [
1584
+ {
1585
+ "required": [
1586
+ "instruction"
1587
+ ]
1588
+ },
1589
+ {
1590
+ "required": [
1591
+ "instruction_append"
1592
+ ]
1593
+ }
1594
+ ]
1595
+ },
1538
1596
  "ollama": {
1539
1597
  "type": "object",
1540
1598
  "properties": {
@@ -270,7 +270,14 @@ orchestrator:
270
270
  # grok-* → xAI (XAI_API_KEY)
271
271
  # kimi-* → Moonshot Kimi (MOONSHOT_API_KEY)
272
272
  # deepseek-* → DeepSeek (DEEPSEEK_API_KEY)
273
+ # jev-* → TypeSafe Jev (TYPESAFE_API_KEY; a decision model: it answers
274
+ # this agent's output.schema, never prose, so it
275
+ # takes no tools and no subagents)
273
276
  # ollama/* → local Ollama (keyless)
277
+ # With no direct key, MODEL_GATEWAY (vercel | openrouter) serves any cloud id;
278
+ # MODEL_GATEWAY_PREFER=gateway sends every cloud id through it even beside
279
+ # a direct key, and MODEL_GATEWAY_EXCEPT names the providers that do the
280
+ # opposite. Deployment config, never YAML: the file names models, not paths.
274
281
  # Subagents inherit this if not set on their own config.
275
282
  model: "gemini-3.5-flash-lite"
276
283
 
@@ -444,6 +451,7 @@ orchestrator:
444
451
  # that effort; none is the model's off switch,
445
452
  # or low effort on Opus 5 and 5.5, Fable and
446
453
  # Mythos (ADR 0049)
454
+ # jev-* → nothing: Jev decides without reasoning
447
455
  # gpt-*/o*, grok-*, kimi-*, deepseek-*, ollama/*, a gateway
448
456
  # → reasoningEffort (an effort word; where the
449
457
  # provider lacks one, its nearest setting above;
@@ -508,7 +516,7 @@ orchestrator:
508
516
  # ── model_overrides ───────────────────────────────────────
509
517
  # [optional] A prompt nuance for one provider (ADR 0115). Keys are the
510
518
  # providers a model id routes to: gemini, anthropic, openai, xai,
511
- # moonshot, deepseek, ollama. Each holds ONE of:
519
+ # moonshot, deepseek, typesafe, ollama. Each holds ONE of:
512
520
  # instruction: replaces the instruction on that provider
513
521
  # instruction_append: added after the instruction, after a blank line
514
522
  # Applied for the provider of this agent's model, before the skills
@@ -1,6 +1,6 @@
1
1
  # Production templates
2
2
 
3
- Ten syndicate files built to be copied into production, one per job. The
3
+ Eleven syndicate files built to be copied into production, one per job. The
4
4
  starter pack in `../examples/` teaches the framework, and the Lyceum
5
5
  course walks through it file by file. These templates are the files you
6
6
  adapt and ship. Each header says what the file is for, how it is shaped,
@@ -14,6 +14,7 @@ first.
14
14
  | `research_brief.yaml` | Orchestration | A decision-ready brief with every claim traceable | three layers: Editor → nested ResearchDesk → Scout, Reader; Writer; tool-less Verifier | short-term | the open web |
15
15
  | `review_panel.yaml` | Orchestration | Ship, fix or hold a proposed change, from a coding harness | panel: Correctness, Risk, Operability → Chair | short-term | only the material it is given |
16
16
  | `draft_review.yaml` | Orchestration | Outbound writing checked against your policy | bounded loop: Drafter ↔ Reviewer | short-term | only the brief |
17
+ | `prompt_writer.yaml` | Orchestration | Production prompts for an agent or a syndicate, from a description or a broken prompt, written to the Lyceum prompt standard | bounded loop: Editor → Architect → Writer ↔ Auditor, a shared checklist and YAML skeleton | session | nothing; writes prompts, never runs them |
17
18
  | `intake_extractor.yaml` | Memory: short-term | Inbound document → structured JSON record, nothing kept | one agent with an `output.schema` | short-term, `includeContents: none` | only the document |
18
19
  | `case_desk.yaml` | Memory: session | Work one operational case across many turns | Lead + Runbooks + Reader, a CASE STATE block every turn | session | your runbooks, pasted links |
19
20
  | `account_memory.yaml` | Memory: long-term | Remember every client's asks, decisions and commitments | Lead + Writer, `preload_memory` / `load_memory` | long-term, domain `memory_extraction_rules` | its own memory silo |