@kybernesis/create 0.25.0 → 0.26.0

package/README.md

@@ -14,6 +14,10 @@ npx @kybernesis/create init acme-atlas
 
 `kyb init --host=exe` always installs the agent's computer (`@kybernesis/computer`: a persistent desktop with Chrome a person can watch and take over) and its vault (`@kybernesis/vault`: per-agent, per-person logins and cards it fills on that computer without seeing them). They are not options. A Vercel host gets neither, because a function cannot keep a desktop alive, and init says so.
 
+## Core on every Studio agent
+
+`kyb init --studio` (every agent the provisioner builds) also installs what a person sees beyond words in KYBER Studio and on the phone: cards under replies (`@kybernesis/cards` and the `show` tool from the `cards` registry item), artifacts (`@kybernesis/artifacts`: pages the agent makes and keeps, served by manage) and magic (`@kybernesis/magic`: proactive heads-ups, off until each person turns them on). On a Linq agent, magic delivers into the iMessage thread the person last used. `kyb upgrade` adds whichever of the three an agent with `@kybernesis/manage` is missing, lists them in `--check` so the owner's Update button shows, and holds the result to the eval gate even when no other package moved.
+
 ## `kyb init [name]`
 
 Scaffolds the full Kybernesis stack:

package/dist/doctor.js

@@ -11,6 +11,7 @@ import { describeStaleSidecar, newestPackageChange, staleSidecars } from "./stal
 import { checkSelfVersion } from "./self-version.js";
 import { envUrlProblems } from "./env-urls.js";
 import { migrateManifest, migrateSources } from "./line-hop.js";
