denchclaw 2.4.0 → 2.4.2

package/assets/seed/schema.sql

@@ -83,6 +83,7 @@ CREATE TABLE IF NOT EXISTS documents (
   file_path VARCHAR NOT NULL UNIQUE,
   parent_id VARCHAR REFERENCES documents(id),
   parent_object_id VARCHAR REFERENCES objects(id),
+  entry_id VARCHAR REFERENCES entries(id),
   sort_order INTEGER DEFAULT 0,
   is_published BOOLEAN DEFAULT false,
   created_at TIMESTAMPTZ DEFAULT now(),

package/extensions/dench-identity/index.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, vi } from "vitest";
+import { buildIdentityPrompt, resolveWorkspaceDir } from "./index.ts";
+import register from "./index.ts";
+import path from "node:path";
+
+describe("buildIdentityPrompt", () => {
+  const workspaceDir = "/home/user/workspace";
+
+  it("includes chat history path so agent can reference past conversations", () => {
+    const prompt = buildIdentityPrompt(workspaceDir);
+    expect(prompt).toContain(".openclaw/web-chat/");
+    expect(prompt).toContain(
+      path.join(workspaceDir, ".openclaw/web-chat/"),
+    );
+  });
+
+  it("includes all workspace context paths (prevents agent losing orientation)", () => {
+    const prompt = buildIdentityPrompt(workspaceDir);
+    expect(prompt).toContain(`**Root**: \`${workspaceDir}\``);
+    expect(prompt).toContain(path.join(workspaceDir, "workspace.duckdb"));
+    expect(prompt).toContain(path.join(workspaceDir, "skills"));
+    expect(prompt).toContain(path.join(workspaceDir, "apps"));
+  });
+
+  it("includes CRM skill path for delegation (prevents agent using wrong skill path)", () => {
+    const prompt = buildIdentityPrompt(workspaceDir);
+    expect(prompt).toContain(
+      path.join(workspaceDir, "skills", "crm", "SKILL.md"),
+    );
+  });
+
+  it("includes exec approval policy (prevents agent stalling on exec confirmation)", () => {
+    const prompt = buildIdentityPrompt(workspaceDir);
+    expect(prompt).toContain("elevated: true");
+    expect(prompt).toContain("automatically approved");
+  });
+
+  it("references DenchClaw branding, not OpenClaw (prevents identity confusion)", () => {
+    const prompt = buildIdentityPrompt(workspaceDir);
+    expect(prompt).toContain("You are **DenchClaw**");
+    expect(prompt).toContain("always use **DenchClaw** (not OpenClaw)");
+  });
+});
+
+describe("resolveWorkspaceDir", () => {
+  it("returns workspace path when config is a valid string", () => {
+    const api = { config: { agents: { defaults: { workspace: "/home/user/ws" } } } };
+    expect(resolveWorkspaceDir(api)).toBe("/home/user/ws");
+  });
+
+  it("returns undefined when api is null (prevents crash on missing config)", () => {
+    expect(resolveWorkspaceDir(null)).toBeUndefined();
+  });
+
+  it("returns undefined when api is undefined (prevents crash on missing config)", () => {
+    expect(resolveWorkspaceDir(undefined)).toBeUndefined();
+  });
+
+  it("returns undefined when config chain is missing (prevents crash on partial config)", () => {
+    expect(resolveWorkspaceDir({})).toBeUndefined();
+    expect(resolveWorkspaceDir({ config: {} })).toBeUndefined();
+    expect(resolveWorkspaceDir({ config: { agents: {} } })).toBeUndefined();
+    expect(resolveWorkspaceDir({ config: { agents: { defaults: {} } } })).toBeUndefined();
+  });
+
+  it("returns undefined when workspace is empty string (prevents empty path injection)", () => {
+    const api = { config: { agents: { defaults: { workspace: "" } } } };
+    expect(resolveWorkspaceDir(api)).toBeUndefined();
+  });
+
+  it("returns undefined when workspace is whitespace-only (prevents whitespace path injection)", () => {
+    const api = { config: { agents: { defaults: { workspace: "   " } } } };
+    expect(resolveWorkspaceDir(api)).toBeUndefined();
+  });
+
+  it("returns undefined when workspace is not a string (prevents type coercion)", () => {
+    expect(resolveWorkspaceDir({ config: { agents: { defaults: { workspace: 42 } } } })).toBeUndefined();
+    expect(resolveWorkspaceDir({ config: { agents: { defaults: { workspace: true } } } })).toBeUndefined();
+    expect(resolveWorkspaceDir({ config: { agents: { defaults: { workspace: null } } } })).toBeUndefined();
+  });
+
+  it("trims leading/trailing whitespace from valid paths", () => {
+    const api = { config: { agents: { defaults: { workspace: "  /home/user/ws  " } } } };
+    expect(resolveWorkspaceDir(api)).toBe("/home/user/ws");
+  });
+});
+
+describe("register", () => {
+  it("hooks into before_prompt_build event when enabled", () => {
+    const api = {
+      config: { plugins: { entries: {} }, agents: { defaults: { workspace: "/ws" } } },
+      on: vi.fn(),
+    };
+    register(api);
+    expect(api.on).toHaveBeenCalledWith(
+      "before_prompt_build",
+      expect.any(Function),
+      { priority: 100 },
+    );
+  });
+
+  it("does not register handler when plugin is explicitly disabled (respects config)", () => {
+    const api = {
+      config: { plugins: { entries: { "dench-identity": { config: { enabled: false } } } } },
+      on: vi.fn(),
+    };
+    register(api);
+    expect(api.on).not.toHaveBeenCalled();
+  });
+
+  it("handler returns system context when workspace is configured", () => {
+    const api = {
+      config: { plugins: { entries: {} }, agents: { defaults: { workspace: "/ws" } } },
+      on: vi.fn(),
+    };
+    register(api);
+
+    const handler = api.on.mock.calls[0][1];
+    const result = handler({}, {});
+    expect(result).toEqual({
+      prependSystemContext: expect.stringContaining("DenchClaw"),
+    });
+  });
+
+  it("handler returns undefined when workspace is not configured (prevents empty prompt)", () => {
+    const api = {
+      config: { plugins: { entries: {} }, agents: { defaults: {} } },
+      on: vi.fn(),
+    };
+    register(api);
+
+    const handler = api.on.mock.calls[0][1];
+    const result = handler({}, {});
+    expect(result).toBeUndefined();
+  });
+});

