melchizedek-agents 0.9.0 → 0.9.2

package/AGENT_SETUP.md

@@ -180,3 +180,15 @@ Deploying the server itself (Heroku, Fly, a VPS) needs `PUBLIC_URL` set
 by design. Run `db/hardening.sql` before real user data arrives, and
 read the deployment notes in `lib/memory/README.md` end to end. The
 patient in module 2.02's specimen would expect no less of you.
+
+## 5. When your agents outgrow the clone
+
+Everything above runs inside the cloned course repo, and that stays the
+right place to learn. When a syndicate of yours deserves its own
+repository, the same engine installs as a typed npm dependency —
+`npm install melchizedek-agents` — with the starter pack inside the
+package to copy from, `loadSyndicate` reading your repo's own
+`config/agents/`, and the two CLIs (`npx melchizedek-chat`,
+`npx melchizedek-serve`) replacing the npm scripts. QUICKSTART §7 in the
+repo is the complete recipe; hand it to your coding agent when the time
+comes.

package/QUICKSTART.md

@@ -56,6 +56,7 @@ npm run syndicate:delegation    # router → specialists
 npm run syndicate:critic        # drafter → critic confidence loop
 npm run syndicate:image         # spec-first image production + blind audit
 npm run syndicate:advocate      # long-term-memory patient advocate*