+import { missingStudioCore } from "./studio-core.js";
 const MARK = {
     pass: green("✓"),
     warn: yellow("!"),
@@ -230,6 +231,10 @@ export async function doctor() {
         else
             add("warn", `${p} not installed`, `eve add @kybernesis/${p.split("/")[1]}`);
     }
+    // Core on every agent Studio manages; kyb upgrade adds whichever is missing.
+    for (const core of missingStudioCore(deps)) {
+        add("warn", `${core.pkg} not installed (${core.what})`, `npx kyb upgrade adds it, or npx eve add @kybernesis/${core.item}`);
+    }
     /**
      * multiplayer is conversation mechanics for a SHARED channel — threads with
      * per-speaker identity, the public/DM split. An agent reached only through

package/dist/init.js

@@ -9,6 +9,7 @@ import { upsertEnv } from "./envfile.js";
 import { systemdRestartCommand } from "./systemd.js";
 import { sandboxCleanupScaffoldFiles } from "./sandbox-cleanup.js";
 import { MODEL_REACH_ENV, resolveModelScaffold } from "./model-reach.js";
+import { STUDIO_CORE, ignoreMagicState, wireMagicLinq } from "./studio-core.js";
 /**
  * The always-installed core. Everything else — channels, subagents, engineer,
  * host bindings — is opt-in, because assuming them means the FDE deletes files
@@ -151,7 +152,7 @@ export async function init(rawName, options = {}) {
         // client change THIS AGENT — its dependencies and its source; `notify`
         // lets it reach the person's phone. Different blast radius, so an agent
         // can have one without the others.
-        console.log(bold("\n2b2  KYBER Studio: local execution + management routes + phone notifications …"));
+        console.log(bold("\n2b2  KYBER Studio: local execution + management routes + phone notifications + cards, artifacts, heads-ups …"));
         const studioFailures = [];
         for (const item of ["local", "manage", "notify"]) {
             // The @kybernesis/ prefix is load-bearing: a bare name resolves against
@@ -168,6 +169,20 @@ export async function init(rawName, options = {}) {
                 console.log(yellow(`  ! ${item} did not install — re-run: npx eve add @kybernesis/${item}`));
             }
         }
+        // What a person sees beyond words, on every agent Studio reaches: cards
+        // under replies, artifacts, and magic (off until each person opts in).
+        // After manage and notify on purpose: artifacts are served by manage's
+        // routes, and magic delivers into its conversation and rings the phone.
+        for (const core of STUDIO_CORE) {
+            const ok = run("npx", ["eve", "add", `@kybernesis/${core.item}`, "--overwrite"], { cwd: dir, allowFail: true });
+            if (!ok) {
+                studioFailures.push(core.item);
+                console.log(yellow(`  ! ${core.item} did not install — re-run: npx eve add @kybernesis/${core.item}`));
+            }
+            else if (core.item === "magic") {
+                ignoreMagicState(dir);
+            }
+        }
         // 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.
@@ -351,6 +366,9 @@ export async function init(rawName, options = {}) {
     else {
         console.log(bold(`\n4/6  Channel: ${channel} (no channel file) …`));
     }
+    // A person who last texted the agent gets their heads-ups in that thread.
+    if (studio && wireMagicLinq(dir))
+        console.log(dim("     agent/lib/magic-surfaces.ts — heads-ups also land in iMessage threads"));
     if (depts.length) {
         console.log(bold(`\n4b   Generating ${depts.length} department subagent(s) …`));
         const skillsSource = join(dir, "node_modules/@kybernesis/arcana/dist/extension/skills");
@@ -403,6 +421,7 @@ export async function init(rawName, options = {}) {
         host === "exe" ? "exe.dev host" : null,
         model.reach === "claude-sub" ? "Claude subscription reach" : null,
         studio ? "KYBER Studio (local execution + management routes)" : null,
+        studio ? "cards, artifacts and heads-ups (each person opts in)" : null,
         engineer ? "engineer subagent (workshop + vision loop)" : null,
         compPlan ? "its own computer (desktop + Chrome, watch and take over)" : null,
         compPlan ? "its own vault (logins and cards it fills without seeing)" : null,

package/dist/studio-core.d.ts

@@ -0,0 +1,68 @@
+/**
+ * What a person gets from an agent in KYBER Studio and on the phone beyond
+ * words: cards under a reply (the `show` tool), pages the agent makes and
+ * keeps (artifacts), and heads-ups it sends on its own (magic, off for each
+ * person until they turn it on). Core on every agent since 2026-10-23 (Ian:
+ * "they ship with every single agent").
+ *
+ * Keyed on @kybernesis/manage, like notify: manage serves the artifact pages
+ * and owns the conversation magic delivers into, so without it neither has
+ * anywhere to land. Every agent the provisioner builds has it (--studio).
+ *
+ * Each one's marker is its own package. An agent that already has it, added
+ * by hand or customised (Sid's own delivery map), is never touched.
+ */
+export declare const STUDIO_CORE: readonly [{
+    readonly item: "cards";
+    readonly pkg: "@kybernesis/cards";
+    readonly what: "cards under its replies";
+}, {
+    readonly item: "artifacts";
+    readonly pkg: "@kybernesis/artifacts";
+    readonly what: "pages it makes and keeps";
+}, {
+    readonly item: "magic";
+    readonly pkg: "@kybernesis/magic";
+    readonly what: "heads-ups, off until each person turns them on";
+}];
+export type StudioCoreItem = (typeof STUDIO_CORE)[number];
+/** The core items this agent is missing, in install order. None without manage. */
+export declare function missingStudioCore(deps: Record<string, string>): StudioCoreItem[];
+/**
+ * The additions an upgrade would make, for `kyb upgrade --check`.
+ *
+ * Without them the Update button stays hidden on an agent whose packages are
+ * all current, which is exactly the agent these were built after. `resolve`
+ * names the build that would install; one that resolves to nothing is left
+ * out, because nothing published runs on this eve.
+ */
+export declare function planStudioCore(deps: Record<string, string>, resolve: (pkg: string) => string | undefined): Array<{
+    name: string;
+    from: string;
+    to: string;
+}>;
+/**
+ * Where magic delivers on an agent that also answers on iMessage through Linq.
+ *
+ * The registry's map sends every heads-up into the conversation Studio and the
+ * phone share. A person who last texted the agent should get it in that same
+ * thread instead (Linq thread ids start with "linq:").
+ */
+export declare function magicSurfacesLinqTs(): string;
+/**
+ * Point magic at Linq when this agent has a Linq channel. Only ever called
+ * right after the registry wrote its default map, so nothing hand-made is lost.
+ */
+export declare function wireMagicLinq(cwd: string): boolean;
+/**
+ * Keep magic's per-person state out of git. `.kyb/magic/people/<id>/` holds
+ * what each person turned on and what they were told; it belongs to the host.
+ */
+export declare function ignoreMagicState(cwd: string): boolean;
+/**
+ * Install each missing core item from the agent's own @kybernesis registry,
+ * the same way `eve add` would by hand: its package and its files. Returns
+ * what was added; a failure is said and skipped, and the eval gate after it
+ * judges the agent as it stands.
+ */
+export declare function repairStudioCore(cwd: string, deps: Record<string, string>): StudioCoreItem[];

package/dist/studio-core.js

@@ -0,0 +1,124 @@
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { dim, green, run, yellow } from "./util.js";
+/**
+ * What a person gets from an agent in KYBER Studio and on the phone beyond
+ * words: cards under a reply (the `show` tool), pages the agent makes and
+ * keeps (artifacts), and heads-ups it sends on its own (magic, off for each
+ * person until they turn it on). Core on every agent since 2026-10-23 (Ian:
+ * "they ship with every single agent").
+ *
+ * Keyed on @kybernesis/manage, like notify: manage serves the artifact pages
+ * and owns the conversation magic delivers into, so without it neither has
+ * anywhere to land. Every agent the provisioner builds has it (--studio).
+ *
+ * Each one's marker is its own package. An agent that already has it, added
+ * by hand or customised (Sid's own delivery map), is never touched.
+ */
+export const STUDIO_CORE = [
+    { item: "cards", pkg: "@kybernesis/cards", what: "cards under its replies" },
+    { item: "artifacts", pkg: "@kybernesis/artifacts", what: "pages it makes and keeps" },
+    { item: "magic", pkg: "@kybernesis/magic", what: "heads-ups, off until each person turns them on" },
+];
+/** The core items this agent is missing, in install order. None without manage. */
+export function missingStudioCore(deps) {
+    if (!deps["@kybernesis/manage"])
+        return [];
+    return STUDIO_CORE.filter((core) => !deps[core.pkg]);
+}
+/**
+ * The additions an upgrade would make, for `kyb upgrade --check`.
+ *
+ * Without them the Update button stays hidden on an agent whose packages are
+ * all current, which is exactly the agent these were built after. `resolve`
+ * names the build that would install; one that resolves to nothing is left
+ * out, because nothing published runs on this eve.
+ */
+export function planStudioCore(deps, resolve) {
+    return missingStudioCore(deps).flatMap((core) => {
+        const version = resolve(core.pkg);
+        return version ? [{ name: core.pkg, from: "none", to: version }] : [];
+    });
+}
+/**
+ * Where magic delivers on an agent that also answers on iMessage through Linq.
+ *
+ * The registry's map sends every heads-up into the conversation Studio and the
+ * phone share. A person who last texted the agent should get it in that same
+ * thread instead (Linq thread ids start with "linq:").
+ */
+export function magicSurfacesLinqTs() {
+    return `import type { MagicDispatch } from "@kybernesis/magic";
+import type { ScheduleToFn } from "eve/schedules";
+import kyb from "../channels/kyb.js";
+import linq from "../channels/linq.js";
+
+/**
+ * Where a heads-up is delivered: the conversation the person last used.
+ *
+ * A person who last texted this agent gets it in that same iMessage thread
+ * (Linq thread ids start with "linq:"). Everyone else gets it in the
+ * conversation Studio and the phone app share, which rings their phone.
+ */
+export function deliver(to: ScheduleToFn, dispatch: MagicDispatch) {
+  const { surface, packet } = dispatch;
+  if (surface.token?.startsWith("linq:")) {
+    return to(linq, { threadId: surface.token }).send(packet, { auth: surface.auth });
+  }
+  return to(kyb, { routine: "magic" }).send(packet, { auth: surface.auth });
+}
+`;
+}
+/**
+ * Point magic at Linq when this agent has a Linq channel. Only ever called
+ * right after the registry wrote its default map, so nothing hand-made is lost.
+ */
+export function wireMagicLinq(cwd) {
+    if (!existsSync(join(cwd, "agent/channels/linq.ts")))
+        return false;
+    const surfaces = join(cwd, "agent/lib/magic-surfaces.ts");
+    if (!existsSync(surfaces))
+        return false;
+    writeFileSync(surfaces, magicSurfacesLinqTs());
+    return true;
+}
+/**
+ * Keep magic's per-person state out of git. `.kyb/magic/people/<id>/` holds
+ * what each person turned on and what they were told; it belongs to the host.
+ */
+export function ignoreMagicState(cwd) {
+    const path = join(cwd, ".gitignore");
+    const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+    if (current.split("\n").some((line) => /^\/?\.kyb\/?$/.test(line.trim())))
+        return false;
+    appendFileSync(path, `${current && !current.endsWith("\n") ? "\n" : ""}.kyb\n`);
+    return true;
+}
+/**
+ * Install each missing core item from the agent's own @kybernesis registry,
+ * the same way `eve add` would by hand: its package and its files. Returns
+ * what was added; a failure is said and skipped, and the eval gate after it
+ * judges the agent as it stands.
+ */
+export function repairStudioCore(cwd, deps) {
+    const added = [];
+    for (const core of missingStudioCore(deps)) {
+        const ok = run("npx", ["eve", "add", `@kybernesis/${core.item}`, "--yes"], { cwd, allowFail: true, quiet: true });
+        if (!ok) {
+            console.log(`  ${yellow("!")} could not add ${core.pkg} (${core.what}). Run: npx eve add @kybernesis/${core.item}`);
+            continue;
+        }
+        deps[core.pkg] = "latest";
+        added.push(core);
+        if (core.item === "magic") {
+            ignoreMagicState(cwd);
+            if (wireMagicLinq(cwd))
+                console.log(`    ${dim("magic delivers into iMessage threads too (agent/lib/magic-surfaces.ts)")}`);
+        }
+    }
+    if (added.length > 0) {
+        console.log(`  ${green("+")} Added ${added.map((core) => `${core.pkg} ${dim(`(${core.what})`)}`).join(", ")}`);
+        console.log(`    ${dim("Takes effect after the next build and restart.")}\n`);
+    }
+    return added;
+}

package/dist/upgrade.js

@@ -12,6 +12,7 @@ import { newestOnLine } from "./on-line-version.js";
 import { findMatchingAgentServiceUnit, repairManageRestart } from "./systemd.js";
 import { repairTerminalSandboxCleanupHooks } from "./sandbox-cleanup.js";
 import { repairExeClaudeRoute } from "./exe-claude-route.js";
+import { planStudioCore, repairStudioCore } from "./studio-core.js";
 import { repairOptInTools, repairRemovedDefaultTools as repairRemovedDefaultTools_ } from "./removed-default-tools.js";
 import { EVE_VERSION, REGISTRY_URL, bold, capture, dim, green, parseEnv, red, run, yellow } from "./util.js";
 import { backUpWorkflowStore, clearStaleEveCaches, migrateManifest, migrateSources, restoreWorkflowStore, workflowStoreBackup, } from "./line-hop.js";
@@ -1098,6 +1099,9 @@ export async function upgrade(options = {}) {
                     .filter((target) => changed.includes(`${target.name}@${target.targetVersion}`))
                     .map((target) => [target.name, { name: target.name, from: target.installedVersion, to: target.targetVersion }])).values(),
                 ...manifest.moves.map((move) => ({ name: move.name, from: move.from, to: move.to ?? "removed" })),
+                // Packages every agent now ships with that this one predates: an
+                // upgrade adds them, so the Update button has to show them.
+                ...planStudioCore(deps, (name) => newestBuildForEve(name, EVE_VERSION)),
             ],
             resetsConversations: eveChanged,
         });