package/extensions/dench-identity/index.ts

@@ -2,7 +2,7 @@ import path from "node:path";
 
 export const id = "dench-identity";
 
-function buildIdentityPrompt(workspaceDir: string): string {
+export function buildIdentityPrompt(workspaceDir: string): string {
   const skillsDir = path.join(workspaceDir, "skills");
   const crmSkillPath = path.join(skillsDir, "crm", "SKILL.md");
   const browserSkillPath = path.join(skillsDir, "browser", "SKILL.md");
@@ -94,6 +94,7 @@ For multi-session projects, write a session handoff summary to \`${workspaceDir}
 - **Skills**: \`${skillsDir}\` — scan this directory for all available skills; new skills may be installed at any time
 - **Apps**: \`${appsDir}\` — \`.dench.app\` folders with \`.dench.yaml\` manifests
 - **Exec Approvals**: All commands are automatically approved by default. All exec calls must be elevated: true.
+- **Chat History**: All chat history is stored in \`${workspaceDir}/.openclaw/web-chat/\`. This is where you can find all your past conversations and the context for the current session.
 
 ## Links
 
@@ -102,7 +103,7 @@ For multi-session projects, write a session handoff summary to \`${workspaceDir}
 - Skills Store: https://skills.sh`;
 }
 
-function resolveWorkspaceDir(api: any): string | undefined {
+export function resolveWorkspaceDir(api: any): string | undefined {
   const ws = api?.config?.agents?.defaults?.workspace;
   return typeof ws === "string" ? ws.trim() || undefined : undefined;
 }

package/extensions/posthog-analytics/lib/build-env.js

@@ -1,3 +1,3 @@
 export const POSTHOG_KEY = "phc_Nt8s1Ny8062TY9aKT8LWiB4nBuoHNYQXRU9MypWfQCW";
-export const DENCHCLAW_VERSION = "2.4.0";
+export const DENCHCLAW_VERSION = "2.4.2";
 export const OPENCLAW_VERSION = "";

package/extensions/vitest.config.ts

@@ -0,0 +1,13 @@
+import baseConfig from "../vitest.config.ts";
+import { defineConfig } from "vitest/config";
+
+const base = baseConfig as unknown as Record<string, unknown>;
+const baseTest = (baseConfig as { test?: Record<string, unknown> }).test ?? {};
+
+export default defineConfig({
+  ...base,
+  test: {
+    ...baseTest,
+    include: ["extensions/**/*.test.ts"],
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "denchclaw",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "Fully Managed OpenClaw Framework for managing your CRM, Sales Automation and Outreach agents. The only local productivity tool you need.",
   "keywords": [],
   "homepage": "https://github.com/DenchHQ/DenchClaw#readme",
@@ -62,6 +62,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.0.1",
+    "axios": "^1.13.5",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "gradient-string": "^3.0.0",

package/skills/crm/SKILL.md

@@ -95,6 +95,51 @@ Never rename partially. If you can't complete all steps, don't start the rename
 - **DuckDB SQL errors**: See the "Common DuckDB Pitfalls" section in the **duckdb-operations** child skill. The most frequent causes: unquoted field names with spaces (use `"Full Name"` not `Full Name`), wrong transaction syntax (`BEGIN TRANSACTION` not `BEGIN`), unescaped single quotes, and PIVOT views without the `IN (...)` field list.
 - **"Script not found" on action buttons**: The `.actions/` directory and/or script files were not created. See the **actions** child skill post-creation checklist.
 
+## Relation Fields — Link Objects Automatically
+
+**Every time you create or modify objects, check whether relation fields should connect them. Do NOT wait for the user to ask — proactively link objects that are obviously related.**
+
+Relation fields (`type: "relation"`) let an entry in one object reference an entry in another. They render as a searchable dropdown in the UI and are the backbone of any useful CRM.
+
+### Mandatory auto-linking rules
+
+When you create an object, scan all existing objects (run `SELECT name FROM objects`) and add relation fields for every obvious link:
+
+| If you're creating... | And this object exists... | Auto-create this relation field |
+|---|---|---|
+| people / contact | company | "Company" on people → company (`many_to_one`) |
+| lead / prospect | company | "Company" on lead → company (`many_to_one`) |
+| deal / opportunity | people | "Primary Contact" on deal → people (`many_to_one`) |
+| deal / opportunity | company | "Company" on deal → company (`many_to_one`) |
+| task | people | "Assigned Contact" on task → people (`many_to_one`) |
+| task | project / deal | "Related To" on task → parent (`many_to_one`) |
+| case | people or company | "Client" on case → people/company (`many_to_one`) |
+| invoice / payment | company | "Company" on invoice → company (`many_to_one`) |
+| invoice / payment | deal | "Deal" on invoice → deal (`many_to_one`) |
+| property / listing | people | "Agent" on property → people (`many_to_one`) |
+| any child concept | its parent concept | relation to parent (`many_to_one`) |
+
+**Use this SQL pattern** (safe — does nothing if the target object doesn't exist):
+
+```sql
+INSERT INTO fields (object_id, name, type, related_object_id, relationship_type, sort_order)
+SELECT
+  (SELECT id FROM objects WHERE name = 'people'),
+  'Company',
+  'relation',
+  (SELECT id FROM objects WHERE name = 'company'),
+  'many_to_one',
+  3
+WHERE EXISTS (SELECT 1 FROM objects WHERE name = 'company')
+ON CONFLICT (object_id, name) DO NOTHING;
+```
+
+**General rule**: If you're creating object B and object A already exists, ask: "Would an entry in B logically belong to or reference an entry in A?" If yes, add a `many_to_one` relation. Use `many_to_many` only when an entry can link to multiple entries (e.g. project → team members).
+
+Relation fields **must be created via SQL** — the API does not support the `relation` type.
+
+---
+
 ## Critical Reminders
 
 - Handle the ENTIRE CRM operation from analysis to SQL execution to filesystem projection to summary
@@ -107,10 +152,11 @@ Never rename partially. If you can't complete all steps, don't start the rename
 - Extract ALL data from user messages — don't leave information unused
 - **REPORTS vs DOCUMENTS**: When the user asks for "reports", "analytics", "charts", "graphs", "metrics", "insights", or "breakdown" — use `.report.json` format (see **reports** child skill), NOT markdown. Only use markdown `.md` for SOPs, guides, notes, and prose documents.
 - **INLINE CHART ARTIFACTS**: When answering analytics questions in chat, ALWAYS emit a `report-json` fenced code block so the UI renders interactive charts inline.
-- **NOTES**: Always use type "richtext" for Notes fields
+- **NOTES FIELD vs ENTRY DOCUMENTS**: These are different. `Notes` is a DuckDB `richtext` field stored in `entry_fields`. Entry documents are markdown files linked through the `documents` table. When the user asks for long-form notes, draft emails, writeups, or entry pages, default to entry documents unless they explicitly say "update the Notes field/column".
+- **ENTRY DOCUMENTS**: New entry detail pages should use human-readable filenames (for example `yt-mikemurphy-001.md`, `jane-smith-001.md`, `acme-corp-001.md`) and MUST be registered in DuckDB `documents` with `file_path`, `parent_object_id`, and `entry_id`. Do NOT default to raw `{entry_id}.md` filenames for new docs. See **documents** child skill.
 - **USER FIELDS**: Resolve member name to ID from `workspace_context.yaml` BEFORE inserting
 - **ENUM FIELDS**: Use type "enum" with `enum_values` JSON array
-- **RELATION FIELDS (PROACTIVE)**: Use type "relation" with `related_object_id` and `relationship_type`. **ALWAYS create relation fields when objects are obviously linked** — don't wait for the user to ask. Examples: people→company, deal→contact, deal→company, task→project, case→client, invoice→company. If you're creating object B and object A exists, ask: "Would B entries reference A entries?" If yes, add a relation. Relation fields must be created via SQL (not the API). See **object-builder** child skill for the full relation pattern and common relation pairs.
+- **RELATION FIELDS (PROACTIVE — SEE SECTION ABOVE)**: ALWAYS create relation fields when objects are obviously linked — don't wait for the user to ask. See the **"Relation Fields — Link Objects Automatically"** section above for the full table of mandatory auto-linking rules and the SQL pattern.
 - **TAGS FIELDS**: Use type "tags" for free-form string arrays. Value stored as `'["tag1","tag2"]'`
 - **URL FIELDS**: Use type "url" for website addresses and links
 - **FILE FIELDS**: Use type "file" for file attachments (stores file path or URL)

package/skills/crm/documents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: documents
-description: Document management with markdown files, cross-nesting between documents and objects, and optional per-entry detail pages.
+description: Document management with markdown files, cross-nesting between documents and objects, and human-readable entry detail pages linked through the documents table.
 metadata: { "openclaw": { "inject": true, "always": true, "emoji": "📄" } }
 ---
 
@@ -31,34 +31,225 @@ VALUES ('Roadmap', 'map', 'projects/roadmap.md', '<parent_doc_id>', 0);
 
 ---
 
-## Entry Detail Pages (Optional Markdown Files)
+## Notes Field vs Entry Documents
 
-Each entry in an object can have an optional markdown file that acts as a detail page (like a Notion row page). The file is stored inside the object's directory at `{{WORKSPACE_PATH}}/{object_name}/{entry_id}.md`.
+These are **not the same thing**:
 
-**Key rules:**
+- **`Notes` field**: a `richtext` value stored in DuckDB `entry_fields`
+- **Entry document**: a standalone `.md` file on disk, linked to the entry through the `documents` table
 
-- Entry `.md` files are **optional** — they are only created when the user writes content via the entry detail panel in the UI.
-- You do NOT need to create `.md` files for every entry during seeding. Only create them when you want to add detailed notes, descriptions, or documentation for a specific entry.
-- The UI automatically shows an empty markdown editor for entries without a `.md` file, and creates the file on first write.
-- Entry `.md` files are plain markdown (no frontmatter required). The filename must be exactly `{entry_id}.md`.
+When the user says:
 
-**When to create entry `.md` files during seeding:**
+- "fill in notes for each entry"
+- "write descriptions for all rows"
+- "add detailed writeups"
+- "put the outreach draft into each influencer notes page"
+- "create entry docs"
 
-- For entries that have rich descriptions or meeting notes
-- For entries that need SOPs, playbooks, or documentation attached
-- For key entries like important leads, major projects, or critical tasks
+default to **entry documents** unless they explicitly say "update the Notes column/field".
 
-**Example:**
+If the user truly means the `Notes` field, they will usually talk about:
+
+- a table column
+- richtext field values
+- filtering/sorting by Notes
+- SQL updates to `entry_fields`
+
+If they mean entry documents, they are talking about:
+
+- markdown pages
+- the entry detail panel
+- prose content, drafts, meeting notes, SOPs, long-form notes
+- files visible under the object in the sidebar
+
+---
+
+## Entry Detail Pages
+
+Each entry in an object can have an optional markdown file that acts as its detail page in the entry panel.
+
+**CRITICAL:** New entry documents should use **human-readable filenames**, not raw UUID filenames. The file must also be registered in DuckDB `documents` with `entry_id`, `parent_object_id`, and `file_path`.
+
+### Required storage model
+
+For every entry document:
+
+1. Write a human-readable markdown file inside the object directory
+2. Insert/update a row in `documents` linking the entry to that file
+
+```sql
+INSERT INTO documents (title, file_path, parent_object_id, entry_id)
+VALUES (
+  'Mike Murphy',
+  'marketing/influencer/yt-mikemurphy-001.md',
+  (SELECT id FROM objects WHERE name = 'influencer'),
+  'yt-mikemurphy-001'
+);
+```
+
+### Naming convention (MANDATORY)
+
+Use this filename structure for entry documents:
+
+`{human_readable_slug}-{sequence}.md`
+
+Examples:
+
+- `acme-corp-001.md`
+- `jane-smith-001.md`
+- `q2-renewal-deal-001.md`
+
+If the entry clearly belongs to a source/domain where a prefix helps, include it:
+
+- `yt-mikemurphy-001.md` for YouTube creators
+- `x-somehandle-001.md` for X/Twitter creators
+
+### How to choose the slug
+
+Use the first strong human-readable identifier available:
+
+1. `Document Slug`, `Slug`, or `File Slug` field if it exists
+2. For YouTube creators: extract the handle from `YouTube URL` and prefix `yt-`
+3. Otherwise use the primary text label, such as:
+   - `Title`
+   - `Channel Name`
+   - `Creator Name`
+   - `Full Name`
+   - `Name`
+   - `Company Name`
+   - `Deal Name`
+   - `Case Number`
+   - `Invoice Number`
+
+Examples:
+
+- `https://www.youtube.com/@MikeMurphy` -> `yt-mikemurphy-001.md`
+- `Creator Name = Jane Smith` -> `jane-smith-001.md`
+- `Company Name = Acme Corp` -> `acme-corp-001.md`
+
+### NEVER do these
+
+- Do **NOT** default to `{entry_id}.md` for new documents
+- Do **NOT** confuse entry documents with the `Notes` richtext field
+- Do **NOT** create a markdown file without also inserting/updating the `documents` table row
+- Do **NOT** write human-readable files and leave them orphaned from metadata
+
+### Backward compatibility
+
+Older workspaces may still have legacy `{entry_id}.md` files. Those can continue to work, but **new** entry documents should follow the human-readable naming convention above.
+
+---
+
+## Creating One Entry Document
+
+Only create entry `.md` files when the user wants detailed prose for a specific entry or group of entries.
+
+Example:
 
 ```bash
-# Only if you want to add detailed notes for this specific entry
-cat > {{WORKSPACE_PATH}}/lead/abc123.md << 'MD'
-# Meeting Notes - Acme Corp
+cat > {{WORKSPACE_PATH}}/marketing/influencer/yt-mikemurphy-001.md << 'MD'
+# Draft Outreach Email
+
+To: hello@mikemurphy.co
+Subject: Partnership idea
 
-Met with John on 2026-03-15. Key takeaways:
+Hi Mike,
 
-- Interested in enterprise plan
-- Budget approved for Q2
-- Follow up next week with pricing proposal
+I loved your AI Handyman breakdowns. DenchClaw is launching a workflow-native AI platform for builders who want serious control over execution, memory, and automation.
+
+Would you be open to testing it and discussing a possible sponsorship?
 MD
 ```
+
+Then register it:
+
+```sql
+INSERT INTO documents (title, file_path, parent_object_id, entry_id)
+VALUES (
+  'Mike Murphy',
+  'marketing/influencer/yt-mikemurphy-001.md',
+  (SELECT id FROM objects WHERE name = 'influencer'),
+  'yt-mikemurphy-001'
+)
+ON CONFLICT (file_path) DO UPDATE
+SET title = excluded.title,
+    parent_object_id = excluded.parent_object_id,
+    entry_id = excluded.entry_id,
+    updated_at = now();
+```
+
+---
+
+## Batch Creating Entry Documents
+
+When the user asks for docs for many entries, do **not** update the `Notes` field in SQL. Create markdown files plus `documents` rows.
+
+### Workflow
+
+1. Query entries and the fields needed to build filenames/titles
+2. Derive a human-readable filename for each entry
+3. Write one `.md` file per entry under the object directory
+4. Insert/update one `documents` row per file
+
+### Example: create docs for every influencer
+
+```bash
+duckdb {{WORKSPACE_PATH}}/workspace.duckdb -json "
+SELECT
+  entry_id,
+  \"Creator Name\",
+  \"Channel Name\",
+  \"YouTube URL\"
+FROM v_influencer
+ORDER BY \"Creator Name\"
+"
+```
+
+Then for each row:
+
+```bash
+# Example row:
+# entry_id = yt-mikemurphy-001
+# youtube url = https://www.youtube.com/@MikeMurphy
+
+cat > {{WORKSPACE_PATH}}/marketing/influencer/yt-mikemurphy-001.md << 'MD'
+# Influencer Notes
+
+## Outreach draft
+
+...
+MD
+```
+
+Register each file:
+
+```sql
+INSERT INTO documents (title, file_path, parent_object_id, entry_id)
+VALUES (
+  'Mike Murphy',
+  'marketing/influencer/yt-mikemurphy-001.md',
+  (SELECT id FROM objects WHERE name = 'influencer'),
+  'yt-mikemurphy-001'
+)
+ON CONFLICT (file_path) DO UPDATE
+SET title = excluded.title,
+    parent_object_id = excluded.parent_object_id,
+    entry_id = excluded.entry_id,
+    updated_at = now();
+```
+
+---
+
+## Standalone Documents vs Entry Documents
+
+Not every markdown file under an object directory is automatically an entry document.
+
+- **Entry document**: has a corresponding `documents` row with `entry_id` set
+- **Standalone document under an object**: has no `entry_id` link; it is just a nested document in that folder
+
+Examples:
+
+- `marketing/influencer/yt-mikemurphy-001.md` with `documents.entry_id = 'yt-mikemurphy-001'` -> entry document
+- `marketing/influencer/outreach-playbook.md` with no `entry_id` -> standalone object-level document
+
+If a markdown file is meant to be the entry page, always register it in `documents`.

package/skills/crm/duckdb-operations/SKILL.md

@@ -96,6 +96,7 @@ CREATE TABLE IF NOT EXISTS documents (
   file_path VARCHAR NOT NULL UNIQUE,
   parent_id VARCHAR REFERENCES documents(id),
   parent_object_id VARCHAR REFERENCES objects(id),
+  entry_id VARCHAR REFERENCES entries(id),
   sort_order INTEGER DEFAULT 0,
   is_published BOOLEAN DEFAULT false,
   created_at TIMESTAMPTZ DEFAULT now(),
@@ -122,6 +123,8 @@ CREATE TABLE IF NOT EXISTS action_runs (
 
 All ID columns default to `gen_random_uuid()::VARCHAR`. You can also use `nanoid32()` if the macro is loaded. When inserting manually, always generate an ID — never use a placeholder.
 
+For entry detail markdown pages, `documents.entry_id` links a document row to a specific CRM entry while `file_path` stores the human-readable markdown path (for example `marketing/influencer/yt-mikemurphy-001.md`).
+
 ---
 
 ## Auto-Generated PIVOT Views