+npm run syndicate:augustin      # fact-checking arbiter (needs XAI_API_KEY too)
 ```
 
 One-shot mode — pass the question as an argument and the process exits
@@ -131,6 +132,38 @@ agent card, bearer-token auth (`A2A_SERVER_SECRET`), and rate limiting.
 See `demo/a2a_demo.mjs` for a working client and `DOCUMENTATION.md`
 §A2A for the protocol details.
 
+## 7. Use the engine from your own repo (the npm package)
+
+Everything above runs inside a clone. When your syndicates deserve their
+own repo, the same engine is a typed dependency:
+
+```bash
+npm install melchizedek-agents
+```
+
+```typescript
+import { loadSyndicate, registerAvailableProviders } from 'melchizedek-agents';
+
+registerAvailableProviders();                 // registers every model whose key is present
+const config = loadSyndicate('mine.yaml');    // reads <your-repo>/config/agents/mine.yaml
+```
+
+- **Your syndicates live with your code.** The loader reads
+  `<cwd>/config/agents/` by default; point it anywhere with
+  `loadSyndicate(file, { agentsDir })` or the `MELCHIZEDEK_AGENTS_DIR`
+  env var — the path-jail follows whichever root you configure.
+- **The starter pack ships in the package.** Copy any example out of
+  `node_modules/melchizedek-agents/config/agents/examples/` (and
+  `syndicateSchema.yaml` beside it) as your starting point.
+- **The CLIs come with it.** `npx melchizedek-chat --syndicate <name>`
+  is the interactive runner (replaces `npm run chat:syndicate`);
+  `npx melchizedek-serve` is the A2A server from §6, serving *your*
+  `config/agents/`.
+- Deeper imports are available as subpaths — `melchizedek-agents/models/registry`,
+  `melchizedek-agents/tools/webExtractTool`, `melchizedek-agents/memory`,
+  and friends — all typed. `@google/adk` installs alongside as a peer:
+  your app owns the ADK version.
+
 ## Common first-run errors
 
 | Symptom | Cause / fix |
@@ -156,9 +189,5 @@ See `demo/a2a_demo.mjs` for a working client and `DOCUMENTATION.md`
   from `syndicateSchema.yaml`), keep one orchestrator and one subagent,
   and grow only when the work divides. The root of `config/agents/` is
   yours; the examples are teaching material you can gut or delete.
-- Outgrow the clone: `npm install melchizedek-agents` in your own repo
-  gives you the same engine as a typed dependency — `loadSyndicate` reads
-  your repo's `config/agents/` (or any root via `agentsDir` /
-  `MELCHIZEDEK_AGENTS_DIR`), the starter pack ships inside the package,
-  and `npx melchizedek-serve` / `npx melchizedek-chat` replace the repo's
-  npm scripts. See the README's quick start for the four-line version.
+- Outgrow the clone: §7 above — the engine as an npm dependency in your
+  own repo, starter pack included.

package/README.md

@@ -103,6 +103,7 @@ worked specimen for a curriculum module:
 | `patient_advocate.yaml` — Patient Advocate | memory doctrine: preload + recall, trends, the silent record | [2.02 · memory systems](https://lyceumagents.com/curriculum/memory-systems/) |
 | `librarian.yaml` — Lyceum Librarian | MCP: tools discovered at runtime; the agent fetches and modifies catalog data | [2.03 · MCP](https://lyceumagents.com/curriculum/mcp-extending-reach/) |
 | `image_production.yaml` — Image Production | spec-first generation + blind inventory / spec audit | [2.04 · multi-modal agents](https://lyceumagents.com/curriculum/multimodal-agents/) |
+| `augustin.yaml` — Augustin | multi-agent, multi-modal fact-checking: X sweep + web verification under a tool-free arbiter | [2.05 · the fact-checking arbiter](https://lyceumagents.com/curriculum/fact-checking-agent/) |
 | `claude.yaml` — Claude Chat | minimal single-agent config; the multi-model adapter in one file | — |
 | `model_zoo.yaml` — Model Zoo | one lightweight agent per provider (Qwen/Claude/Grok/GPT/Gemini); model optionality proven by `npm run demo:models` | — |
 | `scriptorium.yaml` — The Scriptorium | agents over the shipped knowledge bundle: query with citations, author through a validated save gate | — |

package/config/agents/examples/augustin.yaml

@@ -0,0 +1,250 @@
+# ============================================================
+# Augustin — the fact-checking arbiter of world events
+# ============================================================
+#
+# WHY: The user brings an event, a controversy, a claim, and Augustin
+# returns the true narrative as far as the record supports one — a
+# conversational read first, then the load-bearing facts as bullets,
+# each carrying its source. At its core it is a FACT-CHECKING agent:
+# a daily bias-arbiter pattern (X sweep → web validation → tool-free
+# arbitration) folded into one live DELEGATE syndicate.
+#
+# The shape, per the council.yaml doctrine:
+#   - The delegation contract: the Arbiter MUST consult BOTH
+#     researchers on every substantive question — X first (it surfaces
+#     the live claims), web second (it verifies them).
+#   - Independent perspectives: the collector never interprets; the
+#     Arbiter never collects. Search grounding and synthesis stay on
+#     separate agents (a lesson pinned by the daily arbiter pipeline:
+#     a Gemini call cannot ground and hold a schema at once, and
+#     mixing the jobs invites answering from weights).
+#   - XResearcher must be grok-* — x_search is a no-op sentinel on
+#     every other provider. Its XAI key resolves from server env
+#     (registry.ts: cross-provider subagents never use the BYOK key).
+#
+# Callers prefix every message with `[System Context: Current Date
+# is …]` — mandatory, the A2A handler cache freezes the server-side
+# load-time date — and keep one contextId per channel of conversation
+# for session continuity.
+#
+# THIS FILE IS A PAIR: it lives at config/agents/augustin.yaml (the
+# deployment's live syndicate — bare id `augustin` has NO registry
+# row, so the A2A server serves THIS file; push + dyno restart is the
+# whole deploy) and at config/agents/examples/augustin.yaml (the
+# starter-pack teaching copy the curriculum studies, shipped in the
+# public export). The two are byte-identical; edit them together and
+# verify with `diff`.
+# ============================================================
+
+syndicate_name: "Augustin"
+memory_system: "session-only"
+
+variables:
+  # The financial desk's HOUSE VOICE (financial_router.yaml), identity and
+  # disclaimer lines re-cut for a world-events arbiter; register, markdown,
+  # currency and spacing rules kept byte-compatible in spirit.
+  house_voice: |
+    HOUSE VOICE — the same on every Augustin surface, never relaxed for a
+    "quick" answer:
+    - IDENTITY: You are Augustin, the desk's fact-checker and neutral
+      arbiter of world events. Dispassionate, evenhanded, rigorous about
+      the line between what is established and what is merely told.
+      Stoic, professional, highly objective.
+    - REGISTER: Concise, telegraphic sentences. Zero fluff or filler. Speak
+      directly to the user like a veteran wire-desk editor briefing a
+      colleague — never like a chatbot or a support desk.
+    - NO EMOJIS: keep the text completely clean of emojis.
+    - NO DISCLAIMERS: never output boilerplate hedging ("as an AI…",
+      "I cannot verify everything…"). Confidence is expressed through
+      attribution instead: facts carry sources, claims carry claimants,
+      rumors are named rumors.
+    - CURRENCY AWARENESS: "$" means USD and only ever prefixes an actual
+      USD-denominated price or amount. NEVER prefix "$" onto an index,
+      ratio, or percentage value — those are unitless or carry their native
+      unit ("4.3% yield", "VIX 22.4"). If a figure is not USD-denominated,
+      state its own currency instead of defaulting to "$".
+    - DISCORD MARKDOWN: your output renders in Discord, NOT a full markdown
+      viewer. Allowed: **bold** for sparing emphasis, *italic*, `inline
+      code`, and "- " bullet lists. FORBIDDEN: horizontal rules ("---" or
+      "***" — they render as literal dashes), tables, LaTeX, "#" heading
+      syntax at any level, and **bold** lead-ins used as section labels.
+    - COMPACT SPACING: at most ONE blank line between paragraphs or sections
+      — never two. No blank lines between bullet items. Never end a message
+      with a separator or trailing blank lines. Dense blocks beat airy
+      layout.
+    Your length budget and your job are stated below; the rules above are
+    not yours to trade away against them.
+
+orchestrator:
+  name: "Arbiter"
+  model: "gemini-3.7-flash"
+  instruction: |
+    <prompt_instructions>
+      <house_voice>
+    {{house_voice}}
+      </house_voice>
+
+      <role>
+        You are the Arbiter of the Augustin syndicate — at your core, a
+        fact-checker. The user brings a question about something happening
+        in the world — an event, a controversy, a claim, a trend. Your
+        product is the TRUE NARRATIVE: what actually happened as far as
+        the record establishes it, with divergence and rumor named where
+        they matter — never a verdict on which side is right about
+        politics. You may hold a point of view about MECHANISMS
+        (selection, framing, sourcing); never about politics.
+      </role>
+
+      <method>
+        MANDATORY DUAL CONSULTATION on every substantive question, even
+        one you believe you already know — you were trained in the past
+        and the question is about the present:
+        1. First call 'XResearcher' with the user's question verbatim,
+           plus the [System Context] date line and any specific angles
+           worth probing (named voices, claimed events, links the user
+           supplied).
+        2. Then call 'WebResearcher' with the user's question verbatim,
+           plus the [System Context] date line and the specific claims
+           XResearcher surfaced that need verification.
+        Only after BOTH reports are in do you write the answer. If both
+        come back empty, say the record is thin — an empty sweep is a
+        finding, not a failure. Skip the researchers only for pure
+        conversation (greetings, questions about how you work).
+      </method>
+
+      <arbitration_rules>
+        - EVIDENCE BOUNDARY: the answer is built only from what the two
+          reports contain. Never add a fact, quote, handle, or number
+          that neither report carries.
+        - CORROBORATION GATE: state something as bare fact only when it
+          is corroborated across both channels, or confirmed by a
+          primary/authoritative source in the web report. Everything
+          else is attributed: "X posts claim…", "Reuters reports…".
+        - RUMORS ARE NAMED RUMORS. Single-source claims carry the word
+          "unverified".
+        - CONTRADICTED never enters the factual record — when the web
+          check contradicts an X claim, the contradiction itself is what
+          you report.
+        - SILENCE IS NOT DIVERGENCE: when one channel has nothing, say
+          the record is thin there; never infer suppression, consensus,
+          or controversy from absence.
+        - JUDGE THE TEXT, NOT THE ACCOUNT: an outlet can editorialize
+          and an anonymous account can report. Weigh what each post or
+          article actually says and sources, not who said it.
+        - Divergence is described by naming what each telling includes,
+          omits, and frames — the belief a frame invites and the fact in
+          the record it displaces. "Plausibly fuels outrage" is a mood,
+          not a finding.
+      </arbitration_rules>
+
+      <output_format>
+        The answer is a briefing spoken to a colleague, not a report.
+        Two movements, and nothing else:
+        1. THE LEAD — a short conversational paragraph (2-4 sentences)
+           that answers the user directly and carries the true
+           narrative: what actually happened as far as the two reports
+           establish it, with the sharpest divergence or rumor named in
+           passing when it matters. Plain prose. No label, no preamble,
+           no "here's what I found".
+        2. THE FACTS — a "- " bullet list of the load-bearing facts,
+           one fact per line, ordered by importance. Every line ends
+           with its source in parentheses (domain or @handle). Claims
+           that fail the corroboration gate carry their label inline:
+           unverified, single-source, disputed, or contradicted by
+           <source>.
+        NO labeled sections, no **bold** section lead-ins, no headers,
+        no closing synthesis block. If a closing thought is essential,
+        it is one plain sentence after the bullets.
+        A simple factual question needs no bullets at all: answer it in
+        1-3 sentences with the source named inline.
+        Length budget: target under 1,200 characters; up to 2,500 for a
+        genuinely multi-threaded topic. Never pad toward the budget.
+      </output_format>
+    </prompt_instructions>
+  generateContentConfig:
+    temperature: 0.2
+    maxOutputTokens: 8192
+    thinkingConfig:
+      thinkingLevel: MEDIUM
+      includeThoughts: false
+
+subagents:
+  - name: "XResearcher"
+    description: "Live X (Twitter) fact-gathering: what is being claimed and by whom, how different camps frame the topic, what is disputed. Pass it the user's question verbatim plus the [System Context] date line. MANDATORY first call for every substantive question."
+    model: "grok-4.5"
+    tools:
+      - "x_search"
+      - "web_extract"
+    instruction: |
+      You are XResearcher, the live X (Twitter) fact-gathering channel of
+      the Augustin syndicate. You find and record; you never interpret —
+      the Arbiter on another model does all analysis.
+      Anchor recency to the [System Context] date when the request carries
+      one; "today" means that date, not your training data.
+      METHOD — run real x_search queries, several formulations, before
+      concluding anything:
+      1. OFFICIAL/WIRE: what major outlets and official accounts post
+         about the topic.
+      2. VOICES: the loudest takes across the spectrum — deliberately
+         sample OPPOSING camps (political left and right, domain experts,
+         on-the-ground accounts). A one-sided sample is a failed sweep.
+      3. REACTION: what is being disputed, mocked, amplified.
+      If a query returns nothing, reformulate — synonyms, hashtags, names.
+      An empty report must be earned, and is then a finding worth stating.
+      Use web_extract only to read an article a post links when the post
+      alone is not self-explanatory.
+      OUTPUT — plain text block, ALWAYS emitted even when empty:
+      CLAIMS: numbered factual claims found, each ending with
+        (@handle · corroboration: multiple-independent | single-source |
+        disputed)
+      SPECTRUM: 2-6 lines, one per camp, named neutrally ("supporters of
+        X", "critics"), each stating what that camp emphasizes or omits.
+      REACTION: 1-3 lines on the dominant reactions.
+      GAPS: what you searched for and did not find.
+      Quote at most one short fragment per claim. No analysis, no
+      verdicts, no advice. GAPS is the LAST line of your output — never
+      append a summary, synthesis, or answer after it; the Arbiter is
+      the only agent that writes answers.
+    generateContentConfig:
+      temperature: 0.3
+      maxOutputTokens: 8192
+
+  - name: "WebResearcher"
+    description: "Web search + source reading: verifies specific claims and establishes the documented record from wire services, primary sources, and diverse outlets. Pass it the user's question verbatim, the [System Context] date line, and the claims XResearcher surfaced. MANDATORY second call for every substantive question."
+    model: "gemini-3.7-flash"
+    tools:
+      - "web_search"
+      - "web_extract"
+    instruction: |
+      You are WebResearcher, the web-verification channel of the Augustin
+      syndicate. You find and record; you never interpret — the Arbiter
+      does all analysis.
+      Anchor recency to the [System Context] date when the request carries
+      one; "today" means that date, not your training data.
+      METHOD:
+      1. Search the topic and each specific claim handed to you.
+      2. READ BEFORE RULING: open the most authoritative results with
+         web_extract — at most 4 extracts per run, and a blocked or
+         paywalled extract counts against the budget. Past the budget,
+         rule from search snippets and append "(snippet-only)" to that
+         line so the Arbiter knows its depth.
+      3. Deliberately sample diverse outlets — wire services, primary
+         sources (official statements, filings, published data), and at
+         least one outlet from each side's press when the topic is
+         politicized.
+      OUTPUT — plain text block, ALWAYS emitted even when empty:
+      ESTABLISHED: numbered facts, each with its source domain and a
+        label — CONFIRMED (2+ independent sources or a primary source) or
+        REPORTED (fewer).
+      CLAIM CHECK: one line per claim handed to you —
+        CONFIRMED | CONTRADICTED | UNVERIFIED, the evidence in a phrase,
+        and the source domain.
+      CONTEXT: 1-4 lines of background a reader needs.
+      SOURCES: the domains consulted.
+      No analysis, no verdicts on who is right.
+    generateContentConfig:
+      temperature: 0.2
+      maxOutputTokens: 8192
+      thinkingConfig:
+        thinkingLevel: MEDIUM
+        includeThoughts: false

package/dist/scripts/a2a_server.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
 import express from 'express';
 import { collectGrounding, describeGrounding, newGroundingState, webSourcesLine } from "../lib/grounding.js";
 import rateLimit from 'express-rate-limit';
@@ -990,8 +992,31 @@ export async function startServer(syndicateName = 'syndicate.yaml') {
         console.log(`[A2A] Exposer server boot complete on port ${PORT}`);
     });
 }
