nodal-agents 0.4.0 → 0.4.2

package/README.md

@@ -7,9 +7,20 @@
 [![Node](https://img.shields.io/badge/node-22%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/typescript-strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 
-Build and orchestrate AI agents on your own hardware. Multi-LLM,
-multi-channel, multi-connector — **no SaaS lock-in, no per-token markup,
-no cloud roundtrip.** Runs on any machine with Node 22+ — Mac, PC, Linux.
+Build and orchestrate a **team of AI agents** on your own hardware —
+each with its own personality, tools, memory, and model. Talk to them in
+the dashboard or on Telegram; they research, write files, call your
+connectors, and delegate to each other to get the job done.
+
+**No SaaS lock-in. No per-token markup. No cloud roundtrip.** Two commands
+to install, runs on any machine with Node 22+ (Mac, PC, Linux), and works
+with **any LLM** — frontier or local, paid or free.
+
+> **Run the models others choke on.** DeepSeek V4 works out of the box —
+> including the cheap, fast OpenRouter routes — because the runtime quietly
+> handles its quirks (non-standard tool-call payloads) instead of failing.
+> Mix the right model per agent: a frontier model where judgment matters, a
+> near-free one where it doesn't.
 
 ---
 
@@ -18,9 +29,11 @@ no cloud roundtrip.** Runs on any machine with Node 22+ — Mac, PC, Linux.
 | | |
 | --- | --- |
 | 🏠  **Local-first** | Single binary, embedded Postgres, zero cloud dependency. Your conversations, memory, and credentials stay on your machine. |
-| 🔌  **LLM-agnostic** | Anthropic, OpenAI, Google, Groq, Mistral, OpenRouter, or any OpenAI-compatible local model (LM Studio, Ollama). Per-agent key, swap providers without code changes. |
+| 🔌  **Any model, per agent** | Anthropic, OpenAI, Google, Groq, Mistral, OpenRouter, or any local model (LM Studio, Ollama). Setup is just an API key per provider — **each agent picks its own model**, so you can run Claude for the orchestrator and **DeepSeek V4** for the workers. The quirks of OSS frontier models (DeepSeek's non-spec tool args, Kimi/Qwen/GLM XML tool formats) are handled automatically. |
+| 🛟  **Provider failover** | Give an agent a backup key chain — if its provider 5xx's, times out, or hits quota mid-job, the runner fails over to the next one and keeps going (and fails loud only when the whole chain is down). |
 | 🧠  **Memory that compounds** | Persistent facts (entity-scoped, auto-injected into every job) and chat-thread continuity (your agent remembers what it said 30 seconds ago — and what it said yesterday). |
-| 🤝  **Orchestrators that finish** | Router and planner orchestrators delegate to specialist sub-agents. Hard guards against runaway loops — turn caps, chain caps, per-slug delegation budgets, smart retry on side-effect-free failures. |
+| 🤝  **Orchestrators that finish** | Router and planner orchestrators delegate to specialist sub-agents, then resume on completion to wrap up the answer. |
+| 🛡️  **Agents that don't lie, loop, or die** | Generic runtime guards: a per-job token budget and a no-progress detector kill runaway loops; a no-false-success guard refuses to report "done" when an action actually failed (fail loud, never fake it); turn/chain/delegation caps bound everything. |
 | 🔧  **Multi-instance connectors** | Gmail perso *and* Gmail boulot on the same install. OAuth *and* API-key supported. Active list + Marketplace UI in the dashboard. |
 | 🗂️  **Workspaces** | Multiple isolated workspaces on one install (personal vs work) — each with its own agents, skills, connectors, jobs and memory. Switch from the sidebar. |
 | 🤖  **Self-extending (ROOT agent)** | Designate an orchestrator as ROOT and let it create skills/agents and assign them on your behalf — gated by per-grant toggles and an autonomy level (propose-confirm → fully-autonomous). |
@@ -48,8 +61,8 @@ nodal-agents up
 
 Open <http://localhost:3000>. The CLI spawns an embedded Postgres on a
 free port, applies migrations, seeds the system skills, and starts the
-runner (`:3001`) and dashboard (`:3000`). Configure your LLM provider
-from **Settings → LLM Keys** in the dashboard.
+runner (`:3001`) and dashboard (`:3000`). Connect an LLM provider from
+**LLM Providers** in the dashboard — paste an API key and you're running.
 
 > Requires Node 22+. No external Postgres, no Redis, no cloud config.
 > Data lives at `~/.nodalai/` — wipe with `rm -rf ~/.nodalai`.
@@ -77,7 +90,7 @@ When a newer version is available, `nodal-agents up` also prints a one-line
 notice:
 
 ```
-ℹ v0.4.0 available — run `nodal-agents update`
+ℹ v0.4.2 available — run `nodal-agents update`
 ```
 
 ### Build from source
@@ -131,7 +144,8 @@ Delegations create child jobs that resume the parent on completion.
 
 | Route | Purpose |
 | --- | --- |
-| `/agents` | Create, edit, assign skills + connectors + MCP servers to agents. |
+| `/agents` | Create, edit, assign skills + connectors + MCP servers to agents — and pick each agent's provider + model (with an optional failover chain). |
+| `/llm-providers` | Connect each LLM provider with a single API key — enable/disable inline. Models are chosen per-agent, not here. |
 | `/jobs` | Live job stream — task, agent, status, full transcript, tool I/O. |
 | `/connectors` | Active connector instances + Marketplace (multi-instance, OAuth or API-key). |
 | `/mcp` | Active MCP servers + Marketplace — HTTP & stdio, a growing catalogue, plus add/edit your own custom servers. |
@@ -140,7 +154,7 @@ Delegations create child jobs that resume the parent on completion.
 | `/logs` | Tool-call audit — input/output JSON per call, filterable by tool name. |
 | `/approvals` | Human-in-the-loop gates for risky tools (and the ROOT agent's meta-tools under propose-confirm). |
 | `/automations` | Cron-scheduled agent triggers. |
-| `/settings` | LLM keys, auth mode, network (loopback / LAN), bot tokens, workspace management, ROOT-agent designation + grants/autonomy. |
+| `/settings` | Auth mode, network (loopback / LAN), bot tokens, workspace management, ROOT-agent grants + autonomy. |
 
 ---
 
@@ -204,18 +218,28 @@ pnpm deps:check   # runs locally and in CI before every release
 
 ## Status
 
-**Current release:** `0.3.10` on npm `latest`. Used daily by the
+**Current release:** `0.4.2` on npm `latest`. Used daily by the
 maintainer, stable enough for personal production. Pre-1.0 — breaking
 changes are still possible between minors.
 
 ### Shipped and working
 
-- Multi-LLM provider routing with per-agent keys
+- Multi-LLM, **per-agent model selection** — provider setup is just an API key
+  (one per provider); each agent chooses its own model on top. Frontier and
+  local providers, including **DeepSeek V4** (non-spec tool-call args normalized
+  automatically), plus native tool-call parsing for Kimi K2 / Qwen3-Coder / GLM
+- **Provider failover** — an opt-in ordered key chain per agent; on a 5xx /
+  timeout / quota mid-job the runner fails over to the next key, and fails loud
+  (`all_providers_failed`) only when the whole chain is exhausted
+- **Reliability guards (generic, model-agnostic)** — per-job token budget +
+  no-progress detector (kill runaway loops), and a no-false-success guard that
+  refuses to complete a job as "success" when a tool action failed and was never
+  resolved (fail loud, never fake it)
 - Persistent memory (sanitation, dedup, importance ranking, auto-injection,
   feedback loop)
 - Session-thread continuity on chat channels (Telegram today)
-- Orchestrator (router + planner) with delegation chains and anti-runaway
-  caps
+- Orchestrator (router + planner) with delegation chains that resume the
+  parent on completion
 - Multi-instance connectors with OAuth (Gmail, Drive, Sheets, Docs, Notion,
   Airtable) and API-key (Notion, Airtable, Apify, Firecrawl, Tavily)
 - MCP catalog — Streamable HTTP *and* stdio (local subprocess) servers, API-key auth; a growing catalogue (Stripe, n8n, Supabase, Airtable, Notion…) with a "test pending" badge on entries not yet verified live, plus add *and edit* your own custom HTTP/stdio servers from the dashboard

package/cli.js

@@ -12185,6 +12185,13 @@ var init_connector_catalog = __esm({
   }
 });
 
+// ../../packages/shared/src/model-catalog.ts
+var init_model_catalog = __esm({
+  "../../packages/shared/src/model-catalog.ts"() {
+    "use strict";
+  }
+});
+
 // ../../packages/shared/src/index.ts
 var init_src2 = __esm({
   "../../packages/shared/src/index.ts"() {
@@ -12210,6 +12217,7 @@ var init_src2 = __esm({
     init_providers();
     init_root_agent();
     init_connector_catalog();
+    init_model_catalog();
   }
 });
 
@@ -12364,7 +12372,6 @@ var init_llm_keys = __esm({
         apiKeyLast4: text("api_key_last4").notNull().default(""),
         baseUrl: text("base_url"),
         nickname: text("nickname"),
-        defaultModel: text("default_model"),
         isActive: boolean("is_active").notNull().default(true),
         createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
         updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
@@ -12393,6 +12400,14 @@ var init_agents = __esm({
         personality: text("personality").notNull(),
         model: text("model").default("claude-sonnet-4-6-20260217"),
         llmKeyId: uuid("llm_key_id").references(() => entityLlmKeys.id, { onDelete: "set null" }),
+        // Ordered LLM-key fallback chain (Guard 2). When the primary key
+        // (llmKeyId) exhausts retries / times out / hits quota mid-job, the runner
+        // fails over to these in order; all-down fails loud (`all_providers_failed`).
+        // Empty = no failover (default). Each link is a (keyId, model) pair so a
+        // fallback runs on a CHOSEN model (empty model ⇒ that provider's catalog
+        // default). FK integrity is enforced in the app layer; a deleted key is
+        // skipped at resolution time.
+        fallbackChain: jsonb("fallback_chain").$type().default(sql`'[]'::jsonb`),
         active: boolean("active").default(true),
         isDefault: boolean("is_default").default(false),
         role: text("role").default("agent"),

package/migrations/0030_agent_fallback_llm_keys.sql

@@ -0,0 +1,6 @@
+-- Guard 2 (provider failover): ordered LLM-key fallback chain per agent.
+-- When the agent's primary key (llm_key_id) exhausts retries / times out /
+-- hits quota mid-job, the runner fails over to these keys in order; all-down
+-- fails loud (`all_providers_failed`). Empty default = no failover.
+ALTER TABLE "agents"
+  ADD COLUMN IF NOT EXISTS "fallback_llm_key_ids" uuid[] DEFAULT '{}'::uuid[];

package/migrations/0031_llm_key_capabilities.sql

@@ -0,0 +1,7 @@
+-- T2 (per-model LLM capabilities): cache a key's tool-calling capability so the
+-- runtime can pick the right tool_choice WITHOUT a failed first call. NULL =
+-- unknown (runtime assumes supported; the tool_choice floor catches a wrong
+-- guess). Set from the model catalog or the live "Test" capability probe.
+ALTER TABLE "entity_llm_keys"
+  ADD COLUMN IF NOT EXISTS "supports_tools" boolean,
+  ADD COLUMN IF NOT EXISTS "supports_forced_tool_choice" boolean;

package/migrations/0032_drop_llm_key_model_caps.sql

@@ -0,0 +1,9 @@
+-- Simplify LLM providers: a key is now JUST credentials (provider + API key +
+-- base URL + active). The model is chosen per-AGENT, and tool capability is
+-- read from the code model catalog at runtime — so these per-key columns are
+-- dead weight. Drop them. (0030 fallback_llm_key_ids stays — failover is still a
+-- per-key concern.)
+ALTER TABLE "entity_llm_keys"
+  DROP COLUMN IF EXISTS "default_model",
+  DROP COLUMN IF EXISTS "supports_tools",
+  DROP COLUMN IF EXISTS "supports_forced_tool_choice";

package/migrations/0033_agent_fallback_chain.sql

@@ -0,0 +1,21 @@
+-- Per-fallback model selection (Guard 2). The failover chain now stores
+-- (keyId, model) pairs instead of bare key ids, so each fallback runs on a
+-- CHOSEN model rather than its provider's catalog default. Backfill existing
+-- id arrays with an empty model ('' ⇒ runtime uses the catalog default), then
+-- drop the old column.
+ALTER TABLE "agents"
+  ADD COLUMN IF NOT EXISTS "fallback_chain" jsonb DEFAULT '[]'::jsonb;
+
+UPDATE "agents"
+SET "fallback_chain" = COALESCE(
+  (
+    SELECT jsonb_agg(jsonb_build_object('keyId', kid::text, 'model', ''))
+    FROM unnest("fallback_llm_key_ids") AS kid
+  ),
+  '[]'::jsonb
+)
+WHERE "fallback_llm_key_ids" IS NOT NULL
+  AND array_length("fallback_llm_key_ids", 1) > 0;
+
+ALTER TABLE "agents"
+  DROP COLUMN IF EXISTS "fallback_llm_key_ids";

package/migrations/meta/_journal.json

@@ -211,6 +211,34 @@
       "when": 1780900000000,
       "tag": "0029_backfill_root_agent",
       "breakpoints": true
+    },
+    {
+      "idx": 30,
+      "version": "7",
+      "when": 1781000000000,
+      "tag": "0030_agent_fallback_llm_keys",
+      "breakpoints": true
+    },
+    {
+      "idx": 31,
+      "version": "7",
+      "when": 1781100000000,
+      "tag": "0031_llm_key_capabilities",
+      "breakpoints": true
+    },
+    {
+      "idx": 32,
+      "version": "7",
+      "when": 1781200000000,
+      "tag": "0032_drop_llm_key_model_caps",
+      "breakpoints": true
+    },
+    {
+      "idx": 33,
+      "version": "7",
+      "when": 1781300000000,
+      "tag": "0033_agent_fallback_chain",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodal-agents",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Local-first AI agent platform with a web dashboard — install in one command.",
   "license": "MIT",
   "repository": {