@vectorize-io/self-driving-agents 0.0.22 → 0.0.24

package/README.md

@@ -37,6 +37,14 @@ npx @vectorize-io/self-driving-agents install ./my-agent --harness claude
 npx @vectorize-io/self-driving-agents install my-org/my-repo/my-agent --harness openclaw
 ```
 
+Or start with a blank agent — no template, no seed content — using `--empty`:
+
+```bash
+npx @vectorize-io/self-driving-agents install my-agent --harness claude-code --empty
+```
+
+The first positional becomes the agent name. The CLI provisions the bank, sets up the harness, and lets you build everything up from the conversation.
+
 ## How it works
 
 1. You chat with the agent

package/dist/cli.d.ts

@@ -14,4 +14,12 @@
  *   bank-template.json   — optional: bank config at this level
  *   *.md, *.txt, ...     — content files (found recursively, excluding bank-template.json)
  */
-export {};
+/**
+ * Whether a string is a valid agent name. Used by --empty mode where the
+ * first positional arg becomes the agent name (no path, no GitHub fetch).
+ *
+ * Rules: starts with [a-z0-9], then lowercase alphanumerics or hyphens, max
+ * 64 chars. Matches the lowercase-with-hyphens convention the create-agent
+ * skill expects.
+ */
+export declare function isValidAgentName(name: string): boolean;

package/dist/cli.js

@@ -50,6 +50,17 @@ function isLocalPath(input) {
         input.startsWith("/") ||
         input.startsWith("~"));
 }
+/**
+ * Whether a string is a valid agent name. Used by --empty mode where the
+ * first positional arg becomes the agent name (no path, no GitHub fetch).
+ *
+ * Rules: starts with [a-z0-9], then lowercase alphanumerics or hyphens, max
+ * 64 chars. Matches the lowercase-with-hyphens convention the create-agent
+ * skill expects.
+ */
+export function isValidAgentName(name) {
+    return /^[a-z0-9][a-z0-9-]*$/.test(name) && name.length <= 64;
+}
 /**
  * Resolve the agent specifier to a local directory.
  *
@@ -713,16 +724,19 @@ async function main() {
   ${color.bold("self-driving-agents")} — install a self-driving agent
 
   ${color.dim("Usage:")}
-    npx @vectorize-io/self-driving-agents install <agent> --harness <harness> [--agent <name>]
+    npx @vectorize-io/self-driving-agents install <agent> --harness <h>          ${color.dim("# from path or GitHub")}
+    npx @vectorize-io/self-driving-agents install <name>  --harness <h> --empty  ${color.dim("# blank agent")}
 
-  ${color.dim("Agent sources:")}
+  ${color.dim("Agent sources (without --empty):")}
     ${color.cyan("marketing-agent")}             → ${DEFAULT_REPO}/marketing-agent
     ${color.cyan("org/repo/my-agent")}           → org/repo/my-agent on GitHub
     ${color.cyan("./local-dir")}                 → local directory
 
   ${color.dim("Options:")}
     ${color.cyan("--harness <h>")}      Required. openclaw | nemoclaw | hermes | claude | claude-code
-    ${color.cyan("--agent <name>")}     Agent name (defaults to directory name)
+    ${color.cyan("--empty")}            Create a blank agent. First positional becomes the agent name;
+                       no content fetched, no bank-template imported from disk.
+    ${color.cyan("--agent <name>")}     Override the agent name (defaults to directory name)
     ${color.cyan("--sandbox <name>")}   NemoClaw sandbox (auto-detected if only one exists)
 `);
         process.exit(0);
