nodal-agents 0.3.5 → 0.3.8

package/README.md

@@ -22,7 +22,10 @@ no cloud roundtrip.** Runs on any machine with Node 22+ — Mac, PC, Linux.
 | 🧠  **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. |
 | 🔧  **Multi-instance connectors** | Gmail perso *and* Gmail boulot on the same install. OAuth *and* API-key supported. Active list + Marketplace UI in the dashboard. |
-| 📡  **MCP support** | Connect Streamable HTTP MCP servers — per-job tool discovery, tool whitelisting, multi-instance. |
+| 🗂️  **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). |
+| 📄  **Office files** | Read + edit Excel in place, create Word & PowerPoint, inside the agent's workspace — gated behind the office-editing skill. |
+| 📡  **MCP support** | Connect MCP servers over Streamable HTTP *and* stdio (local subprocess) — a growing catalogue (Stripe, n8n, Supabase, Vercel, Airtable, Notion…) plus add *and edit* your own custom servers from the UI. Per-job tool discovery, tool whitelisting, multi-instance. |
 | 💬 &nbsp;**Telegram out of the box** | Long-polling, multi-agent routing (`/ask <slug>`), group-chat filters, conversation continuity, delegation gracefulness on Telegram. |
 | ⚙️ &nbsp;**Real engineering** | TypeScript strict, dependency-cruiser-enforced architecture, full unit + integration suite, Playwright e2e, idempotent migrations, encryption at rest for keys. |
 
@@ -131,13 +134,13 @@ Delegations create child jobs that resume the parent on completion.
 | `/agents` | Create, edit, assign skills + connectors + MCP servers to agents. |
 | `/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 transport). |
+| `/mcp` | Active MCP servers + Marketplace — HTTP & stdio, a growing catalogue, plus add/edit your own custom servers. |
 | `/memories` | Persistent facts per entity — search, edit, archive. |
-| `/skills` | Procedural memory blocks — shipped with the product, user-overridable. |
+| `/skills` | Assigned / Custom / Built-in Library tabs — reusable instructions appended to an agent's prompt; create your own or customise built-ins. |
 | `/logs` | Tool-call audit — input/output JSON per call, filterable by tool name. |
-| `/approvals` | Human-in-the-loop gates for risky tools. |
+| `/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. |
+| `/settings` | LLM keys, auth mode, network (loopback / LAN), bot tokens, workspace management, ROOT-agent designation + grants/autonomy. |
 
 ---
 
@@ -177,8 +180,8 @@ packages/
 ├── runner-adapters  Adapter registry, agent ↔ tool wiring
 ├── delivery         Telegram, email
 ├── auth             Pluggable auth provider
