@treenity/mods 3.0.3 → 3.0.5

package/metatron/permissions.ts

@@ -0,0 +1,76 @@
+// Metatron permission system
+// 1. Pending permission resolvers — shared between approve action (types.ts) and query runner (claude.ts)
+// 2. Rule matching engine — evaluates tree-stored rules against tool calls
+// Separate module to avoid pulling @anthropic-ai/claude-agent-sdk into browser bundle.
+
+export type PermissionPolicy = 'allow' | 'ask-once' | 'ask-always' | 'deny';
+
+export type PermissionRule = {
+  tool: string;         // glob pattern: 'mcp__treenity__*', '*'
+  pathPattern: string;  // optional input.path pattern
+  policy: PermissionPolicy;
+};
+
+// ── Pending permission resolvers ──
+
+export type PermissionMeta = {
+  tool?: string;
+  input?: string;
+  agentPath?: string;
+  scope?: string;
+};
+
+export const pendingPermissions = new Map<string, (allow: boolean, meta?: PermissionMeta) => void>();
+
+export function resolvePermission(id: string, allow: boolean, meta?: PermissionMeta) {
+  const resolve = pendingPermissions.get(id);
+  if (!resolve) return;
+  pendingPermissions.delete(id);
+  resolve(allow, meta);
+}
+
+import { globMatch } from '@treenity/core/glob';
+
+// ── Rule specificity (more specific = higher score) ──
+
+function ruleSpecificity(rule: PermissionRule): number {
+  let score = 0;
+  // Exact tool name > glob pattern > wildcard
+  if (!rule.tool.includes('*')) score += 100;
+  else if (rule.tool !== '*') score += 50;
+  // Path pattern adds specificity
+  if (rule.pathPattern) score += 10;
+  return score;
+}
+
+// ── Evaluate permission against rules ──
+
+export function evaluatePermission(
+  rules: PermissionRule[],
+  toolName: string,
+  input: unknown,
+): PermissionPolicy | null {
+  const inputPath = (input && typeof input === 'object' && 'path' in input)
+    ? String((input as any).path)
+    : '';
+
+  // Find all matching rules
+  const matches = rules.filter(r => {
+    if (!globMatch(r.tool, toolName)) return false;
+    if (r.pathPattern && inputPath && !globMatch(r.pathPattern, inputPath)) return false;
+    return true;
+  });
+
+  if (!matches.length) return null; // no rule matched — caller decides default
+
+  // Sort by specificity (most specific first), then by deny > ask > allow priority
+  const policyPriority: Record<string, number> = { deny: 3, 'ask-always': 2, 'ask-once': 1, allow: 0 };
+
+  matches.sort((a, b) => {
+    const specDiff = ruleSpecificity(b) - ruleSpecificity(a);
+    if (specDiff !== 0) return specDiff;
+    return (policyPriority[b.policy] ?? 0) - (policyPriority[a.policy] ?? 0);
+  });
+
+  return matches[0].policy;
+}

package/metatron/seed.ts

