@kybernesis/create 0.5.1 → 0.6.0

package/dist/cli.js

@@ -22,6 +22,7 @@ function initOptions(rest) {
     const subs = flag(rest, 'subagents');
     return {
         engineer: rest.includes('--engineer'),
+        studio: rest.includes('--studio'),
         channel: flag(rest, "channel"),
         host: flag(rest, "host"),
         subagents: subs === undefined ? undefined : subs.split(',').map((s) => s.trim()).filter(Boolean),
@@ -59,6 +60,7 @@ ${bold("kyb")} — Kybernesis agent scaffolder & FDE toolkit
       --host=<kind>     ${dim("vercel|exe                                (default: vercel)")}
       --subagents=a,b   ${dim("department subagents                      (default: none)")}
       --engineer        ${dim("add the engineer layer: workshop sandbox + vision dev loop")}
+      --studio          ${dim("wire for KYBER Studio: local execution + management routes")}
       --yes             ${dim("no prompts; take flags and defaults")}
   ${bold("kyb doctor")}          preflight checks (keys, issuer, envs, discovery)
   ${bold("kyb skills")}          install/refresh the FDE skill suite for Claude Code

package/dist/doctor.js

@@ -238,6 +238,31 @@ export async function doctor() {
             }
         }
     }
+    // ── KYBER Studio wiring ────────────────────────────────────────────────
+    const hasLocal = existsSync(join(cwd, "agent/tools/local_shell.ts"));
+    const hasManage = existsSync(join(cwd, "agent/channels/kyb.ts"));
+    if (hasLocal) {
+        // Without the relay secret the tools compile, appear in the tool list, and
+        // fail at the moment the user asks for something — the worst time to learn
+        // a deployment is incomplete.
+        if (process.env.LOCAL_EXEC_AGENT_SECRET) {
+            add("pass", "local execution is configured (LOCAL_EXEC_AGENT_SECRET set)");
+        }
+        else {
+            add("fail", "local execution has no LOCAL_EXEC_AGENT_SECRET", "the local_* tools will be offered to the model and fail on first use; set the shared secret the control-plane relay expects");
+        }
+    }
+    if (hasManage) {
+        // manage authorizes with the caller's control-plane grant, so it needs to
+        // know which agent it IS before it can check one.
+        if (process.env.KYBERNESIS_AGENT) {
+            add("pass", "management routes can resolve this agent's grants");
+        }
+        else {
+            add("fail", "management routes have no KYBERNESIS_AGENT", "KYBER Studio cannot install or write routines here: the agent cannot check a grant for a name it does not know");
+        }
+        add("warn", "management routes need a writable working copy", "installing edits this repo and rebuilds; on a read-only serverless bundle the routes refuse. Set restartCommand in agent/channels/kyb.ts or an install will not take effect");
+    }
     // ── engineer subagent (build capability scoped to a subagent) ──────────
     const builderDir = join(cwd, "agent/subagents/builder");
     if (existsSync(builderDir)) {

package/dist/init.d.ts

@@ -1,6 +1,15 @@
 import { type ChannelKind, type HostKind } from "./templates.js";
 export interface InitOptions {
     engineer?: boolean;
+    /**
+     * Wire this agent for KYBER Studio: local execution on the user's own machine,
+     * and management routes so Studio can install capabilities and write routines.
+     *
+     * Off by default. Both let a client reach further than chat does — one onto
+     * the user's laptop, one into the agent's own repository — so they are a
+     * deliberate choice rather than something an engagement gets by accident.
+     */
+    studio?: boolean;
     /** Chat surface. Default "none" — add later with `kyb add channel`. */
     channel?: ChannelKind;
     /** Where the agent runs. Default "vercel". */

package/dist/init.js

@@ -17,6 +17,7 @@ const ENGINEER_ITEMS_VERCEL = ["connection/vercel"];
 const DEFAULT_MODEL = "anthropic/claude-sonnet-5";
 export async function init(rawName, options = {}) {
     const engineer = options.engineer === true;
+    const studio = options.studio === true;
     const nonInteractive = options.yes === true;
     const name = slug(rawName ?? (await ask("Agent name (kebab-case)?", "acme-agent")));
     if (!name) {
@@ -70,6 +71,18 @@ export async function init(rawName, options = {}) {
     for (const item of plan.registryItems) {
         run("npx", ["eve", "add", item, "--overwrite"], { cwd: dir, allowFail: true });
     }
+    if (studio) {
+        // Two separate items on purpose: `local` lets the agent act on the USER'S
+        // machine (consent per effect, granted on the desktop); `manage` lets a
+        // 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 …"));
+        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}`));
+        }
+    }
     const engPlan = engineer ? engineerPlan(host, DEFAULT_MODEL) : null;
     if (engPlan) {
         console.log(bold("\n2c   Engineer subagent: workshop sandbox + vision dev loop …"));
@@ -131,7 +144,7 @@ export async function init(rawName, options = {}) {
         }
     }
     console.log(bold("\n5/6  Env template + hermetic eval script …"));
-    writeFileSync(join(dir, ".env.example"), envExample(name, depts, issuer, plan.env));
+    writeFileSync(join(dir, ".env.example"), envExample(name, depts, issuer, plan.env, host, DEFAULT_MODEL));
     const pkgPath = join(dir, "package.json");
     const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
     pkg.scripts = { ...pkg.scripts, eval: evalScript(name, depts) };
@@ -148,6 +161,7 @@ export async function init(rawName, options = {}) {
         "self-testing (evals)",
         channel === "none" ? null : `${channel} channel`,
         host === "exe" ? "exe.dev host" : null,
+        studio ? "KYBER Studio (local execution + management routes)" : null,
         engineer ? "engineer subagent (workshop + vision loop)" : null,
         depts.length ? `${depts.length} dept subagent(s)` : null,
     ].filter(Boolean);

package/dist/templates.d.ts

@@ -7,7 +7,7 @@ export declare function subagentInstructionsMd(dept: string): string;
 export declare function subagentArcanaTs(dept: string): string;
 export declare function rootArcanaTs(): string;
 export declare function evalFileTs(displayName: string, depts: string[]): string;
-export declare function envExample(name: string, depts: string[], issuer: string, channelEnv?: string[]): string;
+export declare function envExample(name: string, depts: string[], issuer: string, channelEnv?: string[], host?: "vercel" | "exe", model?: string): string;
 export declare function evalScript(name: string, depts: string[]): string;
 export type ChannelKind = "none" | "slack" | "imessage" | "telegram" | "discord" | "web";
 export declare const CHANNEL_KINDS: ChannelKind[];

package/dist/templates.js

@@ -120,22 +120,46 @@ export default kybernesisBaseline({
 ${depts.length ? `  routing: [\n${routing}\n  ],\n` : ""}});
 `;
 }
-export function envExample(name, depts, issuer, channelEnv = []) {
+/**
+ * Env every self-hosted agent needs and cannot infer.
+ *
+ * Both of these have bitten a real deployment. EXE_MODEL must match the LLM
+ * integration actually attached — a ChatGPT subscription serves OpenAI models,
+ * so an Anthropic code default fails against it. EXE_VM_NAME has no default at
+ * all by design: guessing a host would hand a user a working link into another
+ * agent's machine.
+ */
+function exeEnvBlock(name, model) {
+    return `# Self-hosted host + model (@kybernesis/exe)
+# EXE_MODEL must match the LLM integration you attached to the VM. A ChatGPT
+# subscription serves OpenAI models; the code default will fail against one.
+# Set it explicitly rather than relying on ${model}.
+EXE_MODEL="${model}"
+# Preview URLs are built from this. There is no default on purpose.
+EXE_VM_NAME="${name}"
+
+`;
+}
+export function envExample(name, depts, issuer, channelEnv = [], host = "vercel", model = "") {
     const deptVars = depts
         .map((d) => {
         const upper = d.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
         return `# ARCANA_${upper}_API_KEY="kb_..."\n# ARCANA_${upper}_WORKSPACE="${name}-${d}"`;
     })
         .join("\n");
+    const header = host === "exe"
+        ? `# Real values live in .env.local ON THE HOST. \`eve start\` does NOT read it the
+# way \`eve dev\` does — scripts/eve-server.sh exports it into the process.`
+        : `# Real values belong in Vercel envs (prod/preview Sensitive); \`eve deploy\`
+# overwrites .env.local from the development environment on every deploy.`;
     return `# ── Kybernesis agent environment ─────────────────────────────────────
-# Real values belong in Vercel envs (prod/preview Sensitive); \`eve deploy\`
-# overwrites .env.local from the development environment on every deploy.
+${header}
 
 # Control-plane governance (@kybernesis/enterprise)
 KYBERNESIS_ISSUER="${issuer}"
 KYBERNESIS_AGENT="${name}"
 
-${channelEnv.length ? `# Channel\n${channelEnv.join("\n")}\n\n` : ""}# Arcana memory (@kybernesis/arcana) — one workspace + scoped kb_ key per brain
+${host === "exe" ? exeEnvBlock(name, model) : ""}${channelEnv.length ? `# Channel\n${channelEnv.join("\n")}\n\n` : ""}# Arcana memory (@kybernesis/arcana) — one workspace + scoped kb_ key per brain
 # ARCANA_API_KEY="kb_..."
 # ARCANA_COMPANY_WORKSPACE="${name}-company"
 # ARCANA_DM_WORKSPACE="${name}-company"
@@ -360,8 +384,11 @@ export default defineSandbox({
   revalidationKey: () => "kybernesis-workshop-v5-docker",
   async bootstrap({ use }) {
     const sandbox = await use();
+    // Base image is Debian-family; refresh indexes before installing browser deps.
     await sandbox.run({ command: "apt-get update" });
     await sandbox.run({ command: "npm install -g pnpm" });
+    // Explicit package.json rather than \`npm init -y\`: init derives the name from
+    // the directory, and npm rejects names starting with a dot (".shot").
     await sandbox.run({
       command:
         "mkdir -p /workspace/.shot && cd /workspace/.shot && echo '{\\"name\\":\\"kyb-shot\\",\\"private\\":true}' > package.json && npm install playwright",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "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/fde-engagement/references/playbook.md

@@ -44,6 +44,9 @@ npm create @kybernesis acme-atlas -- --engineer
 # ChatGPT/LLM subscription paying for inference. See section 11:
 npm create @kybernesis acme-atlas -- --host=exe --engineer
 
+# …or, when the client wants the desktop app (KYBER Studio) — see section 12:
+npm create @kybernesis acme-atlas -- --studio
+
 # 3. (Optional, for repeated use) put `kyb` on the PATH for the whole engagement:
 npm install -g @kybernesis/create
 ```
@@ -1990,7 +1993,91 @@ Nothing here can be borrowed from another agent or another account.
 against the client's `-eval` workspace, and a live turn on the real surface —
 sent from the client's own device, not yours.
 
-## 12. Known gaps — state these plainly, do not sell around them
+## 12. KYBER Studio — the desktop surface
+
+Slack and iMessage reach an agent where the client already works. KYBER Studio
+is the third door: a desktop app for people who do not live in a chat tool, and
+the only surface where an agent can work on the user's own files.
+
+Reach for it when the client says any of: *"not everyone here uses Slack"*,
+*"I want it on my laptop"*, *"can it look at our repo"*, or when the pilot
+involves someone technical who will hand the agent real work.
+
+### 12.1 What it is
+
+- **The same agent.** Studio does not run anything. It talks to the agent you
+  deployed — same memory, same tools, same subagents. Nothing to deploy twice.
+- **Governed by the same grants.** Sign-in is control-plane device flow, so
+  desktop access is the grant you already manage. Revoke it and the desktop goes
+  with it.
+- **Optionally hands and eyes.** With `@kybernesis/local` the agent can search,
+  read, edit, write, and run commands on the user's machine, with consent.
+- **Optionally self-modifying.** With `@kybernesis/manage` the client can
+  install capabilities and write routines from the app instead of asking you.
+
+### 12.2 The two packages, and why they are separate
+
+| | What it lets happen | Installed on |
+| --- | --- | --- |
+| `@kybernesis/local` | The agent acts on the USER's machine | the agent |
+| `@kybernesis/manage` | A client changes THE AGENT — deps and source | the agent |
+
+Different blast radius, so they are separate items an engagement chooses
+independently. A reporting agent might want `local` and never `manage`. Neither
+is installed by default, because both let a client reach further than chat does.
+
+```bash
+kyb init acme-agent --host=exe --studio        # both, at scaffold time
+npx eve add local                              # or either one, later
+npx eve add manage
+```
+
+`kyb doctor` checks both: the relay secret for local, and `KYBERNESIS_AGENT` for
+manage, since it cannot check a grant for a name it does not know.
+
+### 12.3 Prerequisites, in order
+
+1. **The agent is registered in the control plane** and the pilot users are
+   granted. Studio lists exactly what a user has a grant for — an agent that is
+   registered but ungranted is invisible, which is the correct behaviour and a
+   confusing one if you forget you did it.
+2. **The agent has a URL on file.** Studio reads `/api/me/agents`; an agent with
+   no deployment URL appears as unreachable rather than silently missing.
+3. **For `manage`: a writable working copy.** Installing edits the repo and
+   rebuilds, so it works on a VM and refuses on a read-only serverless bundle,
+   with that reason. Set `restartCommand` in `agent/channels/kyb.ts` or an
+   install completes without taking effect.
+4. **For `local`: the relay secret** (`LOCAL_EXEC_AGENT_SECRET`) matching the
+   control plane.
+
+### 12.4 What consent looks like for the user
+
+Studio asks per **effect** — run a command, read a file, write a file, list a
+directory — not per tool, and not per turn. Approving `read-file` once covers
+every tool that reads a file out, which is why adding a tool later cannot dodge
+a decision the user already made.
+
+The default is ask. A working folder can be set, but it is a starting directory
+rather than a fence: permission to act on the machine is granted once, and the
+agent may work wherever it is asked to. Whether it builds in its own sandbox or
+on the user's files is decided by the ask, not by a mode — the same way a
+colleague knows "build me a demo" from "look at my repo".
+
+### 12.5 State this plainly to the client
+
+- **Local execution is not yet a governed capability.** The agent authenticates
+  to the relay with a shared secret, so anyone holding it can reach a connected
+  desktop in that org. It must become its own revocable grant, separate from
+  "may talk to this agent". Do not install `local` at a client who would treat
+  that as a surprise.
+- **Reading a file sends it to the model.** Execution is local; the reasoning is
+  not. Fine for most work, and a conversation to have before a Studio points at
+  a regulated repository.
+- **Management routes let a client change the agent.** That is the point, and it
+  means the repository is no longer only yours. Agree who reviews what Studio
+  writes — routines land as source files, so a normal review works.
+
+## 13. Known gaps — state these plainly, do not sell around them
 
 Being straight about these is a feature. Clients have met vendors who were not.