@@ -1135,10 +1139,20 @@ export async function upgrade(options = {}) {
         repairHostArtifacts(cwd, deps);
         repairEvalCommand(cwd);
         repairNotifySetup(cwd, deps);
+        const added = repairStudioCore(cwd, deps);
         repairReasoningSandboxes(cwd, deps);
         repairManageRestart(cwd, deps);
         repairExeClaudeRoutes(cwd, deps);
         reportSourceMigration(cwd);
+        if (added.length === 0)
+            return;
+        // New tools and a schedule on a live agent: the same gate as any upgrade.
+        run("npm", ["run", "typecheck"], { cwd });
+        if (options.skipEval) {
+            console.log(yellow("\nEval gate SKIPPED (--skip-eval). Run `npm run eval` before deploying.\n"));
+            return;
+        }
+        await runUpgradeEvalGate(cwd, options.host);
         return;
     }
     console.log(bold(`\nInstalling: ${changed.join(", ")}\n`));
@@ -1225,6 +1239,7 @@ export async function upgrade(options = {}) {
     repairHostArtifacts(cwd, deps);
     repairEvalCommand(cwd);
     repairNotifySetup(cwd, deps);
+    repairStudioCore(cwd, deps);
     repairReasoningSandboxes(cwd, deps);
     repairManageRestart(cwd, deps);
     repairExeClaudeRoutes(cwd, deps);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "The Kybernesis agent scaffolder and FDE toolkit: one command to a governed, remembering, multiplayer, self-testing eve agent \u2014 plus doctor and upgrade.",
   "license": "Apache-2.0",
   "type": "module",
@@ -46,8 +46,7 @@
     "node": ">=20"
   },
   "publishConfig": {
-    "access": "public",
-    "tag": "eve-0.81"
+    "access": "public"
   },
   "peerDependencies": {}
 }