total-recall-brain 3.35.0 → 3.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.35.0",
+  "version": "3.37.0",
   "description": "Personal AI system — database-free, SSSS-powered intelligence engine deployable to any POSIX host.",
   "type": "module",
   "workspaces": [
@@ -22,8 +22,6 @@
     "frontend/index.html",
     "frontend/src/",
     "extension/",
-    "plugins/",
-    "!plugins/**/*.spec.mjs",
     "templates/",
     "scaffold/",
     "docs/ARCHITECTURE.md",
@@ -47,7 +45,7 @@
     "routes:manifest": "node scripts/generate-route-manifest.mjs",
     "clean": "rm -rf scratch/* .remember/* *.log",
     "check:dist": "node scripts/check-dist-freshness.mjs",
-    "prepublishOnly": "npm run check:dist",
+    "prepublishOnly": "npm run check:dist && node scripts/check-scaffold-state.mjs",
     "check:ssss-registry": "node scripts/check-ssss-registry.mjs"
   },
   "repository": {
@@ -82,7 +80,6 @@
     "natural": "^8.1.1",
     "preact": "^10.29.7",
     "sqlite-vss": "^0.1.2",
-    "total-recall-brain": "^3.17.0",
     "ws": "^8.18.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"

package/scaffold/.agent/skills/plugins/SKILL.md

@@ -1,15 +1,209 @@
 ---
 name: plugins
-description: Create, validate, install or share Total Recall plugins.
+description: Standards, authoring guide, and CLI workflows for Total Recall plugins.
 repo_scoped: false
 ---
 
-<!-- total-recall:skill-router:v1 -->
+# Total Recall Plugin Standard & Authoring Guide
 
-# Plugins
+Total Recall capabilities beyond portable memory belong in standalone plugins. This specification details the executable plugin contract, step-by-step authoring procedures, and CLI workflows ensuring any user-authored plugin remains completely compatible across the Total Recall ecosystem.
 
-Use the plugin workspace and current `plugin.json`/extension contracts. Keep optional capabilities in plugins rather than portable memory core. Every claimed command, schedule, UI/API action or memory extension needs a real handler and validation.
+## Core Architectural Invariants
 
-Read implementation or installation references for that operation. Verify scopes, invalid input, canonical SSSS writes, failure reporting and actual execution. Sharing requires explicit authorization; public bundles exclude credentials, private vault content and runtime state. Read sharing procedures only when sharing is requested.
+1. **Portable Memory Separation**: Core Total Recall maintains only portable memory, the SSSS vault, and instruction compilers. Auxiliary tools, domain features, telephony, specialized analyzers, and user interfaces must exist as independent plugins.
+2. **Standard Manifest (`plugin.json`)**: Every plugin defines an authoritative `plugin.json` adhering to `metadata.plugin.schema.json`.
+3. **Canonical State via SSSS**: Plugins must never perform unmanaged raw filesystem writes. Persistent records, configuration overlays, and event telemetry must use SSSS VFS operations.
+4. **Token-Driven UI Elements**: Plugin interface components must avoid hardcoded color values. Visual styling must reference standard design tokens from `DESIGN.md`.
+5. **No AI Slop & Clean Copy**: Plugin documentation and user-facing text must avoid trite terms such as "sovereign", "synergy", or "leverage", and must never conclude any sentence with a preposition.
 
-Before an operation, read its [task references](references/optimized/index.md), including prerequisites and constraints. If the applicable procedure is unclear, read the preserved original instead of guessing. Commands assume the skill root.
+---
+
+## The Plugin Manifest Contract (`plugin.json`)
+
+A valid plugin contains `plugin.json` at its root:
+
+```json
+{
+  "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
+  "id": "my-plugin",
+  "name": "My Plugin",
+  "version": "1.0.0",
+  "description": "Concrete explanation of the exact job this plugin performs.",
+  "author": "Author Name",
+  "license": "MIT",
+  "use_cases": ["developer-tools"],
+  "cli": {
+    "command": "my-tool",
+    "handler": "./cli.mjs",
+    "subcommands": [
+      { "name": "status", "description": "Display runtime status" },
+      { "name": "run", "description": "Execute main capability" }
+    ]
+  },
+  "runtime": {
+    "jobs": [
+      {
+        "id": "periodic-check",
+        "schedule": "0 * * * *",
+        "command": "status",
+        "description": "Hourly status verification"
+      }
+    ],
+    "daemons": [],
+    "startup": []
+  },
+  "deploy": {
+    "targets": ["ssss-app", "nextjs", "react", "flask"],
+    "required_ssss_version": ">=0.9.3",
+    "access_grants": ["ssss:vault:read", "ssss:vault:write"]
+  }
+}
+```
+
+### Manifest Specifications
+
+- **`id`** *(required)*: Lowercase kebab-case string (`^[a-z][a-z0-9-]{1,63}$`). Must match the repository or folder identifier.
+- **`name`** *(required)*: Human-readable display label.
+- **`version`** *(required)*: Semantic version string (`x.y.z`).
+- **`description`** *(required)*: Clear, functional explanation (minimum 5 characters).
+- **`use_cases`** *(optional)*: Array of kebab-case tags used for catalog indexing and search filters.
+- **`cli`** *(optional)*: Declares the CLI command name, the relative ES module handler (`cli.mjs`), and an array of subcommands.
+- **`runtime`** *(optional)*:
+  - **`jobs`**: Scheduled background cron routines (`schedule`, `command`, `timeout_seconds`, `secrets`).
+  - **`daemons`**: Continuously running background services (`handler`, `restart`, `stop_signal`).
+  - **`startup`**: Lifecycle initialization hooks executed when the host begins execution.
+- **`deploy`** *(optional)*: Target application hosts and required SSSS permission scopes.
+- **`ui`** *(optional)*: Declares reusable custom web component elements (`elements[]`), property interfaces, and required design tokens.
+
+---
+
+## Step-by-Step Plugin Creation Workflow
+
+### Step 1: Scaffold the Plugin
+Initialize a new plugin structure through the CLI:
+```bash
+total-recall plugin create my-plugin --name "My Plugin" --description "Handles custom workflows" --use-case automation --with-cli
+```
+This scaffolds a standard directory containing `plugin.json`, `cli.mjs`, and documentation.
+
+### Step 2: Implement the Command Handler (`cli.mjs`)
+The handler module must export a callable function:
+```javascript
+/**
+ * CLI Handler for my-plugin
+ * @param {string[]} argv - Command-line arguments passed after the command name
+ */
+export async function run(argv) {
+  const [subcommand, ...args] = argv.slice(2);
+  
+  if (subcommand === "status") {
+    console.log("My Plugin is fully operational.");
+    return;
+  }
+  
+  if (subcommand === "run") {
+    console.log("Executing capability with arguments:", args);
+    return;
+  }
+
+  console.log("Usage: total-recall my-tool <status|run>");
+}
+
+export default run;
+```
+
+### Step 3: Add SSSS Memory Categories (Optional)
+If your plugin defines new structured memory types, declare them inside `plugin.json`:
+```json
+"ssss_schemas": {
+  "categories": [
+    {
+      "name": "custom-audit",
+      "description": "Structured records for compliance tracking",
+      "node_type": "memory",
+      "template": "./templates/audit.md"
+    }
+  ]
+}
+```
+
+### Step 4: Validate the Plugin
+Run validation before publishing or deploying:
+```bash
+total-recall plugin info my-plugin
+```
+Ensure the validator returns zero schema errors.
+
+---
+
+## Operating Plugins Through the Total Recall CLI
+
+The Total Recall CLI provides complete lifecycle management for plugins:
+
+### 1. Discover and Search
+- **List installed plugins**:
+  ```bash
+  total-recall plugin list
+  ```
+- **List available bundled plugins**:
+  ```bash
+  total-recall plugin available
+  ```
+- **Search plugins by keyword or use case**:
+  ```bash
+  total-recall plugin search telemetry --use-case monitoring
+  ```
+
+### 2. Install and Link
+- **Install from a local directory (symlink during active development)**:
+  ```bash
+  total-recall plugin install /path/to/my-plugin --link
+  ```
+- **Install globally for all workspaces across the machine**:
+  ```bash
+  total-recall plugin install /path/to/my-plugin --global
+  ```
+- **Install from a remote git repository**:
+  ```bash
+  total-recall plugin install https://github.com/org/plugin-repo.git
+  ```
+- **Install from a mesh peer node**:
+  ```bash
+  total-recall plugin install peer:mac-mini/code-quality
+  ```
+
+### 3. Inspect and Execute
+- **Inspect detailed plugin metadata, hashes, and scheduled task logs**:
+  ```bash
+  total-recall plugin info my-plugin
+  ```
+- **Execute installed plugin commands directly**:
+  ```bash
+  total-recall my-tool status
+  ```
+
+### 4. Share and Distribute
+- **Share a plugin via a verified hash-pinned link**:
+  ```bash
+  total-recall plugin share my-plugin
+  ```
+- **Revoke sharing access**:
+  ```bash
+  total-recall plugin unshare my-plugin
+  ```
+- **Remove or uninstall a plugin**:
+  ```bash
+  total-recall plugin remove my-plugin
+  ```
+
+---
+
+## Authoring Standards Checklist
+
+Before distributing any plugin, confirm each requirement:
+- [ ] `plugin.json` passes validation against `metadata.plugin.schema.json`.
+- [ ] CLI commands exit with code `0` on success and non-zero on failure.
+- [ ] No private secrets, personal user paths, or session tokens exist in the repository.
+- [ ] SSSS data modifications use validated operations rather than raw disk writes.
+- [ ] User interface components utilize design tokens without hardcoded colors.
+- [ ] All written documentation avoids forbidden words and concludes every sentence without a preposition.

package/src/cli/agent.mjs

@@ -23,6 +23,14 @@ Options:
   --detach                  Spawn process detached in background (default: true)
   --name <label>            Assign a human-readable name to the agent session
   --tail <lines>            Number of log lines to inspect (default: 50)
+  --cwd <dir>               Working directory for the agent (on the target node with --node)
+  --tools <list>            Built-in tools for the harness: default (all), none, or e.g. "Bash,Read,WebFetch"
+                            (alias --allow-tools; --no-tools = none). Spawns default to all tools.
+  --setting-sources <list>  Settings layers the harness loads (e.g. local, or user,project)
+
+Auth:
+  Claude Code reads CLAUDE_CODE_OAUTH_TOKEN (from \`claude setup-token\`) from the environment,
+  else from the Total Recall secret store, so SSH/launchd sessions without a login keychain work.
 
 Available Harnesses:
   agy, claude, codex, gemini
@@ -31,11 +39,53 @@ Examples:
   npx total-recall agent list
   npx total-recall agent spawn claude "Refactor src/cli/harness.mjs error handling"
   npx total-recall agent spawn agy "Crawl recent preprints on quantum shuttling" --name "Quantum Scout"
+  npx total-recall agent spawn claude "Run the lead search workflow" --node build-box --cwd '~/code/app'
   npx total-recall agent logs agent-claude-xyz --tail 100
   npx total-recall agent kill agent-claude-xyz
 `);
 }
 
