@rubytech/create-maxy 1.0.793 → 1.0.794

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy",
-  "version": "1.0.793",
+  "version": "1.0.794",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy": "./dist/index.js"

package/payload/platform/lib/graph-search/src/__tests__/fulltext-coverage.test.ts

@@ -85,6 +85,14 @@ const CANONICAL_TEXT_PROPERTIES = [
   "contactValue",
   // ToolCall
   "toolName",
+  // Agent (Task 837) — public-agent projection. `displayName` mirrors
+  // config.json; `slug` is the directory-name identifier; `role` is the
+  // discriminator carried on the four owned :KnowledgeDocument projections
+  // ('identity' | 'soul' | 'knowledge' | 'knowledge-summary'). Adding any
+  // new agent-side text property to the projector requires extending both
+  // the schema's ON EACH list and this canon, otherwise BM25 silently
+  // misses operator queries that match the new field.
+  "displayName", "slug", "role",
 ];
 
 interface IndexDeclaration {

package/payload/platform/neo4j/edge-annotations.json

@@ -111,6 +111,26 @@
     "OBSERVED_IN": {
       "direction": "(*)-[:OBSERVED_IN]->(Conversation)",
       "note": "Observation provenance."
+    },
+    "HAS_IDENTITY": {
+      "direction": "(Agent)-[:HAS_IDENTITY]->(KnowledgeDocument)",
+      "note": "Task 837 — public-agent IDENTITY.md projection (KnowledgeDocument with role='identity', namespaced attachmentId='agent:<slug>:identity')."
+    },
+    "HAS_SOUL": {
+      "direction": "(Agent)-[:HAS_SOUL]->(KnowledgeDocument)",
+      "note": "Task 837 — public-agent SOUL.md projection (role='soul')."
+    },
+    "HAS_KNOWLEDGE": {
+      "direction": "(Agent)-[:HAS_KNOWLEDGE]->(KnowledgeDocument)",
+      "note": "Task 837 — public-agent KNOWLEDGE.md projection (role='knowledge'); KNOWLEDGE-SUMMARY.md uses the same edge with role='knowledge-summary'."
+    },
+    "USES_KNOWLEDGE": {
+      "direction": "(Agent)-[:USES_KNOWLEDGE]->(KnowledgeDocument)",
+      "note": "Task 837 — operator-tagged docs (slug ∈ k.agents). Materialised at projection time only; runtime memory-search reads k.agents directly."
+    },
+    "HANDLED_BY": {
+      "direction": "(Conversation)-[:HANDLED_BY]->(Agent)",
+      "note": "Task 837 — public conversations only. Written by ensureConversation via OPTIONAL MATCH so orphan slugs do not block conversation creation."
     }
   },
   "sublabels": {

package/payload/platform/neo4j/migrations/002-project-public-agents.ts

@@ -0,0 +1,191 @@
+/**
+ * Migration 002 — Project file-based public agents into the graph (Task 837).
+ *
+ * Two passes:
+ *
+ *   1. Walk every account directory under data/accounts/<accountId>/agents/
+ *      and call projectAgent(accountId, accountDir, slug) for each non-admin
+ *      agent that has a config.json. The projector is idempotent: re-running
+ *      this migration produces no duplicate nodes or edges.
+ *
+ *   2. For every existing public Conversation that carries an agentSlug
+ *      property, MATCH the corresponding :Agent and MERGE the
+ *      (:Conversation)-[:HANDLED_BY]->(:Agent) edge. Conversations whose
+ *      slug doesn't resolve to an Agent (orphan slugs from deleted agents,
+ *      or DM-channel public flows that haven't been extended to register a
+ *      slug) are left edge-less; they will gain the edge automatically once
+ *      the slug is registered or a new agent at that slug is projected.
+ *
+ * Run via the platform/ui standalone runtime so it picks up the same
+ * NEO4J_URI / accounts-directory resolution as the server:
+ *
+ *   cd platform/ui && \
+ *     NEO4J_URI=bolt://… NEO4J_PASSWORD=… \
+ *     npx tsx ../neo4j/migrations/002-project-public-agents.ts
+ *
+ * Output: structured `[agent-graph-backfill]` lines per account + a final
+ * totals line. A non-zero exit code on any per-account failure surfaces to
+ * the operator; subsequent accounts are still attempted (the migration is
+ * isolating by account, not all-or-nothing).
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  projectAgent,
+  getSession,
+} from "../../ui/app/lib/neo4j-store";
+import { ACCOUNTS_DIR } from "../../ui/app/lib/claude-agent/account";
+
+interface PerAccountStats {
+  accountId: string;
+  agents: number;
+  agentFailures: number;
+  convEdges: number;
+  convOrphans: number;
+  convCandidates: number;
+}
+
+async function projectAccountAgents(
+  accountId: string,
+  accountDir: string,
+): Promise<{ agents: number; agentFailures: number }> {
+  const agentsDir = resolve(accountDir, "agents");
+  if (!existsSync(agentsDir)) return { agents: 0, agentFailures: 0 };
+
+  let agents = 0;
+  let agentFailures = 0;
+  for (const entry of readdirSync(agentsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === "admin") continue;
+
+    const configPath = resolve(agentsDir, entry.name, "config.json");
+    if (!existsSync(configPath)) continue;
+
+    try {
+      await projectAgent(accountId, accountDir, entry.name);
+      agents++;
+    } catch (err) {
+      agentFailures++;
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `[agent-graph-backfill] account=${accountId.slice(0, 8)} agent=${entry.name} project FAILED error="${msg}"`,
+      );
+    }
+  }
+  return { agents, agentFailures };
+}
+
+interface HandledByBackfillStats {
+  candidates: number;
+  edges: number;
+  orphans: number;
+}
+
+/**
+ * Two-pass: count candidate Conversations (those carrying agentSlug),
+ * then OPTIONAL MATCH to surface orphans separately from successful merges.
+ * A hard MATCH-then-MATCH chain would silently filter orphan-slug rows out,
+ * making `edges=0` indistinguishable from "no public conversations exist"
+ * vs "every slug is orphaned" — different incidents, different fixes.
+ */
+async function backfillHandledByEdges(accountId: string): Promise<HandledByBackfillStats> {
+  const session = getSession();
+  try {
+    const result = await session.run(
+      `MATCH (c:Conversation {accountId: $accountId, agentType: 'public'})
+       WHERE c.agentSlug IS NOT NULL
+       OPTIONAL MATCH (a:Agent {accountId: $accountId, slug: c.agentSlug})
+       FOREACH (_ IN CASE WHEN a IS NULL THEN [] ELSE [1] END | MERGE (c)-[:HANDLED_BY]->(a))
+       RETURN
+         count(c) AS candidates,
+         sum(CASE WHEN a IS NULL THEN 0 ELSE 1 END) AS edges,
+         sum(CASE WHEN a IS NULL THEN 1 ELSE 0 END) AS orphans`,
+      { accountId },
+    );
+    const toNum = (v: unknown): number => {
+      if (typeof v === "number") return v;
+      if (v && typeof (v as { toNumber: () => number }).toNumber === "function") {
+        return (v as { toNumber: () => number }).toNumber();
+      }
+      return 0;
+    };
+    return {
+      candidates: toNum(result.records[0]?.get("candidates")),
+      edges: toNum(result.records[0]?.get("edges")),
+      orphans: toNum(result.records[0]?.get("orphans")),
+    };
+  } finally {
+    await session.close();
+  }
+}
+
+async function main(): Promise<void> {
+  const start = Date.now();
+
+  if (!existsSync(ACCOUNTS_DIR)) {
+    console.error(`[agent-graph-backfill] ACCOUNTS_DIR missing at ${ACCOUNTS_DIR} — nothing to do`);
+    process.exit(0);
+  }
+
+  const accountEntries = readdirSync(ACCOUNTS_DIR, { withFileTypes: true })
+    .filter((e) => e.isDirectory());
+
+  console.error(`[agent-graph-backfill] start accounts=${accountEntries.length}`);
+
+  let totalAgents = 0;
+  let totalAgentFailures = 0;
+  let totalConvEdges = 0;
+  let totalConvOrphans = 0;
+  let totalConvCandidates = 0;
+  const perAccount: PerAccountStats[] = [];
+
+  for (const entry of accountEntries) {
+    const accountDir = resolve(ACCOUNTS_DIR, entry.name);
+    const accountId = entry.name;
+    const accountStart = Date.now();
+
+    const { agents, agentFailures } = await projectAccountAgents(accountId, accountDir);
+    totalAgents += agents;
+    totalAgentFailures += agentFailures;
+
+    let convStats: HandledByBackfillStats = { candidates: 0, edges: 0, orphans: 0 };
+    try {
+      convStats = await backfillHandledByEdges(accountId);
+      totalConvEdges += convStats.edges;
+      totalConvOrphans += convStats.orphans;
+      totalConvCandidates += convStats.candidates;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `[agent-graph-backfill] account=${accountId.slice(0, 8)} handled-by-backfill FAILED error="${msg}"`,
+      );
+    }
+
+    perAccount.push({
+      accountId,
+      agents,
+      agentFailures,
+      convEdges: convStats.edges,
+      convOrphans: convStats.orphans,
+      convCandidates: convStats.candidates,
+    });
+    const ms = Date.now() - accountStart;
+    console.error(
+      `[agent-graph-backfill] account=${accountId.slice(0, 8)} agents=${agents} failures=${agentFailures} conv-candidates=${convStats.candidates} conv-edges=${convStats.edges} conv-orphans=${convStats.orphans} ms=${ms}`,
+    );
+  }
+
+  const ms = Date.now() - start;
+  console.error(
+    `[agent-graph-backfill] done totals: agents=${totalAgents} agent-failures=${totalAgentFailures} conv-candidates=${totalConvCandidates} conv-edges=${totalConvEdges} conv-orphans=${totalConvOrphans} ms=${ms}`,
+  );
+
+  process.exit(totalAgentFailures > 0 ? 1 : 0);
+}
+
+main().catch((err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(`[agent-graph-backfill] fatal error="${msg}"`);
+  process.exit(2);
+});