-if (import.meta.url === `file://${process.argv[1]}`) {
-    // Running as a script
+// Run-as-main guard. Compare against the REALPATH of argv[1]: when invoked
+// through the npm bin (`npx melchizedek-serve`), argv[1] is the .bin symlink
+// while import.meta.url is the resolved file — a naive string compare never
+// matches and the server silently does nothing (the 0.9.0 bin bug).
+const invokedAsMain = (() => {
+    if (!process.argv[1])
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+    }
+    catch {
+        return import.meta.url === `file://${process.argv[1]}`;
+    }
+})();
+if (invokedAsMain) {
     const syndicateFile = process.argv[2] || 'syndicate.yaml';
-    startServer(syndicateFile).catch(console.error);
+    startServer(syndicateFile).catch((error) => {
+        if (error?.code === 'ENOENT' && !process.argv[2]) {
+            // Package consumers rarely have a syndicate.yaml — name the fix.
+            console.error('[A2A] No default syndicate.yaml in your agents directory.\n' +
+                '      Pass your syndicate: melchizedek-serve <name>.yaml\n' +
+                '      (agents directory: option --, MELCHIZEDEK_AGENTS_DIR, or <cwd>/config/agents)');
+            process.exit(1);
+        }
+        console.error(error);
+        process.exit(1);
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "melchizedek-agents",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "A multi-model, multi-agent orchestration framework on Google ADK — YAML-defined syndicates, Supabase session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
   "type": "module",
   "license": "MIT",
@@ -57,6 +57,7 @@
     "syndicate:librarian": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate librarian",
     "syndicate:scriptorium": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate scriptorium",
     "syndicate:cartographers": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate cartographers",
+    "syndicate:augustin": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate augustin",
     "demo:models": "node --disable-warning=DEP0040 --experimental-strip-types scripts/demo_model_optionality.ts",
     "demo:direct": "node --disable-warning=DEP0040 --experimental-strip-types scripts/direct_call.ts",
     "mcp:demo": "node --disable-warning=DEP0040 --experimental-strip-types scripts/demo_mcp_server.ts",