@@ -736,6 +750,7 @@ async function main() {
     let harness;
     let agentName;
     let sandbox;
+    let isEmpty = false;
     for (let i = 0; i < restArgs.length; i++) {
         if (restArgs[i] === "--harness" && restArgs[i + 1])
             harness = restArgs[++i];
@@ -743,6 +758,8 @@ async function main() {
             agentName = restArgs[++i];
         else if (restArgs[i] === "--sandbox" && restArgs[i + 1])
             sandbox = restArgs[++i];
+        else if (restArgs[i] === "--empty")
+            isEmpty = true;
     }
     if (!harness) {
         p.cancel("--harness required (openclaw | nemoclaw | hermes | claude | claude-code)");
@@ -752,9 +769,30 @@ async function main() {
         sandbox = await detectNemoClawSandbox();
     }
     p.intro(color.bgCyan(color.black(` self-driving-agents `)));
-    // Step 0: Resolve agent directory (local or GitHub)
+    // Step 0: Resolve agent directory (local or GitHub) — skipped when --empty
+    // is set; in that case the first positional becomes the agent name and
+    // there's no source content to ingest.
     const spin = p.spinner();
-    const { dir, source, defaultName, cleanup } = await resolveAgentDir(dirArg, spin);
+    let dir = "";
+    let source;
+    let defaultName;
+    let cleanup;
+    if (isEmpty) {
+        if (!dirArg || dirArg.startsWith("-")) {
+            p.cancel("--empty needs an agent name as the first positional argument.\n" +
+                "  e.g. install my-agent --harness claude-code --empty");
+            process.exit(1);
+        }
+        if (!isValidAgentName(dirArg)) {
+            p.cancel(`Invalid agent name '${dirArg}'. Use lowercase letters, digits, and hyphens (max 64 chars), e.g. my-agent.`);
+            process.exit(1);
+        }
+        source = "<empty>";
+        defaultName = dirArg;
+    }
+    else {
+        ({ dir, source, defaultName, cleanup } = await resolveAgentDir(dirArg, spin));
+    }
     try {
         let agentId;
         if (agentName) {
@@ -985,25 +1023,32 @@ async function main() {
             ccConfig.dynamicBankId = true;
             ccConfig.dynamicBankGranularity = expectedGranularity;
             ccConfig.enableKnowledgeTools = true;
+            // Coalesce all worktrees of a repo into one bank by resolving the
+            // `project` field to the main repo basename instead of the cwd basename.
+            // Plugin default is already true, but pin it explicitly so future plugin
+            // version flips don't fragment a user's memory across worktrees.
+            ccConfig.resolveWorktrees = true;
             mkdirSync(ccConfigDir, { recursive: true });
             writeFileSync(ccConfigPath, JSON.stringify(ccConfig, null, 2) + "\n");
             p.log.success(`Plugin config: ${color.dim(ccConfigPath)}`);
-            // Step 4: Save content locally for the agent
-            const contentDir = join(homedir(), ".self-driving-agents", "claude-code", agentId);
-            mkdirSync(contentDir, { recursive: true });
-            // Copy content files to the local dir
-            const contentFiles = findContentFiles(dir);
-            for (const relPath of contentFiles) {
-                const destPath = join(contentDir, relPath);
-                mkdirSync(join(destPath, ".."), { recursive: true });
-                writeFileSync(destPath, readFileSync(join(dir, relPath), "utf-8"));
-            }
-            // Copy bank-template.json if present (has mental model definitions)
-            const templateSrc = join(dir, "bank-template.json");
-            if (existsSync(templateSrc)) {
-                writeFileSync(join(contentDir, "bank-template.json"), readFileSync(templateSrc, "utf-8"));
+            // Step 4: Save content locally for the agent (skipped when --empty —
+            // the create-agent skill goes interactive without a `from <path>`).
+            let contentDir = null;
+            if (!isEmpty) {
+                contentDir = join(homedir(), ".self-driving-agents", "claude-code", agentId);
+                mkdirSync(contentDir, { recursive: true });
+                const contentFiles = findContentFiles(dir);
+                for (const relPath of contentFiles) {
+                    const destPath = join(contentDir, relPath);
+                    mkdirSync(join(destPath, ".."), { recursive: true });
+                    writeFileSync(destPath, readFileSync(join(dir, relPath), "utf-8"));
+                }
+                const templateSrc = join(dir, "bank-template.json");
+                if (existsSync(templateSrc)) {
+                    writeFileSync(join(contentDir, "bank-template.json"), readFileSync(templateSrc, "utf-8"));
+                }
+                p.log.success(`Content saved to ${color.dim(contentDir)} (${contentFiles.length} files)`);
             }
-            p.log.success(`Content saved to ${color.dim(contentDir)} (${contentFiles.length} files)`);
             // Auto-approve hindsight MCP tools and skills in user settings
             const userSettingsPath = join(homedir(), ".claude", "settings.json");
             let userSettings = {};
@@ -1036,7 +1081,11 @@ async function main() {
                 writeFileSync(userSettingsPath, JSON.stringify(userSettings, null, 2) + "\n");
                 p.log.success("Auto-approved hindsight tools in Claude Code");
             }
-            const prompt = `/hindsight-memory:create-agent ${agentId} from ${contentDir}`;
+            // With --empty the skill runs interactively (Mode B); otherwise it
+            // ingests from the staged content directory (Mode A).
+            const prompt = contentDir
+                ? `/hindsight-memory:create-agent ${agentId} from ${contentDir}`
+                : `/hindsight-memory:create-agent ${agentId}`;
             p.note([
                 `${color.yellow("⚠")}  ${color.bold(`Important:`)} the agent's memory is scoped to the directory where you start ${color.cyan("claude")}.`,
                 `   Always start your Claude Code sessions from the same project directory.`,
@@ -1084,20 +1133,24 @@ async function main() {
             p.cancel(`Cannot reach Hindsight at ${apiUrl}\nStart the server or reconfigure the plugin.`);
             process.exit(1);
         }
-        // Step 4: Import bank template
-        const templatePath = join(dir, "bank-template.json");
-        if (existsSync(templatePath)) {
-            spin.start("Importing bank template...");
-            const template = JSON.parse(readFileSync(templatePath, "utf-8"));
+        // Step 4: Import bank template — or, with --empty, provision a blank
+        // bank so later writes from the harness have somewhere to land.
+        const templatePath = isEmpty ? "" : join(dir, "bank-template.json");
+        const hasTemplate = !isEmpty && existsSync(templatePath);
+        if (isEmpty || hasTemplate) {
+            spin.start(isEmpty ? "Provisioning bank..." : "Importing bank template...");
+            const template = hasTemplate
+                ? JSON.parse(readFileSync(templatePath, "utf-8"))
+                : { version: "1" };
             await sdk.importBankTemplate({
                 client: lowLevel,
                 path: { bank_id: bankId },
                 body: template,
             });
-            spin.stop("Bank template imported");
+            spin.stop(isEmpty ? "Bank provisioned" : "Bank template imported");
         }
         // Step 5: Ingest content (recursive — all text files except bank-template.json)
-        const contentFiles = findContentFiles(dir);
+        const contentFiles = isEmpty ? [] : findContentFiles(dir);
         if (contentFiles.length > 0) {
             spin.start(`Ingesting ${contentFiles.length} file(s)...`);
             for (const relPath of contentFiles) {

package/dist/tests/cli.test.js

@@ -129,6 +129,94 @@ describe("isLocalPath", () => {
         expect(isLocalPath("marketing/seo")).toBe(false);
     });
 });
+describe("isValidAgentName", () => {
+    // Mirrors the regex in cli.ts. --empty mode validates the first positional
+    // arg (the agent name) against this since there's no path/GitHub fetch to
+    // implicitly sanitize.
+    function isValidAgentName(name) {
+        return /^[a-z0-9][a-z0-9-]*$/.test(name) && name.length <= 64;
+    }
+    it("accepts lowercase with hyphens", () => {
+        expect(isValidAgentName("my-agent")).toBe(true);
+        expect(isValidAgentName("marketing-seo")).toBe(true);
+        expect(isValidAgentName("agent")).toBe(true);
+        expect(isValidAgentName("a1b2c3")).toBe(true);
+    });
+    it("accepts a single character", () => {
+        expect(isValidAgentName("a")).toBe(true);
+        expect(isValidAgentName("0")).toBe(true);
+    });
+    it("rejects uppercase", () => {
+        expect(isValidAgentName("MyAgent")).toBe(false);
+        expect(isValidAgentName("AGENT")).toBe(false);
+    });
+    it("rejects names starting with hyphen", () => {
+        expect(isValidAgentName("-agent")).toBe(false);
+        expect(isValidAgentName("--empty")).toBe(false);
+    });
+    it("rejects empty string", () => {
+        expect(isValidAgentName("")).toBe(false);
+    });
+    it("rejects whitespace", () => {
+        expect(isValidAgentName("my agent")).toBe(false);
+        expect(isValidAgentName(" my-agent")).toBe(false);
+    });
+    it("rejects underscores and other punctuation", () => {
+        expect(isValidAgentName("my_agent")).toBe(false);
+        expect(isValidAgentName("my.agent")).toBe(false);
+        expect(isValidAgentName("my/agent")).toBe(false);
+    });
+    it("rejects names longer than 64 characters", () => {
+        expect(isValidAgentName("a".repeat(64))).toBe(true);
+        expect(isValidAgentName("a".repeat(65))).toBe(false);
+    });
+});
+describe("--empty arg parsing", () => {
+    // Mirrors the loop in main() that walks restArgs to pick out flag values.
+    function parseRestArgs(restArgs) {
+        let harness;
+        let agentName;
+        let sandbox;
+        let isEmpty = false;
+        for (let i = 0; i < restArgs.length; i++) {
+            if (restArgs[i] === "--harness" && restArgs[i + 1])
+                harness = restArgs[++i];
+            else if (restArgs[i] === "--agent" && restArgs[i + 1])
+                agentName = restArgs[++i];
+            else if (restArgs[i] === "--sandbox" && restArgs[i + 1])
+                sandbox = restArgs[++i];
+            else if (restArgs[i] === "--empty")
+                isEmpty = true;
+        }
+        return { harness, agentName, sandbox, isEmpty };
+    }
+    it("picks up --empty as a boolean", () => {
+        expect(parseRestArgs(["--harness", "claude-code", "--empty"]).isEmpty).toBe(true);
+        expect(parseRestArgs(["--harness", "claude-code"]).isEmpty).toBe(false);
+    });
+    it("--empty does not consume the next argument", () => {
+        const r = parseRestArgs(["--empty", "--harness", "claude-code"]);
+        expect(r.isEmpty).toBe(true);
+        expect(r.harness).toBe("claude-code");
+    });
+    it("works alongside --harness, --agent, --sandbox", () => {
+        const r = parseRestArgs([
+            "--harness",
+            "nemoclaw",
+            "--empty",
+            "--agent",
+            "my-agent",
+            "--sandbox",
+            "default",
+        ]);
+        expect(r).toEqual({
+            harness: "nemoclaw",
+            agentName: "my-agent",
+            sandbox: "default",
+            isEmpty: true,
+        });
+    });
+});
 describe("deriveDefaultName", () => {
     // Mirrors the logic in resolveAgentDir:
     // - GitHub refs: subpath with / → hyphens (marketing/seo → marketing-seo)
@@ -695,6 +783,9 @@ describe("claude-code Hindsight config persistence", () => {
             hindsightApiUrl: prompted.apiUrl,
             hindsightApiToken: prompted.apiToken,
             enableKnowledgeTools: true,
+            // Pin worktree resolution so all worktrees of a repo land in the same
+            // bank, matching what cli.ts writes during the claude-code install flow.
+            resolveWorktrees: true,
         };
     }
     it("prompts on first install (empty config)", () => {
@@ -726,4 +817,12 @@ describe("claude-code Hindsight config persistence", () => {
         const result = applyClaudeConfig({ enableKnowledgeTools: false }, { apiUrl: "https://x.com", apiToken: "t" });
         expect(result.enableKnowledgeTools).toBe(true);
     });
+    it("always pins resolveWorktrees=true so worktrees share one bank", () => {
+        // Plugin already defaults to true, but SDA pins it explicitly so a future
+        // plugin default flip can't fragment a user's memory across worktrees.
+        const fresh = applyClaudeConfig({}, { apiUrl: "https://x.com", apiToken: "t" });
+        expect(fresh.resolveWorktrees).toBe(true);
+        const overridden = applyClaudeConfig({ resolveWorktrees: false }, { apiUrl: "https://x.com", apiToken: "t" });
+        expect(overridden.resolveWorktrees).toBe(true);
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectorize-io/self-driving-agents",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "Install self-driving agents with portable memory on any harness",
   "type": "module",
   "main": "dist/cli.js",