package/payload/platform/neo4j/schema.cypher

@@ -286,6 +286,7 @@ OPTIONS {
 //   - Email: Email, EmailAccount
 //   - Review signals: ReviewAlert
 //   - CV/career sublabels: Position, Credential
+//   - Public agents: Agent (Task 837 — projection of file-based public agents)
 //
 // Property union — every textual property the schema's writers assign:
 //   - Generic: name, title, summary, body, content, text, description, headline, abstract,
@@ -301,6 +302,11 @@ OPTIONS {
 //   - Credential: authority
 //   - AccessGrant: contactValue
 //   - ToolCall: toolName
+//   - Agent (Task 837): displayName, slug, role
+//     `displayName` = operator-facing name; `slug` = directory-name identifier;
+//     `role` = discriminator on KnowledgeDocument projections
+//     ('identity'|'soul'|'knowledge'|'knowledge-summary') so BM25 hits surface
+//     which file backed the result. Distinct from Person.role (no shadow).
 CREATE FULLTEXT INDEX entity_search IF NOT EXISTS
 FOR (n:LocalBusiness|Service|PriceSpecification|OpeningHoursSpecification|Organization
     |Person|UserProfile|Preference|AdminUser|AccessGrant
@@ -309,12 +315,13 @@ FOR (n:LocalBusiness|Service|PriceSpecification|OpeningHoursSpecification|Organi
     |Task|Project|Event
     |Workflow|WorkflowStep|WorkflowRun|StepResult
     |OnboardingState|Email|EmailAccount|ReviewAlert
-    |Position|Credential)
+    |Position|Credential|Agent)
 ON EACH [n.name, n.firstName, n.lastName, n.givenName, n.familyName,
          n.title, n.currentTitle, n.summary, n.body, n.content, n.text, n.description, n.headline, n.abstract,
          n.email, n.note, n.label, n.value, n.message, n.preview, n.tagline,
          n.subject, n.bodyPreview, n.fromName, n.fromAddress, n.agentAddress, n.screeningReason,
-         n.authority, n.contactValue, n.toolName];
+         n.authority, n.contactValue, n.toolName,
+         n.displayName, n.slug, n.role];
 
 // Project node (Task 740) — a standalone creative-output node distinct from
 // :Section. Anchored via (:UserProfile)-[:CREATED]->(:Project), with optional
@@ -724,6 +731,66 @@ FOR (ag:AccessGrant) ON (ag.magicToken);
 CREATE INDEX access_grant_status IF NOT EXISTS
 FOR (ag:AccessGrant) ON (ag.status);
 
+// ----------------------------------------------------------
+// Agent node — projection of file-based public agents (Task 837)
+//
+// Source of truth remains the filesystem: accountDir/agents/<slug>/
+// {config.json, IDENTITY.md, SOUL.md, KNOWLEDGE.md, KNOWLEDGE-SUMMARY.md}.
+// The Agent node is a graph projection so operators can see, on /graph,
+// which public agents exist, what knowledge they have access to, and
+// which conversations they have handled. Re-running the projector
+// is idempotent and never mutates the on-disk files.
+//
+// Properties (mirrored from config.json + filesystem mtime):
+//   slug              — directory name; immutable identifier within an account
+//   displayName       — operator-facing name from config.json
+//   status            — 'active' | 'inactive' | <other> per config.json
+//   model             — Anthropic model id used by the public agent
+//   liveMemory        — bool; whether memory-search runs at message time
+//   knowledgeKeywords — string[] (live-search keyword subscriptions)
+//   role              — always 'agent' (mirrors KnowledgeDocument.role
+//                       discriminator; surfaces in BM25 hits)
+//   createdAt         — ISO 8601, set on first projection
+//   updatedAt         — ISO 8601, set on every projection
+//
+// Owned KnowledgeDocument projections (deleted on agent delete):
+//   (Agent)-[:HAS_IDENTITY]->(:KnowledgeDocument {role:'identity'})
+//   (Agent)-[:HAS_SOUL    ]->(:KnowledgeDocument {role:'soul'})
+//   (Agent)-[:HAS_KNOWLEDGE]->(:KnowledgeDocument {role:'knowledge'})
+//   (Agent)-[:HAS_KNOWLEDGE]->(:KnowledgeDocument {role:'knowledge-summary'})
+// attachmentId is namespaced as "agent:<accountId>:<slug>:<role>" so the
+// projection reuses the existing knowledge_doc_id_unique constraint without
+// a parallel uniqueness scheme. The accountId segment is load-bearing —
+// without it, two accounts with the same agent slug would collide on the
+// global unique constraint and the second projection would silently
+// re-parent the first account's doc via the MERGE+SET path. Account
+// isolation is doctrine.
+//
+// Operator-tagged docs (NOT deleted on agent delete — only edges removed):
+//   (Agent)-[:USES_KNOWLEDGE]->(:KnowledgeDocument)
+// where slug ∈ KnowledgeDocument.agents. Materialised at projection time
+// only; the runtime memory-search path continues to read k.agents directly,
+// so a doc tagged after the last projection becomes graph-visible at the
+// next re-projection but is reachable at runtime immediately. The runtime
+// path is unchanged — see [public-agent.ts:130-160].
+//
+// Conversation→Agent edge (written by ensureConversation when
+// agentType='public' and agentSlug is set):
+//   (Conversation)-[:HANDLED_BY]->(Agent)
+// OPTIONAL MATCH on the Agent so a public conversation with an orphan
+// slug still writes (single `[agent-graph] handled-by-skip` log line).
+//
+// Composite uniqueness: one Agent per (accountId, slug) — the directory
+// name is the natural key within an account, slugs collide across
+// accounts and that's allowed.
+// ----------------------------------------------------------
+
+CREATE CONSTRAINT agent_account_slug_unique IF NOT EXISTS
+FOR (a:Agent) REQUIRE (a.accountId, a.slug) IS UNIQUE;
+
+CREATE INDEX agent_account IF NOT EXISTS
+FOR (a:Agent) ON (a.accountId);
+
 // ----------------------------------------------------------
 // AdminUser node — device-level admin identity
 // Platform-native. Represents a human who administers one or

package/payload/platform/plugins/admin/skills/public-agent-manager/SKILL.md

@@ -195,7 +195,8 @@ After creation, no template metadata persists in the agent's files. The resultin
 9. **KNOWLEDGE.md generation** — populate from the now-tagged set plus keyword matches using the `update-knowledge` skill workflow
 10. Write `config.json` with selected model, plugins, status "active", `liveMemory`, and `knowledgeKeywords`. This is the last gated write — placed after IDENTITY.md, SOUL.md, and KNOWLEDGE.md to prevent cascade failure if one gate stalls.
 11. Check context budget — auto-summarise if over threshold
-12. Confirm creation: "Agent created. Visitors can reach it at `/{slug}`"
+12. **Project the agent into the graph** — delegate to the `database-operator` specialist with the instruction: "Project public agent `{slug}` into the graph by POSTing to `/api/admin/agents/{slug}/project` (Task 837 surface)." The route reads the on-disk files and idempotently MERGEs the `:Agent` node, the four owned `:KnowledgeDocument` projections (IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY when present, namespaced `attachmentId="agent:<slug>:<role>"`), the `HAS_*` edges, and the `USES_KNOWLEDGE` edges to every operator-tagged doc. Loud-fail: if the route returns non-2xx, surface the error to the user verbatim — the agent's files exist on disk but its graph projection is incomplete, which means the operator's /graph view will not show this agent. Re-running the projection is safe; it is the same idempotent MERGE.
+13. Confirm creation: "Agent created. Visitors can reach it at `/{slug}`"
 
 ### List
 
@@ -231,6 +232,8 @@ For knowledge scope changes:
 - Allow toggling `liveMemory` on/off (update `config.json`).
 - After changes, offer to refresh KNOWLEDGE.md using the `update-knowledge` skill.
 
+**After every Edit operation that touches IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY/`config.json` (including `liveMemory`, `knowledgeKeywords`, or direct-tag mutations), delegate to `database-operator` to re-project: POST `/api/admin/agents/{slug}/project`.** Without re-projection the on-disk files diverge from the graph state — the operator sees stale `:Agent` properties and stale `USES_KNOWLEDGE` edges in /graph. Loud-fail: surface non-2xx errors verbatim.
+
 ### Delete
 
 Deletion removes the entire agent directory (`agents/{slug}/`) — not individual files. A partial deletion leaves ghost state that poisons future creation into the same slug.
@@ -242,7 +245,7 @@ Deletion removes the entire agent directory (`agents/{slug}/`) — not individua
 - If no other agents remain (or the user declines to set a new default), clear the `defaultAgent` field by calling `account-update` with `field: "defaultAgent"`, `value: ""`. Tell the user that visitors to the root URL will see a "no agents" message until a new agent is created.
 
 **Cleanup sequence:**
-- Remove the entire `agents/{slug}/` directory
+- Issue `DELETE /api/admin/agents/{slug}` — the route runs `deleteAgentProjection` (Task 837) FIRST to remove the `:Agent` node and its four owned `:KnowledgeDocument` projections, then `rmSync` the directory. Loud-fail: if graph cleanup throws, files are preserved and a 500 is returned with the error text. Re-issuing the DELETE is safe (idempotent on both layers). Operator-tagged docs survive the projection delete — only the `USES_KNOWLEDGE` edges from this Agent are removed.
 - Verify the directory no longer exists
 - Report what was removed (list the files that were in the directory)
 

package/payload/platform/plugins/docs/references/platform.md

@@ -65,7 +65,7 @@ There is no dashboard, no settings panel, no menus. Everything is done through c
 
 The chat input auto-grows as you type — it expands to fit your message and shrinks back when you delete text. You can also drag the resize handle above the input to set a custom height.
 
-The admin interface is a three-pane layout: a sidebar on the left with your brand mark, navigation (Chat, Projects, Artefacts), and your recent conversations; the chat in the middle; and an artefact pane on the right that opens when you select a document, click a project, or open Browser, Data, or Graph from the menu — holding the surface side-by-side with the conversation so the chat stays live while you work in it. The sidebar's nav rows swap the list view in place — Chat shows recent conversations, Projects shows your active work projects, and Artefacts lists every KnowledgeDocument plus this account's agent templates (your admin agent's IDENTITY, SOUL, and KNOWLEDGE files plus one entry per enabled specialist). Click an artefact row to open the document. KnowledgeDocuments and your admin agent's templates are editable — type in the document and changes save automatically; specialist agent templates are read-only because they ship with Maxy and your edits would be overwritten on the next install. PDF artefacts render inline so you can read them without leaving the pane. If your browser doesn't have a built-in PDF viewer, a Download button appears instead. Artefacts that have no readable file backing them (orphan rows, files removed from disk, unsupported content types) show a one-line banner explaining the skip instead of opening to a blank pane. Click a project row to open the Graph view focused on that project's neighbourhood — clicking a second project swaps the focus rather than stacking on top. The chat / artefact divider is drag-resizable — drag the line between the columns to make either side wider; double-click it to reset to half of the available width (viewport minus sidebar), clamped to the chat / artefact min-width floors. Your chosen width is remembered across reloads. On wider screens (>1280px) all three panes are visible. The sidebar narrows at 1280px, the artefact pane hides at 1080px (Browser, Data, and Graph then open as full-window pages instead), and the sidebar collapses to a 56px icon rail at 820px. On phones (<640px) the sidebar slides in as a drawer from the left when you tap the menu icon in the chat header.
+The admin interface is a three-pane layout: a sidebar on the left with your brand mark, navigation (Chat, People, Agents, Projects, Tasks, Artefacts), and your recent conversations; the chat in the middle; and an artefact pane on the right that opens when you select a document, click a project, or open Browser, Data, or Graph from the menu — holding the surface side-by-side with the conversation so the chat stays live while you work in it. The sidebar's nav rows swap the list view in place — Chat shows recent conversations, Projects shows your active work projects, and Artefacts lists every KnowledgeDocument plus this account's agent templates (your admin agent's IDENTITY, SOUL, and KNOWLEDGE files plus one entry per enabled specialist). The People, Agents, and Tasks rows are graph shortcuts: clicking each opens the artefact-pane Graph filtered to every Person, every public Agent, or every Task in your account respectively, with no side-list — the graph itself is the result. Public agents become first-class graph entities the moment you create them, with edges to their IDENTITY/SOUL/KNOWLEDGE files, edges to every knowledge document they have access to, and edges from every conversation they have handled, so a single Agents click reveals the whole shape of who knows what and who has been talking to whom. Click an artefact row to open the document. KnowledgeDocuments and your admin agent's templates are editable — type in the document and changes save automatically; specialist agent templates are read-only because they ship with Maxy and your edits would be overwritten on the next install. PDF artefacts render inline so you can read them without leaving the pane. If your browser doesn't have a built-in PDF viewer, a Download button appears instead. Artefacts that have no readable file backing them (orphan rows, files removed from disk, unsupported content types) show a one-line banner explaining the skip instead of opening to a blank pane. Click a project row to open the Graph view focused on that project's neighbourhood — clicking a second project swaps the focus rather than stacking on top. The chat / artefact divider is drag-resizable — drag the line between the columns to make either side wider; double-click it to reset to half of the available width (viewport minus sidebar), clamped to the chat / artefact min-width floors. Your chosen width is remembered across reloads. On wider screens (>1280px) all three panes are visible. The sidebar narrows at 1280px, the artefact pane hides at 1080px (Browser, Data, and Graph then open as full-window pages instead), and the sidebar collapses to a 56px icon rail at 820px. On phones (<640px) the sidebar slides in as a drawer from the left when you tap the menu icon in the chat header.
 
 Page titles are brand-aware: the browser tab shows your product name (e.g. `Real Agent` instead of `Maxy`) on every shell — chat, graph, and data — so a non-default brand never leaks the default name in tab strips or browser history.