-├── catalog          Shipped system skills (telegram-responder, obsidian,
-│                    research-scope-discipline, claude-html-design)
+├── catalog          Shipped system skills (office-editing, telegram-responder,
+│                    obsidian, task-planning, markdown-output, language-mirror …)
 └── secrets          AES-256-GCM key vault
 ```
 
@@ -201,7 +204,7 @@ pnpm deps:check   # runs locally and in CI before every release
 
 ## Status
 
-**Current release:** `0.1.5` on npm `latest`. Used daily by the
+**Current release:** `0.3.8` on npm `latest`. Used daily by the
 maintainer, stable enough for personal production. Pre-1.0 — breaking
 changes are still possible between minors.
 
@@ -215,11 +218,18 @@ changes are still possible between minors.
   caps
 - Multi-instance connectors with OAuth (Gmail, Drive, Sheets, Docs, Notion,
   Airtable) and API-key (Notion, Airtable, Apify, Firecrawl, Tavily)
-- MCP Streamable HTTP catalog with API-key auth
+- MCP catalog — Streamable HTTP *and* stdio (local subprocess) servers, API-key auth; a growing catalogue (Stripe, n8n, Supabase, Vercel, 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
+- Top-level workspaces — multiple isolated entities (agents/skills/connectors/jobs/memory per workspace), switch in the sidebar
+- ROOT agent — designate an orchestrator that can create skills/agents and assign them, gated by per-grant toggles + an autonomy/approval level
+- Office file editing — Excel in-place edit, Word/PowerPoint create, in the agent workspace (office-editing skill)
+- Multiple filesystem folders per agent (sandboxed `file_*` tools)
 - Telegram delivery (long-poll, group filters, multi-agent routing,
-  delegation gracefulness)
-- Approval gates for risky tools
+  delegation gracefulness) — exactly-once delivery contract: anti-spam guard
+  against runaway message loops + a guard that re-prompts (then fails loud)
+  rather than completing a job without ever replying
+- Approval gates for risky tools (execute-the-approved-action on resume)
 - Cron scheduling
+- `nodal-agents update` — one-command upgrade + boot version notice
 - Encryption at rest for LLM keys + MCP keys
 - Embedded Postgres distribution via npm (no external DB to install)
 
@@ -227,9 +237,9 @@ changes are still possible between minors.
 
 - **MCP OAuth flow** → unlocks Linear, Notion remote, GitHub remote,
   Atlassian, Sentry, and the rest of the SaaS-as-MCP ecosystem.
-- **MCP stdio transport** → unlocks the Anthropic reference servers
-  (filesystem, sqlite, brave-search, GitHub stdio…) and the community
-  catalog.
+- **Dashboard chat for the ROOT companion** → talk to your ROOT agent in
+  the app, multi-turn, instead of via Telegram; plus a dry-run mode and a
+  test-workflow meta-tool.
 - **pgvector binaries bundled in the npm pack** → semantic memory search
   active out-of-the-box. Today, installs without pgvector fall back to
   keyword search (which works, just less smart for cross-vocabulary

package/cli.js

@@ -12158,6 +12158,22 @@ var init_providers = __esm({
   }
 });
 
+// ../../packages/shared/src/root-agent.ts
+import { z as z19 } from "zod";
+var AutonomyLevelSchema, RootGrantsSchema;
+var init_root_agent = __esm({
+  "../../packages/shared/src/root-agent.ts"() {
+    "use strict";
+    AutonomyLevelSchema = z19.enum(["propose_confirm", "destructive_gate", "fully_autonomous"]);
+    RootGrantsSchema = z19.object({
+      createAgent: z19.boolean(),
+      createSkill: z19.boolean(),
+      assignSkill: z19.boolean(),
+      autonomy: AutonomyLevelSchema
+    });
+  }
+});
+
 // ../../packages/shared/src/index.ts
 var init_src2 = __esm({
   "../../packages/shared/src/index.ts"() {
@@ -12181,6 +12197,7 @@ var init_src2 = __esm({
     init_agent_run();
     init_operation();
     init_providers();
+    init_root_agent();
   }
 });
 
@@ -12270,12 +12287,25 @@ var init_entities = __esm({
         industry: text("industry"),
         goal: text("goal"),
         mcpToken: uuid("mcp_token").defaultRandom(),
+        // ROOT agent designation (Wave 1 — V4 ROOT agent, 2026-05-29).
+        // Points at the agent that receives meta-tools. Set null when no root
+        // agent is designated. FK uses a lazy callback to avoid the circular
+        // import (agents.ts imports entities.ts for its own FK — a direct TS
+        // import here would create a module cycle; the lazy arrow breaks it at
+        // Drizzle schema resolution time while TS only sees the type via the
+        // forward-reference pattern).
+        rootAgentId: uuid("root_agent_id"),
+        // Per-grant toggles + autonomy level for the root agent. Stored as JSONB
+        // and parsed at runtime via parseRootGrants() from @nodal-agents/shared.
+        // Default is an empty object — the runtime falls back to DEFAULT_ROOT_GRANTS.
+        rootGrants: jsonb("root_grants").notNull().default(sql`'{}'::jsonb`),
         createdAt: timestamp("created_at", { withTimezone: true }).defaultNow(),
         updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow()
       },
       (table) => [
         uniqueIndex("entities_mcp_token_idx").on(table.mcpToken),
-        index("idx_entities_user_id").on(table.userId)
+        index("idx_entities_user_id").on(table.userId),
+        index("idx_entities_root_agent_id").on(table.rootAgentId)
       ]
     );
     entityMembers = pgTable(
@@ -12704,7 +12734,13 @@ var init_approvals = __esm({
         expiresAt: timestamp("expires_at", { withTimezone: true }).default(
           sql`now() + interval '1 hour'`
         ),
-        notes: text("notes")
+        notes: text("notes"),
+        /**
+         * Stamped by the runner's resume step once the approved/rejected tool has
+         * been executed (or its marker replaced). NULL = not yet executed.
+         * Guards against double-execution on duplicate resume triggers.
+         */
+        executedAt: timestamp("executed_at", { withTimezone: true })
       },
       (table) => [
         index("idx_approval_requests_entity_id").on(table.entityId),
@@ -13388,6 +13424,23 @@ var init_credentials2 = __esm({
   }
 });
 
+// ../../packages/db/src/repos/agents.ts
+var init_agents2 = __esm({
+  "../../packages/db/src/repos/agents.ts"() {
+    "use strict";
+    init_agents();
+  }
+});
+
+// ../../packages/db/src/repos/skills.ts
+var init_skills2 = __esm({
+  "../../packages/db/src/repos/skills.ts"() {
+    "use strict";
+    init_agents();
+    init_skills();
+  }
+});
+
 // ../../packages/db/src/index.ts
 var init_src4 = __esm({
   "../../packages/db/src/index.ts"() {
@@ -13396,6 +13449,8 @@ var init_src4 = __esm({
     init_transaction();
     init_schema2();
     init_credentials2();
+    init_agents2();
+    init_skills2();
     init_drizzle_orm();
   }
 });

package/migrations/0021_entities_root_agent_grants.sql

@@ -0,0 +1,22 @@
+-- 0021_entities_root_agent_grants.sql
+-- Wave 1 — V4 ROOT agent foundation (2026-05-29):
+--   1. ADD COLUMN entities.root_agent_id  (nullable FK → agents.id, set null on delete)
+--   2. ADD COLUMN entities.root_grants    (jsonb, not null, default '{}')
+--   3. CREATE INDEX idx_entities_root_agent_id
+--
+-- All steps are idempotent (IF NOT EXISTS / IF EXISTS guards).
+
+-- ─── 1. root_agent_id ────────────────────────────────────────────────────────
+
+ALTER TABLE entities
+  ADD COLUMN IF NOT EXISTS root_agent_id uuid
+    REFERENCES agents(id) ON DELETE SET NULL;
+
+-- ─── 2. root_grants ──────────────────────────────────────────────────────────
+
+ALTER TABLE entities
+  ADD COLUMN IF NOT EXISTS root_grants jsonb NOT NULL DEFAULT '{}'::jsonb;
+
+-- ─── 3. Index ────────────────────────────────────────────────────────────────
+
+CREATE INDEX IF NOT EXISTS idx_entities_root_agent_id ON entities(root_agent_id);

package/migrations/0022_approval_requests_executed_at.sql

@@ -0,0 +1,12 @@
+-- 0022_approval_requests_executed_at.sql
+-- Approval-gate execute-on-resume (2026-05-29):
+--   ADD COLUMN approval_requests.executed_at (nullable timestamptz)
+--
+-- When execute.ts resumes a job, it checks for approved/rejected requests
+-- where executed_at IS NULL, executes the tool, and stamps executed_at = now().
+-- This prevents double-execution on duplicate resume triggers.
+--
+-- Idempotent: ADD COLUMN IF NOT EXISTS.
+
+ALTER TABLE approval_requests
+  ADD COLUMN IF NOT EXISTS executed_at timestamptz;

package/migrations/meta/_journal.json

@@ -1,153 +1,167 @@
-{
-  "version": "7",
-  "dialect": "postgresql",
-  "entries": [
-    {
-      "idx": 0,
-      "version": "7",
-      "when": 1777221376983,
-      "tag": "0000_flashy_clea",
-      "breakpoints": true
-    },
-    {
-      "idx": 1,
-      "version": "7",
-      "when": 1777222639218,
-      "tag": "0001_exotic_shooting_star",
-      "breakpoints": true
-    },
-    {
-      "idx": 2,
-      "version": "7",
-      "when": 1777222668100,
-      "tag": "0002_gray_devos",
-      "breakpoints": true
-    },
-    {
-      "idx": 3,
-      "version": "7",
-      "when": 1778116559502,
-      "tag": "0003_stormy_thaddeus_ross",
-      "breakpoints": true
-    },
-    {
-      "idx": 4,
-      "version": "7",
-      "when": 1778141889404,
-      "tag": "0004_married_deadpool",
-      "breakpoints": true
-    },
-    {
-      "idx": 5,
-      "version": "7",
-      "when": 1778237574443,
-      "tag": "0005_tense_hedge_knight",
-      "breakpoints": true
-    },
-    {
-      "idx": 6,
-      "version": "7",
-      "when": 1778341607214,
-      "tag": "0006_credentials_table",
-      "breakpoints": true
-    },
-    {
-      "idx": 7,
-      "version": "7",
-      "when": 1778421836079,
-      "tag": "0007_free_speed",
-      "breakpoints": true
-    },
-    {
-      "idx": 8,
-      "version": "7",
-      "when": 1778459305708,
-      "tag": "0008_curious_thor_girl",
-      "breakpoints": true
-    },
-    {
-      "idx": 9,
-      "version": "7",
-      "when": 1778860776473,
-      "tag": "0009_agent_memory_token_budget",
-      "breakpoints": true
-    },
-    {
-      "idx": 10,
-      "version": "7",
-      "when": 1778940762250,
-      "tag": "0010_agent_workspace_root",
-      "breakpoints": true
-    },
-    {
-      "idx": 11,
-      "version": "7",
-      "when": 1779000000000,
-      "tag": "0011_agent_jobs_failed_delegations_count",
-      "breakpoints": true
-    },
-    {
-      "idx": 12,
-      "version": "7",
-      "when": 1779100000000,
-      "tag": "0012_agent_jobs_last_failed_delegation_slug",
-      "breakpoints": true
-    },
-    {
-      "idx": 13,
-      "version": "7",
-      "when": 1779200000000,
-      "tag": "0013_cascade_agent_fks",
-      "breakpoints": true
-    },
-    {
-      "idx": 14,
-      "version": "7",
-      "when": 1779400000000,
-      "tag": "0014_mcp_server_credentials",
-      "breakpoints": true
-    },
-    {
-      "idx": 15,
-      "version": "7",
-      "when": 1779500000000,
-      "tag": "0015_agent_mcp_servers_unique",
-      "breakpoints": true
-    },
-    {
-      "idx": 16,
-      "version": "7",
-      "when": 1779600000000,
-      "tag": "0016_drop_connector_entity_slug_unique",
-      "breakpoints": true
-    },
-    {
-      "idx": 17,
-      "version": "7",
-      "when": 1779700000000,
-      "tag": "0017_drop_mcp_server_entity_slug_unique",
-      "breakpoints": true
-    },
-    {
-      "idx": 18,
-      "version": "7",
-      "when": 1779800000000,
-      "tag": "0018_mcp_servers_bearer_auth",
-      "breakpoints": true
-    },
-    {
-      "idx": 19,
-      "version": "7",
-      "when": 1779900000000,
-      "tag": "0019_agents_position",
-      "breakpoints": true
-    },
-    {
-      "idx": 20,
-      "version": "7",
-      "when": 1780000000000,
-      "tag": "0020_agent_workspaces",
-      "breakpoints": true
-    }
-  ]
-}
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1777221376983,
+      "tag": "0000_flashy_clea",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1777222639218,
+      "tag": "0001_exotic_shooting_star",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1777222668100,
+      "tag": "0002_gray_devos",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1778116559502,
+      "tag": "0003_stormy_thaddeus_ross",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1778141889404,
+      "tag": "0004_married_deadpool",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1778237574443,
+      "tag": "0005_tense_hedge_knight",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1778341607214,
+      "tag": "0006_credentials_table",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1778421836079,
+      "tag": "0007_free_speed",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1778459305708,
+      "tag": "0008_curious_thor_girl",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1778860776473,
+      "tag": "0009_agent_memory_token_budget",
+      "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "when": 1778940762250,
+      "tag": "0010_agent_workspace_root",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1779000000000,
+      "tag": "0011_agent_jobs_failed_delegations_count",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1779100000000,
+      "tag": "0012_agent_jobs_last_failed_delegation_slug",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "7",
+      "when": 1779200000000,
+      "tag": "0013_cascade_agent_fks",
+      "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "7",
+      "when": 1779400000000,
+      "tag": "0014_mcp_server_credentials",
+      "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "7",
+      "when": 1779500000000,
+      "tag": "0015_agent_mcp_servers_unique",
+      "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1779600000000,
+      "tag": "0016_drop_connector_entity_slug_unique",
+      "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "7",
+      "when": 1779700000000,
+      "tag": "0017_drop_mcp_server_entity_slug_unique",
+      "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1779800000000,
+      "tag": "0018_mcp_servers_bearer_auth",
+      "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "7",
+      "when": 1779900000000,
+      "tag": "0019_agents_position",
+      "breakpoints": true
+    },
+    {
+      "idx": 20,
+      "version": "7",
+      "when": 1780000000000,
+      "tag": "0020_agent_workspaces",
+      "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "7",
+      "when": 1780100000000,
+      "tag": "0021_entities_root_agent_grants",
+      "breakpoints": true
+    },
+    {
+      "idx": 22,
+      "version": "7",
+      "when": 1780200000000,
+      "tag": "0022_approval_requests_executed_at",
+      "breakpoints": true
+    }
+  ]
+}

package/package.json

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