@@ -0,0 +1,50 @@
+import { type NodeData } from '@treenity/core';
+import { registerPrefab } from '@treenity/core/mod';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+registerPrefab('metatron', 'seed', [
+  { $path: 'metatron', $type: 'metatron.config',
+    model: 'claude-opus-4-6', systemPrompt: '', sessionId: '', lastRun: 0 },
+
+  { $path: 'metatron/tasks', $type: 'dir' },
+
+  // Query mounts — virtual folders filtered by task status
+  { $path: 'metatron/inbox', $type: 'mount-point',
+    mount: { $type: 't.mount.query' },
+    query: { $type: 'query', source: '/metatron/tasks', match: { $type: 'metatron.task', status: { $in: ['pending', 'running'] } } } },
+  { $path: 'metatron/done', $type: 'mount-point',
+    mount: { $type: 't.mount.query' },
+    query: { $type: 'query', source: '/metatron/tasks', match: { $type: 'metatron.task', status: 'done' } } },
+
+  // Skills — modular prompt fragments
+  { $path: 'metatron/skills', $type: 'dir' },
+  { $path: 'metatron/skills/tree-admin', $type: 'metatron.skill',
+    name: 'Tree Admin',
+    prompt: 'You are a Treenity tree administrator. You can create, read, update, and delete nodes using MCP tools. Use catalog and describe_type to discover available types before creating nodes.',
+    enabled: true, category: 'core', updatedAt: 0 },
+  { $path: 'metatron/skills/self-learning', $type: 'metatron.skill',
+    name: 'Self-Learning',
+    prompt: 'After completing a task successfully, reflect on what you learned. If you discovered a reusable principle, pattern, or gotcha — save it as a skill at /metatron/skills/. Check existing skills first (list_children), update rather than duplicate. Skills should be concise (1-3 sentences) and actionable.',
+    enabled: true, category: 'meta', updatedAt: 0 },
+
+  // Memory — persistent facts/preferences
+  { $path: 'metatron/memory', $type: 'dir' },
+
+  // Workspaces — multi-task columns
+  { $path: 'metatron/workspaces', $type: 'dir' },
+
+  { $path: '/sys/autostart/metatron', $type: 'ref', $ref: '/metatron' },
+] as NodeData[], (nodes) => {
+  // Load metatron prompt from docs
+  let systemPrompt = '';
+  try {
+    systemPrompt = readFileSync(join(process.cwd(), 'docs/metatron-prompt.md'), 'utf8');
+  } catch {
+    console.warn('[seed] docs/metatron-prompt.md not found, metatron systemPrompt will be empty');
+  }
+
+  return nodes.map(n =>
+    n.$path === 'metatron' ? { ...n, systemPrompt } : n,
+  );
+});

package/metatron/server.ts

@@ -0,0 +1,3 @@
+import './types';
+import './service';
+import './seed';

package/metatron/service.ts

