@vectorize-io/self-driving-agents 0.0.23 → 0.0.26

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.
  *
@@ -649,7 +660,9 @@ curl -s -X POST ${apiUrl}/v1/default/banks/${bankId}/memories/retain \\
     execSync(`cd "${outDir}" && zip -j "${zipPath}" SKILL.md`, { stdio: "pipe" });
     return zipPath;
 }
-async function promptClaudeConfig(agentId, opts = { askBankId: true }) {
+async function promptClaudeConfig(agentId, opts = {}) {
+    const askBankId = opts.askBankId ?? true;
+    const allowLocalhost = opts.allowLocalhost ?? false;
     const deploymentType = await p.select({
         message: "Hindsight deployment:",
         options: [
@@ -668,11 +681,14 @@ async function promptClaudeConfig(agentId, opts = { askBankId: true }) {
     else {
         const urlInput = await p.text({
             message: "Hindsight API URL:",
-            placeholder: "https://your-hindsight.example.com",
+            placeholder: allowLocalhost
+                ? "http://localhost:9077 or https://your-hindsight.example.com"
+                : "https://your-hindsight.example.com",
             validate: (val) => {
                 if (!val)
                     return "URL is required";
-                if (val.startsWith("http://localhost") || val.startsWith("http://127.0.0.1")) {
+                if (!allowLocalhost &&
+                    (val.startsWith("http://localhost") || val.startsWith("http://127.0.0.1"))) {
                     return "Claude cannot reach localhost. Use a publicly accessible URL.";
                 }
                 return undefined;
@@ -683,7 +699,9 @@ async function promptClaudeConfig(agentId, opts = { askBankId: true }) {
             process.exit(0);
         }
         apiUrl = urlInput;
-        p.log.warn("Make sure your Hindsight instance is publicly accessible from Claude's servers.");
+        if (!allowLocalhost) {
+            p.log.warn("Make sure your Hindsight instance is publicly accessible from Claude's servers.");
+        }
     }
     const tokenInput = await p.password({ message: "Hindsight API token:" });
     if (p.isCancel(tokenInput)) {
@@ -692,7 +710,7 @@ async function promptClaudeConfig(agentId, opts = { askBankId: true }) {
     }
     const apiToken = tokenInput || undefined;
     let bankId = agentId;
-    if (opts.askBankId) {
+    if (askBankId) {
         const bankInput = await p.text({
             message: "Bank ID:",
             initialValue: agentId,
@@ -713,16 +731,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 +757,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 +765,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 +776,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) {
@@ -954,9 +999,29 @@ async function main() {
                 catch { /* ignore */ }
             }
             const hasConnection = ccConfig.hindsightApiUrl || ccConfig.llmProvider;
-            if (!hasConnection && process.stdin.isTTY) {
+            let reconfigure = !hasConnection;
+            if (hasConnection && process.stdin.isTTY) {
+                const summary = ccConfig.hindsightApiUrl === HINDSIGHT_CLOUD_API_URL
+                    ? "Cloud (api.hindsight.vectorize.io)"
+                    : ccConfig.hindsightApiUrl
+                        ? `External: ${ccConfig.hindsightApiUrl}`
+                        : `LLM provider: ${ccConfig.llmProvider}`;
+                const ok = await p.confirm({
+                    message: `Hindsight: ${color.cyan(summary)}. Use this?\n${color.dim("  Changing this will affect all existing Claude Code agents — one Claude Code install shares a single Hindsight connection.")}`,
+                });
+                if (p.isCancel(ok)) {
+                    p.cancel("Cancelled.");
+                    process.exit(0);
+                }
+                if (!ok)
+                    reconfigure = true;
+            }
+            if (reconfigure && process.stdin.isTTY) {
                 // Bank ID is derived from agent + cwd at runtime — don't ask for it
-                const claudeConfig = await promptClaudeConfig(agentId, { askBankId: false });
+                const claudeConfig = await promptClaudeConfig(agentId, {
+                    askBankId: false,
+                    allowLocalhost: true,
+                });
                 ccConfig.hindsightApiUrl = claudeConfig.apiUrl;
                 ccConfig.hindsightApiToken = claudeConfig.apiToken;
             }
@@ -993,22 +1058,24 @@ async function main() {
             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 = {};
@@ -1041,7 +1108,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.`,
@@ -1089,20 +1160,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/skill/SKILL.md

@@ -41,7 +41,9 @@ Use when pages don't cover what you need.
 
 ## Ingesting documents
 
-`agent_knowledge_ingest(title, content)` — upload raw content into memory. Never summarize before ingesting. Save large content to a file first, read it, then pass the full text.
+`agent_knowledge_ingest(title, content)` — upload raw content into memory. Never summarize before ingesting. Pass the full text inline.
+
+`agent_knowledge_ingest_files(paths)` — ingest one or more files straight from disk. `paths` is a list of file paths or glob patterns (e.g. `["docs/**/*.md", "/abs/path/notes.txt"]`). Each file's content is read and stored under a document ID derived from its path. Prefer this over `agent_knowledge_ingest` when the content already lives in files — no need to read them first. Use absolute paths when in doubt; relative paths resolve against the working directory.
 
 ## Updating and deleting
 

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)

package/dist/tests/lint.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/lint.test.js

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "fs";
+import { tmpdir } from "os";
+import { join, resolve } from "path";
+// @ts-expect-error - .mjs has no type declarations; runtime import is fine
+import { findBankTemplates, lintBankTemplate, lintAll } from "../scripts/lint-bank-templates.mjs";
+const REPO_ROOT = resolve(__dirname, "..", "..");
+describe("lint-bank-templates", () => {
+    let dir;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), "sda-lint-"));
+    });
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("accepts a valid template (observations_mission + >=1 mental_models, no reflect_mission)", () => {
+        const file = join(dir, "bank-template.json");
+        writeFileSync(file, JSON.stringify({
+            version: "1",
+            bank: { observations_mission: "watch X" },
+            mental_models: [{ id: "a", name: "A" }],
+        }));
+        expect(lintBankTemplate(file)).toEqual([]);
+    });
+    it("rejects missing observations_mission", () => {
+        const file = join(dir, "bank-template.json");
+        writeFileSync(file, JSON.stringify({ bank: {}, mental_models: [{ id: "a", name: "A" }] }));
+        const errs = lintBankTemplate(file);
+        expect(errs.some((e) => e.includes("observations_mission"))).toBe(true);
+    });
+    it("rejects empty observations_mission", () => {
+        const file = join(dir, "bank-template.json");
+        writeFileSync(file, JSON.stringify({
+            bank: { observations_mission: "   " },
+            mental_models: [{ id: "a", name: "A" }],
+        }));
+        const errs = lintBankTemplate(file);
+        expect(errs.some((e) => e.includes("observations_mission"))).toBe(true);
+    });
+    it("rejects empty mental_models", () => {
+        const file = join(dir, "bank-template.json");
+        writeFileSync(file, JSON.stringify({
+            bank: { observations_mission: "watch X" },
+            mental_models: [],
+        }));
+        const errs = lintBankTemplate(file);
+        expect(errs.some((e) => e.includes("mental_models"))).toBe(true);
+    });
+    it("rejects missing mental_models entirely", () => {
+        const file = join(dir, "bank-template.json");
+        writeFileSync(file, JSON.stringify({ bank: { observations_mission: "watch X" } }));
+        const errs = lintBankTemplate(file);
+        expect(errs.some((e) => e.includes("mental_models"))).toBe(true);
+    });
+    it("rejects deprecated reflect_mission", () => {
+        const file = join(dir, "bank-template.json");
+        writeFileSync(file, JSON.stringify({
+            bank: { observations_mission: "watch X", reflect_mission: "old" },
+            mental_models: [{ id: "a", name: "A" }],
+        }));
+        const errs = lintBankTemplate(file);
+        expect(errs.some((e) => e.includes("reflect_mission"))).toBe(true);
+    });
+    it("rejects invalid JSON", () => {
+        const file = join(dir, "bank-template.json");
+        writeFileSync(file, "{ not json");
+        const errs = lintBankTemplate(file);
+        expect(errs.some((e) => e.toLowerCase().includes("json"))).toBe(true);
+    });
+    it("findBankTemplates walks recursively and skips node_modules", () => {
+        mkdirSync(join(dir, "a", "b"), { recursive: true });
+        mkdirSync(join(dir, "node_modules", "x"), { recursive: true });
+        writeFileSync(join(dir, "bank-template.json"), "{}");
+        writeFileSync(join(dir, "a", "bank-template.json"), "{}");
+        writeFileSync(join(dir, "a", "b", "bank-template.json"), "{}");
+        writeFileSync(join(dir, "node_modules", "x", "bank-template.json"), "{}");
+        const found = findBankTemplates(dir);
+        expect(found).toHaveLength(3);
+        expect(found.every((f) => !f.includes("node_modules"))).toBe(true);
+    });
+    it("the actual repo passes lint", () => {
+        const issues = lintAll(REPO_ROOT);
+        expect(issues).toEqual([]);
+    });
+});