@kybernesis/create 0.7.2 → 0.7.3

package/dist/arcana.d.ts

@@ -0,0 +1,8 @@
+export interface ArcanaSetup {
+    dir: string;
+    /** Proposed workspace prefix — the agent's name. Only a suggestion. */
+    suggest: string;
+    /** Department subagents, each of which gets its own brain. */
+    depts?: string[];
+}
+export declare function configureArcana({ dir, suggest, depts }: ArcanaSetup): Promise<void>;

package/dist/arcana.js

@@ -0,0 +1,99 @@
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ask, bold, dim, green, red, yellow } from "./util.js";
+/**
+ * Collect the memory workspaces and their keys, and check them before moving on.
+ *
+ * This exists because the registry item's `envVars` only APPENDS blank names to
+ * .env.local — nothing ever asked for a value. So a scaffold finished looking
+ * complete, with an agent whose memory could not work, and the first sign of it
+ * was an agent that had lost its mind at runtime.
+ *
+ * It also stops guessing the workspace names. `<agent>-company` is a
+ * convention, not a fact: a workspace with that name may already exist for
+ * something else, or the client may have named theirs differently years ago.
+ * The scaffolder proposes; the person deploying decides.
+ */
+const API = "https://api.arcana.kybernesis.ai";
+/** Read a key/workspace pair the way the agent will: read-only, one call. */
+async function check(workspace, key) {
+    try {
+        const res = await fetch(`${API}/brain/${encodeURIComponent(workspace)}/timeline?limit=1`, {
+            headers: { authorization: `Bearer ${key}`, "X-Kyberagent-Agent": workspace },
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (res.ok)
+            return "ok";
+        // 403 is the one that matters: keys are workspace-scoped, and a key for the
+        // wrong brain is the single most common way this is set up wrong.
+        return res.status === 401 || res.status === 403 ? "forbidden" : "unreachable";
+    }
+    catch {
+        return "unreachable";
+    }
+}
+function upsertEnv(dir, values) {
+    const p = join(dir, ".env.local");
+    let text = existsSync(p) ? readFileSync(p, "utf8") : "";
+    for (const [k, v] of Object.entries(values)) {
+        if (!v)
+            continue;
+        const line = `${k}="${v}"`;
+        const re = new RegExp(`^${k}=.*$`, "m");
+        if (re.test(text))
+            text = text.replace(re, line);
+        else
+            text += (text.endsWith("\n") || text === "" ? "" : "\n") + line + "\n";
+    }
+    if (existsSync(p))
+        writeFileSync(p, text);
+    else
+        appendFileSync(p, text);
+}
+export async function configureArcana({ dir, suggest, depts = [] }) {
+    console.log(bold("\n     Memory (Arcana) — workspaces and keys"));
+    console.log(dim("     Create these at https://arcana.kybernesis.ai and mint a scoped kb_ key\n" +
+        "     for each. Names are yours — the suggestions are only a convention."));
+    const values = {};
+    let anyBad = false;
+    const pair = async (label, workspaceVar, keyVar, proposed) => {
+        const workspace = await ask(`     ${label} workspace?`, proposed);
+        const key = await ask(`     ${label} key (kb_…, empty to skip)?`, "");
+        if (!key) {
+            console.log(yellow(`       skipped — ${keyVar} left unset`));
+            values[workspaceVar] = workspace;
+            return;
+        }
+        const state = await check(workspace, key);
+        if (state === "ok")
+            console.log(green(`       ✓ ${workspace} reachable`));
+        else if (state === "forbidden") {
+            anyBad = true;
+            console.log(red(`       ✗ that key is not valid for "${workspace}" (keys are workspace-scoped)`));
+        }
+        else {
+            console.log(yellow(`       ! could not reach Arcana to check — saved anyway`));
+        }
+        values[workspaceVar] = workspace;
+        values[keyVar] = key;
+    };
+    await pair("Company", "ARCANA_COMPANY_WORKSPACE", "ARCANA_API_KEY", `${suggest}-company`);
+    // The eval script the scaffolder writes REQUIRES this one; leaving it to a
+    // template comment is how `npm run eval` fails on a fresh, correct install.
+    await pair("Eval", "ARCANA_EVAL_API_KEY_WORKSPACE", "ARCANA_EVAL_API_KEY", `${suggest}-eval`);
+    // The eval workspace name itself is derived by the npm script, so only the
+    // key is stored; drop the placeholder we used to prompt with.
+    delete values.ARCANA_EVAL_API_KEY_WORKSPACE;
+    for (const dept of depts) {
+        await pair(`Subagent "${dept}"`, `ARCANA_${dept.toUpperCase()}_WORKSPACE`, `ARCANA_${dept.toUpperCase()}_API_KEY`, `${suggest}-${dept}`);
+    }
+    // DM sessions default to the company brain unless the deployment splits them.
+    if (values.ARCANA_COMPANY_WORKSPACE) {
+        values.ARCANA_DM_WORKSPACE ??= values.ARCANA_COMPANY_WORKSPACE;
+    }
+    upsertEnv(dir, values);
+    console.log(dim("     written to .env.local"));
+    if (anyBad) {
+        console.log(yellow("     Fix the mismatched pair and re-run `kyb arcana` — `kyb doctor` checks them too."));
+    }
+}

package/dist/cli.js

@@ -6,6 +6,7 @@
  *                         self-testing eve agent (also: npm create @kybernesis)
  *   kyb doctor            preflight an agent project: keys, issuer, envs, discovery
  *   kyb skills [--global] install/refresh the FDE Claude Code skill suite
+ *   kyb arcana            set memory workspaces + keys, and verify them
  *   kyb register          register this agent with the control plane (device flow)
  *   kyb deploy            put this repo on its host and restart it, with proof
  *   kyb upgrade           bump @kybernesis/* to latest, gated on the eval suite
@@ -18,6 +19,7 @@ import { upgrade } from "./upgrade.js";
 import { installSkills } from "./skills.js";
 import { deploy } from "./deploy.js";
 import { register } from "./register.js";
+import { configureArcana } from "./arcana.js";
 function flag(rest, key) {
     const hit = rest.find((a) => a.startsWith(`--${key}=`));
     return hit ? hit.slice(key.length + 3) : undefined;
@@ -44,6 +46,9 @@ switch (command) {
     case "skills":
         installSkills({ global: rest.includes("--global") });
         break;
+    case "arcana":
+        await configureArcana({ dir: process.cwd(), suggest: flag(rest, "name") ?? "agent" });
+        break;
     case "register":
         await register({ name: flag(rest, "name"), url: flag(rest, "url") });
         break;
@@ -75,6 +80,7 @@ ${bold("kyb")} — Kybernesis agent scaffolder & FDE toolkit
   ${bold("kyb doctor")}          preflight checks (keys, issuer, envs, discovery)
   ${bold("kyb skills")}          install/refresh the FDE skill suite for Claude Code
       --global          ${dim("install to ~/.claude/skills instead of this repo")}
+  ${bold("kyb arcana")}          set memory workspaces + keys, and verify each pair
   ${bold("kyb register")}        register this agent with the control plane
       --name=<name>     ${dim("defaults to KYBERNESIS_AGENT in .env.local")}
       --url=<url>       ${dim("defaults to https://$EXE_VM_NAME.exe.xyz")}

package/dist/init.js

@@ -3,6 +3,7 @@ import { join, resolve } from "node:path";
 import { DEFAULT_ISSUER, EVE_VERSION, REGISTRY_URL, ask, bold, closePrompts, dim, green, run, slug, yellow, } from "./util.js";
 import { CHANNEL_KINDS, channelPlan, engineerPlan, envExample, evalFileTs, evalScript, hostAgentTs, hostSteps, identityMd, rootArcanaTs, subagentAgentTs, subagentArcanaTs, subagentInstructionsMd, } from "./templates.js";
 import { suiteDir } from "./skills.js";
+import { configureArcana } from "./arcana.js";
 /**
  * The always-installed core. Everything else — channels, subagents, engineer,
  * host bindings — is opt-in, because assuming them means the FDE deletes files
@@ -111,6 +112,11 @@ export async function init(rawName, options = {}) {
     writeFileSync(join(dir, "agent/agent.ts"), hostAgentTs(host, DEFAULT_MODEL));
     writeFileSync(join(dir, "agent/extensions/arcana.ts"), rootArcanaTs());
     writeFileSync(join(dir, "evals/kybernesis.eval.ts"), evalFileTs(displayName, depts));
+    // Ask for the memory keys HERE, while the person is still standing in the
+    // scaffold — not in a printed next-step they will read after the context has
+    // gone. Skipped with --yes, which is for CI and takes no input by design.
+    if (!options.yes)
+        await configureArcana({ dir, suggest: name, depts });
     /**
      * A self-hosted agent gets its restart script installed, not described.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "The Kybernesis agent scaffolder and FDE toolkit: one command to a governed, remembering, multiplayer, self-testing eve agent — plus doctor and upgrade.",
   "license": "Apache-2.0",
   "type": "module",