@@ -0,0 +1,368 @@
+// Metatron — AI task queue + Claude CLI service
+// 1. action:task — creates task nodes in /metatron inbox
+// 2. service — watches for pending tasks, auto-invokes Claude CLI via MCP
+// Prompt lives in the node (systemPrompt). First run sends full prompt.
+// Subsequent runs (with sessionId) send just "check inbox" — Claude already has context.
+// Streaming: progress visible on running task nodes in real-time.
+// Abort: user can stop a running task via task.stop() → abortQuery in claude.ts.
+// Inject: user can queue messages via task.inject() → processed after current run.
+
+import { createNode, type NodeData, register } from '@treenity/core';
+import { type ServiceCtx } from '@treenity/core/contexts/service';
+import { type ActionCtx } from '@treenity/core/server/actions';
+import { buildClaims, withAcl } from '@treenity/core/server/auth';
+import { debouncedWrite } from '@treenity/core/util/debounced-write';
+import { closeSession, invokeClaude } from './claude';
+import { uniqueMentionPaths } from './mentions';
+import { type PermissionRule } from './permissions';
+
+const log = (msg: string) => console.log(`[metatron] ${msg}`);
+
+const CHECK_INBOX = 'Check your inbox at /metatron/inbox. Process all pending tasks.';
+
+// ── Load enabled skills from /metatron/skills/* ──
+
+async function loadSkills(ctx: ServiceCtx, configPath: string): Promise<string> {
+  try {
+    const { items } = await ctx.tree.getChildren(`${configPath}/skills`);
+    const enabled = items.filter(s => s.$type === 'metatron.skill' && s.enabled && s.prompt);
+    if (!enabled.length) return '';
+
+    const sections = enabled.map(s => {
+      const name = String(s.name || s.$path.split('/').at(-1));
+      return `### ${name}\n${String(s.prompt)}`;
+    });
+
+    log(`  loaded ${enabled.length} skill(s)`);
+    return '\n\n## Active Skills\n\n' + sections.join('\n\n');
+  } catch {
+    return '';
+  }
+}
+
+// ── Load permission rules from /metatron/permissions/* ──
+
+async function loadPermissions(ctx: ServiceCtx, configPath: string): Promise<PermissionRule[]> {
+  try {
+    const { items } = await ctx.tree.getChildren(`${configPath}/permissions`);
+    const rules = items
+      .filter(n => n.$type === 'metatron.permission' && n.tool)
+      .map(n => ({
+        tool: String(n.tool),
+        pathPattern: String(n.pathPattern || ''),
+        policy: (n.policy as PermissionRule['policy']) || 'allow',
+      }));
+    if (rules.length) log(`  loaded ${rules.length} permission rule(s)`);
+    return rules;
+  } catch {
+    return [];
+  }
+}
+
+// ── Resolve @/path mentions in prompts → context section ──
+// Uses ACL-wrapped tree scoped to the task creator's permissions.
+// withAcl.get() returns undefined for denied paths — no existence leakage.
+
+const SENSITIVE_RE = /(password|secret|token|key|hash|credentials|apiKey|api_key)/i;
+
+export async function resolveContext(
+  store: import('@treenity/core/tree').Tree,
+  prompts: string[],
+  createdBy: string | null,
+): Promise<string> {
+  const allPaths = new Set<string>();
+  for (const p of prompts) {
+    for (const path of uniqueMentionPaths(p)) allPaths.add(path);
+  }
+
+  if (!allPaths.size) return '';
+
+  // ACL-scoped tree for the task creator
+  const claims = createdBy ? await buildClaims(store, createdBy) : ['public'];
+  const userTree = withAcl(store, createdBy, claims);
+
+  const MAX_MENTIONS = 5;
+  const paths = [...allPaths].slice(0, MAX_MENTIONS);
+  const sections: string[] = [];
+
+  for (const path of paths) {
+    try {
+      const node = await userTree.get(path);
+      if (!node) {
+        sections.push(`### ${path}\n(not found or access denied)`);
+        continue;
+      }
+      // Include type + top-level fields, strip system and sensitive fields
+      const summary: Record<string, unknown> = { $type: node.$type };
+      // use getComponents for this loop
+      for (const [k, v] of Object.entries(node)) {
+        if (k.startsWith('$')) continue;
+        if (SENSITIVE_RE.test(k)) continue;
+        if (typeof v === 'object' && v && '$type' in v) {
+          // Named component — filter its keys too
+          const comp: Record<string, unknown> = { $type: (v as any).$type };
+          for (const [ck, cv] of Object.entries(v as Record<string, unknown>)) {
+            if (ck.startsWith('$') || SENSITIVE_RE.test(ck)) continue;
+            comp[ck] = typeof cv === 'string' && cv.length > 500 ? cv.slice(0, 500) + '...' : cv;
+          }
+          summary[k] = comp;
+          continue;
+        }
+        if (typeof v === 'string' && v.length > 500) {
+          summary[k] = v.slice(0, 500) + '...';
+        } else {
+          summary[k] = v;
+        }
+      }
+      sections.push(`### ${path}\n\`\`\`json\n${JSON.stringify(summary, null, 2)}\n\`\`\``);
+    } catch {
+      sections.push(`### ${path}\n(error reading node)`);
+    }
+  }
+
+  return '\n\n## Referenced Nodes\n\n' + sections.join('\n\n');
+}
+
+// ── Action: create a task ──
+
+/** @description Create a task for AI processing in the Metatron inbox */
+register('metatron.config', 'action:task', async (ctx: ActionCtx, data: { prompt: string }) => {
+  if (!data.prompt) throw new Error('prompt is required');
+
+  const id = `t-${Date.now()}`;
+  const taskPath = `${ctx.node.$path}/tasks/${id}`;
+
+  await ctx.tree.set(createNode(taskPath, 'metatron.task', {
+    prompt: data.prompt,
+    status: 'pending',
+    createdAt: Date.now(),
+    createdBy: ctx.userId ?? null,
+  }));
+
+  log(`task created: ${taskPath} — "${data.prompt.slice(0, 80)}"`);
+  return { taskPath };
+}, { description: 'Create a task for AI', params: 'prompt' });
+
+// ── Service: watch inbox, auto-invoke Claude ──
+
+register('metatron.config', 'service', async (node: NodeData, ctx: ServiceCtx) => {
+  let running = false;
+  let stopped = false;
+  let pendingRecheck = false;
+  let runCount = 0;
+
+  log(`service started at ${node.$path}`);
+
+  async function updateTask(path: string, fields: Record<string, unknown>) {
+    const task = await ctx.tree.get(path);
+    if (task) await ctx.tree.set({ ...task, ...fields });
+  }
+
+  async function updateRunningTasks(paths: string[], output: string) {
+    for (const p of paths) {
+      const task = await ctx.tree.get(p);
+      if (task && task.status === 'running') {
+        const { $rev: _, ...rest } = task;
+        await ctx.tree.set({ ...rest, log: output });
+      }
+    }
+  }
+
+  // Check if any running tasks have queued inject messages
+  async function drainInjected(paths: string[]): Promise<string | null> {
+    for (const p of paths) {
+      const task = await ctx.tree.get(p);
+      const injected = task?.injected as string[] | undefined;
+      if (injected?.length) {
+        const messages = [...injected];
+        await ctx.tree.set({ ...task!, injected: [] });
+        return messages.join('\n\n');
+      }
+    }
+    return null;
+  }
+
+  async function processInbox() {
+    if (running) {
+      log('already running, will recheck after');
+      pendingRecheck = true;
+      return;
+    }
+    if (stopped) return;
+
+    const tasksPath = `${node.$path}/tasks`;
+    const { items } = await ctx.tree.getChildren(tasksPath);
+    const tasks = items.filter(t => t.$type === 'metatron.task');
+    const pending = tasks.filter(t => t.status === 'pending');
+    // Recover tasks stuck in "running" from a previous crash
+    const stuck = tasks.filter(t => t.status === 'running');
+    for (const t of stuck) {
+      log(`  recovering stuck task: ${t.$path} -> pending`);
+      await updateTask(t.$path, { status: 'pending', result: '' });
+      pending.push(t);
+    }
+
+    log(`inbox scan: ${pending.length} pending / ${tasks.length} total tasks`);
+    if (!pending.length) return;
+
+    running = true;
+    runCount++;
+    const runId = runCount;
+    log(`run #${runId}: processing ${pending.length} task(s)...`);
+
+    const runningPaths = pending.map(t => t.$path);
+
+    // Mark all pending tasks as "running" with initial progress
+    for (const t of pending) {
+      log(`  -> running: ${t.$path}`);
+      await updateTask(t.$path, { status: 'running', result: 'Waiting for Claude...' });
+    }
+
+    try {
+      const config = await ctx.tree.get(node.$path) as NodeData;
+      const sessionId = config.sessionId as string || '';
+      const systemPrompt = config.systemPrompt as string || '';
+
+      const isResume = !!sessionId;
+      const skillsSection = isResume ? '' : await loadSkills(ctx, node.$path);
+      const taskPrompts = pending.map(t => String(t.prompt || ''));
+      const createdBy = (pending[0]?.createdBy as string) ?? null;
+      const contextSection = isResume ? '' : await resolveContext(ctx.tree, taskPrompts, createdBy);
+      const prompt = isResume ? CHECK_INBOX : (systemPrompt + skillsSection + contextSection) || CHECK_INBOX;
+      const permissionRules = await loadPermissions(ctx, node.$path);
+
+      log(`run #${runId}: ${isResume ? 'RESUME session ' + sessionId.slice(0, 8) + '...' : 'NEW session (' + prompt.length + ' chars)'}`);
+
+      // Stream output — debounced progress updates
+      let tailBuf = '';
+      const progress = debouncedWrite(async () => {
+        await updateRunningTasks(runningPaths, tailBuf);
+      }, 2000, 'metatron.progress');
+
+      const onOutput = (chunk: string) => {
+        tailBuf += chunk;
+        progress.trigger();
+      };
+
+      let result;
+      try {
+        result = await invokeClaude(prompt, {
+          key: node.$path,
+          sessionId: sessionId || undefined,
+          model: config.model as string || undefined,
+          permissionRules,
+          onOutput,
+        });
+      } catch (sessionErr) {
+        if (isResume) {
+          const errMsg = sessionErr instanceof Error ? sessionErr.message : String(sessionErr);
+          log(`  session resume failed: ${errMsg} — clearing session, retrying fresh`);
+          closeSession(node.$path);
+          const freshConfig = await ctx.tree.get(node.$path) as NodeData;
+          await ctx.tree.set({ ...freshConfig, sessionId: '' });
+
+          tailBuf = '';
+          const retrySkills = await loadSkills(ctx, node.$path);
+          result = await invokeClaude((systemPrompt + retrySkills) || CHECK_INBOX, {
+            key: node.$path,
+            model: config.model as string || undefined,
+            permissionRules,
+            onOutput,
+          });
+        } else {
+          throw sessionErr;
+        }
+      }
+
+      progress.cancel();
+
+      // Final update on config: session ID + last run
+      const fresh = await ctx.tree.get(node.$path) as NodeData;
+      await ctx.tree.set({
+        ...fresh,
+        sessionId: result.sessionId ?? fresh.sessionId,
+        lastRun: Date.now(),
+      });
+
+      // Task status: aborted → done (with log preserved), error → error, else → done
+      const finalStatus = result.aborted ? 'done' : result.error ? 'error' : 'done';
+      for (const p of runningPaths) {
+        const task = await ctx.tree.get(p);
+        if (task) {
+          await ctx.tree.set({
+            ...task,
+            status: finalStatus,
+            log: result.output,
+            result: result.aborted
+              ? (result.text || '[interrupted by user]')
+              : (result.text || result.output),
+          });
+        }
+      }
+
+      log(`run #${runId}: ${result.aborted ? 'ABORTED' : 'done'}. session=${result.sessionId?.slice(0, 8) ?? 'none'} cost=$${result.costUsd ?? '?'}`);
+
+      // Check for injected follow-up messages — if found, process them immediately
+      if (!result.aborted && result.sessionId) {
+        const followUp = await drainInjected(runningPaths);
+        if (followUp) {
+          log(`run #${runId}: processing injected follow-up`);
+          running = false; // allow re-entry
+          // Re-set tasks to running for the follow-up
+          for (const p of runningPaths) {
+            await updateTask(p, { status: 'running', result: 'Processing follow-up...' });
+          }
+          // Recursive process with pending tasks will pick them up
+          pendingRecheck = true;
+        }
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      log(`run #${runId}: FAILED — ${msg}`);
+
+      // Revert running tasks back to pending so they can be retried
+      for (const p of runningPaths) {
+        const current = await ctx.tree.get(p);
+        if (current && current.status === 'running') {
+          log(`  -> reverting to pending: ${p}`);
+          await ctx.tree.set({ ...current, status: 'pending', result: `Error: ${msg}` });
+        }
+      }
+
+      const fresh = await ctx.tree.get(node.$path) as NodeData;
+      await ctx.tree.set({
+        ...fresh,
+        lastRun: Date.now(),
+      });
+    } finally {
+      running = false;
+    }
+
+    if (!stopped && pendingRecheck) {
+      pendingRecheck = false;
+      log('recheck triggered (new tasks arrived during run)');
+      processInbox();
+    }
+  }
+
+  const unsub = ctx.subscribe(`${node.$path}/tasks`, (event) => {
+    log(`event: ${event.type} ${event.path}`);
+    if (event.type === 'set' || event.type === 'patch') {
+      processInbox();
+    }
+  }, { children: true });
+
+  // Initial inbox check on startup
+  log('initial inbox check...');
+  processInbox();
+
+  return {
+    stop: async () => {
+      log('service stopping');
+      stopped = true;
+      unsub();
+      closeSession(node.$path);
+      log('service stopped');
+    },
+  };
+});

package/metatron/types.ts

@@ -0,0 +1,120 @@
+import { getCtx, registerType } from '@treenity/core/comp';
+
+/** AI orchestrator config — model, system prompt, session tracking */
+export class MetatronConfig {
+  model = 'claude-opus-4-6';
+  /** @format textarea */
+  systemPrompt = '';
+  sessionId = '';
+  lastRun = 0;
+}
+
+/** AI task — prompt with status and result of LLM execution */
+export class MetatronTask {
+  /** @format textarea */
+  prompt = '';
+  status: 'pending' | 'running' | 'done' | 'error' = 'pending';
+  /** @format textarea */
+  result = '';
+  /** @format textarea */
+  log = '';
+  createdAt = 0;
+  /** Queued user messages to process after current run */
+  injected: string[] = [];
+  /** Source task path if forked */
+  forkedFrom = '';
+  /** Log position where the fork was made */
+  forkIndex = 0;
+
+  /** @description Stop the running task */
+  async stop() {
+    if (this.status !== 'running') throw new Error('task is not running');
+    const { node } = getCtx();
+    const configPath = node.$path.replace(/\/tasks\/[^/]+$/, '');
+    const { abortQuery } = await import('./claude');
+    abortQuery(configPath);
+  }
+
+  /** @description Queue a follow-up message for the running task */
+  async inject(data: { /** Message text */ text: string }) {
+    if (!data.text?.trim()) throw new Error('text is required');
+    this.injected.push(data.text.trim());
+  }
+
+  /** @description Fork this conversation at a specific log position */
+  async fork(data: { /** Character position in log to fork at */ atIndex: number }) {
+    const { tree, node } = getCtx();
+    const { createNode } = await import('@treenity/core');
+    const configPath = node.$path.replace(/\/tasks\/[^/]+$/, '');
+    const id = `t-${Date.now()}`;
+    const forkPath = `${configPath}/tasks/${id}`;
+    const logSlice = this.log.slice(0, data.atIndex);
+
+    await tree.set(createNode(forkPath, 'metatron.task', {
+      prompt: `[forked from ${node.$path.split('/').at(-1)}] ${this.prompt}`,
+      status: 'done',
+      result: logSlice,
+      log: logSlice,
+      createdAt: Date.now(),
+      forkedFrom: node.$path,
+      forkIndex: data.atIndex,
+    }));
+
+    return { taskPath: forkPath };
+  }
+}
+
+/** Permission rule — controls which tools Metatron is allowed to use */
+export class MetatronPermission {
+  /** Tool name or glob pattern: 'mcp__treenity__*', '*' */
+  tool = '';
+  /** Optional input.path pattern */
+  pathPattern = '';
+  policy: 'allow' | 'deny' = 'allow';
+  createdAt = 0;
+}
+
+/** Reusable prompt template for quick task creation */
+export class MetatronTemplate {
+  name = '';
+  /** @format textarea */
+  prompt = '';
+  category = '';
+}
+
+/** Modular prompt fragment — learned skill or injected capability */
+export class MetatronSkill {
+  name = '';
+  /** @format textarea */
+  prompt = '';
+  enabled = true;
+  category = '';
+  updatedAt = 0;
+}
+
+/** Multi-task workspace — side-by-side columns of conversations */
+export class MetatronWorkspace {
+  name = '';
+  columns: string[] = [];
+
+  /** @description Add a task as a column */
+  async addColumn(data: { /** Task path */ taskPath: string }) {
+    if (!data.taskPath) throw new Error('taskPath is required');
+    if (this.columns.includes(data.taskPath)) return;
+    this.columns.push(data.taskPath);
+  }
+
+  /** @description Remove a column by task path */
+  async removeColumn(data: { /** Task path */ taskPath: string }) {
+    const idx = this.columns.indexOf(data.taskPath);
+    if (idx === -1) throw new Error('column not found');
+    this.columns.splice(idx, 1);
+  }
+}
+
+registerType('metatron.config', MetatronConfig);
+registerType('metatron.task', MetatronTask);
+registerType('metatron.permission', MetatronPermission);
+registerType('metatron.template', MetatronTemplate);
+registerType('metatron.skill', MetatronSkill);
+registerType('metatron.workspace', MetatronWorkspace);

package/metatron/view.tsx

@@ -0,0 +1,4 @@
+// Barrel — registers all metatron views
+import './views/config';
+import './views/task';
+import './views/workspace';