+const SPAWN_VALUE_FLAGS = {
+  '--node': 'targetNode',
+  '-n': 'targetNode',
+  '--name': 'name',
+  '--cwd': 'cwd',
+  '--tools': 'tools',
+  '--allow-tools': 'tools',
+  '--setting-sources': 'settingSources',
+};
+
+/**
+ * Parse `agent spawn` arguments. Option values are consumed with their flag, so
+ * they never leak into the task text; `--tools ""` is a real (empty) value.
+ */
+export function parseSpawnArgs(rest) {
+  const out = { detach: true, isJson: false, name: null, targetNode: null, cwd: undefined, tools: undefined, settingSources: undefined };
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    const eq = arg.startsWith('--') ? arg.indexOf('=') : -1;
+    const flag = eq > 0 ? arg.slice(0, eq) : arg;
+    if (SPAWN_VALUE_FLAGS[flag]) {
+      let value;
+      if (eq > 0) value = arg.slice(eq + 1);
+      else {
+        if (i + 1 >= rest.length) throw new Error(`${flag} requires a value`);
+        value = rest[++i];
+      }
+      out[SPAWN_VALUE_FLAGS[flag]] = value;
+    } else if (arg === '--json') out.isJson = true;
+    else if (arg === '--no-detach') out.detach = false;
+    else if (arg === '--detach') out.detach = true;
+    else if (arg === '--no-tools') out.tools = 'none';
+    else if (arg.startsWith('--')) throw new Error(`Unknown option for agent spawn: ${arg}`);
+    else positional.push(arg);
+  }
+  out.harness = positional[0];
+  out.task = positional.slice(1).join(' ').trim();
+  return out;
+}
+
 export async function run(argv) {
   let args = argv;
   if (Array.isArray(args) && args[0]?.endsWith('node')) {
@@ -79,34 +129,25 @@ export async function run(argv) {
   }
 
   if (command === 'spawn') {
-    let targetNode = null;
-    const filteredRest = [];
-    for (let i = 0; i < rest.length; i++) {
-      if (rest[i] === '--node' || rest[i] === '-n') {
-        targetNode = rest[i + 1];
-        i++;
-      } else {
-        filteredRest.push(rest[i]);
-      }
+    let parsed;
+    try {
+      parsed = parseSpawnArgs(rest);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
     }
-
-    const harness = filteredRest[0];
-    const task = filteredRest.filter(r => !r.startsWith('--')).slice(1).join(' ').trim();
-    const detach = !filteredRest.includes('--no-detach');
-    const isJson = filteredRest.includes('--json');
-    const nameIdx = filteredRest.indexOf('--name');
-    const name = nameIdx !== -1 ? filteredRest[nameIdx + 1] : null;
+    const { harness, task, detach, isJson, name, targetNode, cwd, tools, settingSources } = parsed;
 
     if (!harness || !task) {
       console.error('Error: Please specify harness ID and task prompt.');
-      console.error('Usage: npx total-recall agent spawn <harness> "<task>" [--name "..."] [--node <node>]');
+      console.error('Usage: npx total-recall agent spawn <harness> "<task>" [--name "..."] [--node <node>] [--cwd <dir>] [--tools <list|none|default>]');
       process.exit(1);
     }
 
     const nodeStr = targetNode ? ` on mesh node \x1b[1;33m${targetNode}\x1b[0m` : '';
     if (!isJson) console.log(`\n🚀 Spawning agent on harness: \x1b[1;36m${harness}\x1b[0m${nodeStr}...`);
     try {
-      const record = await spawnAgent(harness, task, { detach, name, node: targetNode });
+      const record = await spawnAgent(harness, task, { detach, name, node: targetNode, cwd, tools, settingSources });
       if (isJson) {
         console.log(JSON.stringify(record, null, 2));
         return;