@kybernesis/create 0.7.3 → 0.7.8

package/dist/cli.js

@@ -53,7 +53,7 @@ switch (command) {
         await register({ name: flag(rest, "name"), url: flag(rest, "url") });
         break;
     case "deploy":
-        await deploy({ host: flag(rest, "host") });
+        await deploy({ host: flag(rest, "host"), noEnv: rest.includes("--no-env") });
         break;
     case "upgrade":
         await upgrade(rest.includes("--skip-eval"));
@@ -86,6 +86,7 @@ ${bold("kyb")} — Kybernesis agent scaffolder & FDE toolkit
       --url=<url>       ${dim("defaults to https://$EXE_VM_NAME.exe.xyz")}
   ${bold("kyb deploy")}          copy to the host, install, restart, prove it took
       --host=<target>   ${dim("ssh target; defaults to $EXE_VM_NAME.exe.xyz")}
+      --no-env          ${dim("do not send .env.local (host manages its own secrets)")}
   ${bold("kyb upgrade")}         bump @kybernesis/* packages, gated on evals
       --skip-eval       ${dim("skip the eval gate")}
 

package/dist/deploy.d.ts

@@ -1,4 +1,5 @@
 export declare function deploy(options: {
     host?: string;
     dir?: string;
+    noEnv?: boolean;
 }): Promise<void>;

package/dist/deploy.js

@@ -77,11 +77,14 @@ export async function deploy(options) {
      * not run on the host. `.eve` is the durable store — conversations, turn
      * history, the workflow queue — and overwriting it with a local copy is how
      * a deployment eats its own production state.
+     *
+     * `.env.local` is excluded from the SOURCE sync and sent separately below.
+     * It is not source: rsync --delete would remove a host-only file, and a
+     * half-matching copy is worse than a deliberate one.
      */
-    console.log(bold("1/3  Copying source …"));
+    console.log(bold("1/4  Copying source …"));
     const ok = run("rsync", [
         "-az",
-        "--delete",
         "--exclude",
         "node_modules",
         "--exclude",
@@ -100,7 +103,50 @@ export async function deploy(options) {
         process.exitCode = 1;
         return;
     }
-    console.log(bold("\n2/3  Installing dependencies on the host …"));
+    /**
+     * The agent cannot boot without its environment.
+     *
+     * This step was missing, and the failure was exactly as opaque as it sounds:
+     * source copied, dependencies installed, build succeeded, and the server died
+     * on `Invalid extension config: apiKey: expected string, received undefined`
+     * — an error about a mount, thirty lines into a log, when the actual cause
+     * was that no configuration had ever reached the machine.
+     *
+     * Sent separately from the source sync so `--delete` cannot touch it, and
+     * skippable for deployments whose secrets are managed on the host.
+     */
+    if (!options.noEnv) {
+        const envFile = join(dir, ".env.local");
+        if (existsSync(envFile)) {
+            console.log(bold("\n2/4  Environment …"));
+            /**
+             * Only when the host has none.
+             *
+             * The host's copy is authoritative: it holds credentials minted ON the
+             * host, values a laptop never had, and secrets nobody keeps in a working
+             * tree. A local stub overwriting it does not misconfigure a deployment,
+             * it destroys one — that happened here, to a production agent, and
+             * `rsync --delete` took the backup with it in the same run.
+             */
+            const hasRemote = spawnSync("ssh", [target, `test -s ${remote}/.env.local`]).status === 0;
+            if (hasRemote) {
+                console.log(dim("  host has its own — left untouched"));
+            }
+            else if (!run("scp", ["-q", envFile, `${target}:${remote}/.env.local`])) {
+                console.log(red("  Could not copy .env.local — the agent will not start without it."));
+                process.exitCode = 1;
+                return;
+            }
+            else {
+                console.log(dim("  sent (host had none)"));
+            }
+        }
+        else {
+            console.log(yellow("\n  ! No .env.local here. The host needs one, or the agent will fail to boot\n" +
+                "    on the first config it dereferences. Run kyb arcana, or create it there."));
+        }
+    }
+    console.log(bold("\n3/4  Installing dependencies on the host …"));
     if (!run("ssh", [target, `cd ${remote} && npm install --no-audit --no-fund`])) {
         console.log(red("  npm install failed on the host."));
         process.exitCode = 1;
@@ -114,7 +160,7 @@ export async function deploy(options) {
      * exists to prevent. setsid + nohup + no stdin is the difference between a
      * deploy and an outage.
      */
-    console.log(bold("\n3/3  Restarting (detached) …"));
+    console.log(bold("\n4/4  Restarting (detached) …"));
     /**
      * Find the restart script rather than assuming its name.
      *

package/dist/envfile.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Set values in a project's .env.local, replacing in place.
+ *
+ * Its own module because two commands need it and both were getting it wrong
+ * in the same way: a registry item's `envVars` only appends NAMES, so a
+ * scaffold could finish with `KYBERNESIS_AGENT=` empty and every later command
+ * reading it would report the value as missing — which reads as a step the
+ * person skipped rather than one they were never offered.
+ */
+export declare function upsertEnv(dir: string, values: Record<string, string>): void;

package/dist/envfile.js

@@ -0,0 +1,30 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Set values in a project's .env.local, replacing in place.
+ *
+ * Its own module because two commands need it and both were getting it wrong
+ * in the same way: a registry item's `envVars` only appends NAMES, so a
+ * scaffold could finish with `KYBERNESIS_AGENT=` empty and every later command
+ * reading it would report the value as missing — which reads as a step the
+ * person skipped rather than one they were never offered.
+ */
+export function upsertEnv(dir, values) {
+    const path = join(dir, ".env.local");
+    let text = existsSync(path) ? readFileSync(path, "utf8") : "";
+    for (const [key, value] of Object.entries(values)) {
+        const line = `${key}="${value}"`;
+        const existing = new RegExp(`^${key}=.*$`, "m");
+        if (existing.test(text)) {
+            // A function replacer, never a string: `$&` and `` $` `` are special in a
+            // replacement string, and a value containing either silently splices in
+            // part of the file. That has happened twice, and both times it produced
+            // a file that looked plausible and did not parse.
+            text = text.replace(existing, () => line);
+        }
+        else {
+            text += (text.endsWith("\n") || text === "" ? "" : "\n") + line + "\n";
+        }
+    }
+    writeFileSync(path, text);
+}

package/dist/init.js

@@ -1,9 +1,10 @@
 import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 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 { CHANNEL_KINDS, channelPlan, engineerPlan, envExample, evalFileTs, exeEvalConfigTs, evalScript, hostAgentTs, hostSteps, identityMd, rootArcanaTs, subagentAgentTs, subagentArcanaTs, subagentInstructionsMd, } from "./templates.js";
 import { suiteDir } from "./skills.js";
 import { configureArcana } from "./arcana.js";
+import { upsertEnv } from "./envfile.js";
 /**
  * The always-installed core. Everything else — channels, subagents, engineer,
  * host bindings — is opt-in, because assuming them means the FDE deletes files
@@ -64,7 +65,12 @@ export async function init(rawName, options = {}) {
     for (const item of CORE_ITEMS) {
         run("npx", ["eve", "add", `@kybernesis/${item}`, "--overwrite"], { cwd: dir });
     }
-    const extraDeps = [...plan.deps, ...(host === "exe" ? ["@kybernesis/exe", "@ai-sdk/openai"] : [])];
+    // @ai-sdk/anthropic is for the EVAL JUDGE, not the agent: an agent judged
+    // by the model it runs on is a weak test.
+    const extraDeps = [
+        ...plan.deps,
+        ...(host === "exe" ? ["@kybernesis/exe", "@ai-sdk/openai", "@ai-sdk/anthropic"] : []),
+    ];
     if (extraDeps.length) {
         console.log(bold(`\n2b   Installing for ${channel}/${host}: ${extraDeps.join(", ")} …`));
         run("npm", ["install", ...extraDeps, "--no-audit", "--no-fund"], { cwd: dir, allowFail: true });
@@ -78,10 +84,28 @@ export async function init(rawName, options = {}) {
         // client change THIS AGENT — its dependencies and its source. Different
         // blast radius, so an agent can have one without the other.
         console.log(bold("\n2b2  KYBER Studio: local execution + management routes …"));
+        const studioFailures = [];
         for (const item of ["local", "manage"]) {
-            const ok = run("npx", ["eve", "add", item, "--overwrite"], { cwd: dir, allowFail: true });
-            if (!ok)
-                console.log(yellow(`  ! ${item} did not install cleanly — re-run: npx eve add ${item}`));
+            // The @kybernesis/ prefix is load-bearing: a bare name resolves against
+            // eve OWN registry, which has no such item, so both installs failed with
+            // "not found" — and allowFail swallowed it. --studio therefore did
+            // nothing at all, silently, and the first sign was Studio refusing to
+            // connect an agent that looked correctly scaffolded.
+            const ok = run("npx", ["eve", "add", `@kybernesis/${item}`, "--overwrite"], {
+                cwd: dir,
+                allowFail: true,
+            });
+            if (!ok) {
+                studioFailures.push(item);
+                console.log(yellow(`  ! ${item} did not install — re-run: npx eve add @kybernesis/${item}`));
+            }
+        }
+        // Said again, loudly, at the end. A warning printed sixty lines before a
+        // green summary is a warning nobody reads — and the agent that results
+        // looks correctly scaffolded right up until KYBER Studio refuses it.
+        if (studioFailures.length) {
+            console.log(yellow(`\n  ! --studio did NOT complete: ${studioFailures.join(", ")} missing.\n` +
+                `    This agent cannot be connected to a desktop until they install.`));
         }
     }
     const engPlan = engineer ? engineerPlan(host, DEFAULT_MODEL) : null;
@@ -112,9 +136,38 @@ 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));
+    // A self-hosted agent judges through its own integration; the default
+    // resolves through a gateway it has no key for, and only the judged gates
+    // fail — which reads as a half-broken agent rather than a missing config.
+    if (host === "exe")
+        writeFileSync(join(dir, "evals/evals.config.ts"), exeEvalConfigTs());
     // 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.
+    /**
+     * Write the values this command already knows.
+     *
+     * These were left blank, so the first thing a person met after a clean
+     * scaffold was `kyb register` reporting "No agent name" — a step they were
+     * never offered, reading as one they had skipped.
+     */
+    const known = { KYBERNESIS_ISSUER: issuer, KYBERNESIS_AGENT: name };
+    if (host === "exe") {
+        // Usually the agent's name, and usually not. Everything downstream — the
+        // deploy target, the registered URL — derives from this one value.
+        known.EXE_VM_NAME = options.yes ? name : await ask("exe.dev VM name?", name);
+        /**
+         * Left empty on purpose rather than guessed.
+         *
+         * Model ids are per-integration and carry a provider prefix. A hardcoded
+         * default put one host's id on another, where an unknown id answers
+         * `404 unsupported endpoint` — an error about the endpoint for a problem
+         * with the model. Empty fails honestly; the host lists its own with
+         * curl https://llm.int.exe.xyz/models.json
+         */
+        known.EXE_MODEL = "";
+    }
+    upsertEnv(dir, known);
     if (!options.yes)
         await configureArcana({ dir, suggest: name, depts });
     /**

package/dist/templates.d.ts

@@ -37,3 +37,16 @@ export interface EngineerPlan {
     steps: string[];
 }
 export declare function engineerPlan(host: HostKind, model: string): EngineerPlan;
+/**
+ * The eval judge, for an exe.dev host.
+ *
+ * Without this the judge resolves through Vercel's AI Gateway and fails with
+ * "Unauthenticated request to AI Gateway" on a host that has no gateway key
+ * and does not need one — the agent passes every gate the judge is not part
+ * of, which reads as a half-broken agent rather than a missing config.
+ *
+ * Judged by a DIFFERENT provider from the one under test. A model grading its
+ * own output is a weak test, and the Anthropic path is a plain Messages
+ * endpoint, so none of the subscription backend's constraints apply.
+ */
+export declare function exeEvalConfigTs(): string;

package/dist/templates.js

@@ -69,7 +69,15 @@ export function subagentArcanaTs(dept) {
     const upper = dept.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
     return `import { defineMcpClientConnection } from "eve/connections";
 
-const workspace = process.env.ARCANA_${upper}_WORKSPACE ?? "REPLACE-${dept}";
+// Same reasoning as the root brain: no placeholder. A subagent quietly
+// addressing a workspace nobody owns is amnesia that looks like a model
+// problem rather than a missing value. Set it with \`kyb arcana\`.
+const workspace = process.env.ARCANA_${upper}_WORKSPACE;
+if (!workspace) {
+  throw new Error(
+    "ARCANA_${upper}_WORKSPACE is not set — run \`kyb arcana\` to set this subagent workspace and key.",
+  );
+}
 
 export default defineMcpClientConnection({
   url: "https://mcp.arcana.kybernesis.ai/mcp",
@@ -97,7 +105,16 @@ export function rootArcanaTs() {
 // One brain for shared surfaces, optionally a second for DMs. Hermetic eval
 // runs override ARCANA_COMPANY_WORKSPACE to "<client>-eval", which switches
 // to the eval workspace's own key automatically.
-const COMPANY = process.env.ARCANA_COMPANY_WORKSPACE ?? "REPLACE-company";
+// No placeholder fallback. A default here does not prevent a mistake, it
+// hides one: memory silently addresses a workspace nobody owns, and the agent
+// looks like it has amnesia rather than like it is misconfigured. Set with
+// \`kyb arcana\`.
+const COMPANY = process.env.ARCANA_COMPANY_WORKSPACE;
+if (!COMPANY) {
+  throw new Error(
+    "ARCANA_COMPANY_WORKSPACE is not set — run \`kyb arcana\` to set the workspace and its key.",
+  );
+}
 const DM = process.env.ARCANA_DM_WORKSPACE ?? COMPANY;
 
 export default arcana({
@@ -501,8 +518,13 @@ export default defineAgent({
         {
             path: "agent/subagents/builder/extensions/engineer.ts",
             content: `// Engineer layer mounted LOCALLY on this subagent (eve >=0.30): screenshot,
-// deliver, and the trade-school skills belong to \`builder\` alone. The root
-// agent never gets shell or a browser.
+// deliver, and the trade-school skills belong to \`builder\` alone, so the root
+// agent has no shell.
+//
+// The root DOES get a browser and GitHub tools — the engineer layer installs
+// extension/agent-browser and extension/github-tools at the root, deliberately,
+// because reading a page is not the same blast radius as running a command.
+// This comment used to claim otherwise, which is worse than saying nothing.
 export { default } from "@kybernesis/engineer";
 `,
         },
@@ -534,3 +556,33 @@ export { default } from "@kybernesis/engineer";
             ],
     };
 }
+/**
+ * The eval judge, for an exe.dev host.
+ *
+ * Without this the judge resolves through Vercel's AI Gateway and fails with
+ * "Unauthenticated request to AI Gateway" on a host that has no gateway key
+ * and does not need one — the agent passes every gate the judge is not part
+ * of, which reads as a half-broken agent rather than a missing config.
+ *
+ * Judged by a DIFFERENT provider from the one under test. A model grading its
+ * own output is a weak test, and the Anthropic path is a plain Messages
+ * endpoint, so none of the subscription backend's constraints apply.
+ */
+export function exeEvalConfigTs() {
+    return `import { defineEvalConfig } from "eve/evals";
+import { createAnthropic } from "@ai-sdk/anthropic";
+
+const exe = createAnthropic({
+  baseURL: process.env.EXE_LLM_URL ?? "https://llm.int.exe.xyz/v1",
+  apiKey: "exe-integration",
+});
+
+export default defineEvalConfig({
+  // A different provider from the agent under test, on purpose.
+  judge: { model: exe(process.env.EXE_JUDGE_MODEL ?? "claude-sonnet-4-6") },
+  // Real model and real memory on every turn: generous timeout, gentle concurrency.
+  timeoutMs: 300_000,
+  maxConcurrency: 1,
+});
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.7.3",
+  "version": "0.7.8",
   "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",

package/skills/self-hosting/SKILL.md

@@ -88,6 +88,25 @@ What this arrangement costs you, and it is worth saying to the client:
 
 ## The failure modes, each of which cost a real session
 
+- **`EXE_MODEL` is deliberately empty after `kyb init`.** Set it from the
+  host: `curl https://llm.int.exe.xyz/models.json`. Nothing can guess it —
+  ids are per-integration.
+- **Model ids carry a provider prefix**: `openai/gpt-5.6-sol`, not
+  `gpt-5.6-sol`. Get them from `curl https://llm.int.exe.xyz/models.json` on
+  the host, and note its `preferred_model`.
+- **An unknown model id on the responses surface returns**
+  `404 unsupported endpoint: /v1/responses` — an error about the ENDPOINT for
+  a problem with the MODEL. The endpoint is fine. Check the prefix before
+  believing that 404; chasing it cost hours and produced two wrong fixes.
+- **Subscription-backed models are Responses-API only.** models.json reports
+  `"apis": ["openai_responses"]`, and chat-completions answers `Model … is
+  not in this integration's model list` for a model that plainly is listed.
+- **Evals must run ON the host.** `llm.int.exe.xyz` is internal to exe.dev, so
+  a laptop cannot reach it — every model call fails with a connection error to
+  the cloud metadata address, which looks like a broken agent and is not.
+- **An integration has to be attached to the VM** (`integrations attach llm
+  <vm>`, or `auto:all`). Check with `ssh exe.dev integrations list`.
+
 - **Docker ships disabled on some images.** exe.dev's exeuntu runs
   `systemctl disable docker.service`, so `docker --version` works while nothing
   can run. Every sandbox call fails with `SandboxTemplateNotProvisionedError`.