@kybernesis/create 0.13.4 → 0.14.1

package/dist/init.js

@@ -5,6 +5,8 @@ import { CHANNEL_KINDS, channelPlan, engineerPlan, envExample, evalFileTs, exeEv
 import { suiteDir } from "./skills.js";
 import { configureArcana } from "./arcana.js";
 import { upsertEnv } from "./envfile.js";
+import { systemdRestartCommand } from "./systemd.js";
+import { sandboxCleanupScaffoldFiles } from "./sandbox-cleanup.js";
 /**
  * The always-installed core. Everything else — channels, subagents, engineer,
  * host bindings — is opt-in, because assuming them means the FDE deletes files
@@ -252,24 +254,23 @@ export async function init(rawName, options = {}) {
             console.log(yellow("  ! could not install scripts/claude-subscription.sh — copy it from node_modules/@kybernesis/exe/scripts/"));
         }
         /**
-         * Point the management routes at that script.
+         * Point management restarts at the one supervisor that owns production.
          *
-         * The registry template ships `restartCommand` commented out next to an
-         * example path, because on Vercel there is nothing to restart. On a VM
-         * there is, and the correct value is not a guess — it is the script three
-         * lines above. Left commented, every install through Studio succeeds and
-         * then reports that a restart is still required, which reads as a broken
-         * feature rather than one line of config nobody was asked for.
+         * install-service.sh installs systemd with a build-before-start gate. Using
+         * eve-server.sh after that would create a second supervisor and can leave
+         * two executors racing over one durable store. `-n` makes missing sudo
+         * authorization fail instead of hanging a detached Studio restart.
          */
         const manageChannelFile = join(dir, "agent/channels/kyb.ts");
         if (existsSync(manageChannelFile)) {
             const appRoot = `/home/exedev/${name}`;
+            const restartCommand = systemdRestartCommand(name);
             const wired = readFileSync(manageChannelFile, "utf8").replace(/export default manageChannel\(\{[\s\S]*?\}\);/, () => `export default manageChannel({\n` +
                 `  appRoot: process.env.EVE_APP_DIR ?? ${JSON.stringify(appRoot)},\n` +
-                `  restartCommand: "bash scripts/eve-server.sh restart",\n` +
+                `  restartCommand: ${JSON.stringify(restartCommand)},\n` +
                 `});`);
             writeFileSync(manageChannelFile, wired);
-            console.log(dim("     agent/channels/kyb.ts — restart wired to that script"));
+            console.log(dim(`     agent/channels/kyb.ts — restart wired to systemd (${restartCommand})`));
         }
     }
     if (plan.file) {
@@ -297,6 +298,11 @@ export async function init(rawName, options = {}) {
             }
         }
     }
+    for (const file of sandboxCleanupScaffoldFiles(host, depts)) {
+        const full = join(dir, file.path);
+        mkdirSync(join(full, ".."), { recursive: true });
+        writeFileSync(full, file.content);
+    }
     if (engPlan) {
         for (const file of engPlan.files) {
             const full = join(dir, file.path);

package/dist/removed-default-tools.d.ts

@@ -0,0 +1,29 @@
+/**
+ * eve 0.39 removed `glob` and `grep` from the default tool set (changelog
+ * 4c1bd80). Two things follow for an agent written against 0.38:
+ *
+ * - A `tools/glob.ts` or `tools/grep.ts` that exports `disableTool()` now
+ *   disables a slot nothing provides. On 0.38 that compiled with a warning;
+ *   from 0.39 it is a compile error — the whole agent fails to build, and
+ *   `eve eval` exits 1 with that one line as the only output. Kyber's ten
+ *   knowledge specialists each carried both files.
+ * - A scope that HAD the two tools by default (the root, the builder) loses
+ *   them silently. The certified agent's behaviour is preserved by opting
+ *   those scopes back in explicitly, which eve supports with a one-line file.
+ *
+ * Both happen in one pass over every agent scope, and only in the direction
+ * that preserves what the agent already did.
+ */
+export declare const REMOVED_DEFAULT_TOOLS: readonly ["glob", "grep"];
+/**
+ * A scope that disables `bash` has opted out of the sandbox altogether (the
+ * five sandbox tools proxy into one container; disabling bash is how a
+ * knowledge specialist stays container-free). Such a scope never had a
+ * reason to keep glob or grep either.
+ */
+export declare function scopeHasSandboxTools(scope: string): boolean;
+export interface RemovedDefaultToolsRepair {
+    removed: string[];
+    optedIn: string[];
+}
+export declare function repairRemovedDefaultTools(cwd: string): RemovedDefaultToolsRepair;

package/dist/removed-default-tools.js

@@ -0,0 +1,86 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+/**
+ * eve 0.39 removed `glob` and `grep` from the default tool set (changelog
+ * 4c1bd80). Two things follow for an agent written against 0.38:
+ *
+ * - A `tools/glob.ts` or `tools/grep.ts` that exports `disableTool()` now
+ *   disables a slot nothing provides. On 0.38 that compiled with a warning;
+ *   from 0.39 it is a compile error — the whole agent fails to build, and
+ *   `eve eval` exits 1 with that one line as the only output. Kyber's ten
+ *   knowledge specialists each carried both files.
+ * - A scope that HAD the two tools by default (the root, the builder) loses
+ *   them silently. The certified agent's behaviour is preserved by opting
+ *   those scopes back in explicitly, which eve supports with a one-line file.
+ *
+ * Both happen in one pass over every agent scope, and only in the direction
+ * that preserves what the agent already did.
+ */
+export const REMOVED_DEFAULT_TOOLS = ["glob", "grep"];
+function optInSource(tool) {
+    return (`// eve 0.39 removed ${tool} from the default tool set. This scope had it on the\n` +
+        `// certified 0.38 stack, so it is opted back in explicitly (kyb upgrade wrote this).\n` +
+        `export { default } from "eve/tools/${tool}";\n`);
+}
+function isDisableToolFile(path) {
+    try {
+        return /disableTool\s*\(/.test(readFileSync(path, "utf8"));
+    }
+    catch {
+        return false;
+    }
+}
+function agentScopes(cwd) {
+    const root = join(cwd, "agent");
+    if (!existsSync(root))
+        return [];
+    const scopes = [];
+    const visit = (dir) => {
+        if (existsSync(join(dir, "agent.ts")))
+            scopes.push(dir);
+        const subagents = join(dir, "subagents");
+        if (!existsSync(subagents))
+            return;
+        for (const entry of readdirSync(subagents, { withFileTypes: true })) {
+            if (entry.isDirectory())
+                visit(join(subagents, entry.name));
+        }
+    };
+    visit(root);
+    return scopes;
+}
+/**
+ * A scope that disables `bash` has opted out of the sandbox altogether (the
+ * five sandbox tools proxy into one container; disabling bash is how a
+ * knowledge specialist stays container-free). Such a scope never had a
+ * reason to keep glob or grep either.
+ */
+export function scopeHasSandboxTools(scope) {
+    const bash = join(scope, "tools", "bash.ts");
+    return !(existsSync(bash) && isDisableToolFile(bash));
+}
+export function repairRemovedDefaultTools(cwd) {
+    const removed = [];
+    const optedIn = [];
+    for (const scope of agentScopes(cwd)) {
+        const tools = join(scope, "tools");
+        for (const tool of REMOVED_DEFAULT_TOOLS) {
+            const file = join(tools, `${tool}.ts`);
+            if (existsSync(file)) {
+                if (isDisableToolFile(file)) {
+                    unlinkSync(file);
+                    removed.push(relative(cwd, file));
+                }
+                // Anything else authored there (an opt-in, a custom tool) is the
+                // agent's own and stays.
+                continue;
+            }
+            if (!scopeHasSandboxTools(scope))
+                continue;
+            mkdirSync(tools, { recursive: true });
+            writeFileSync(file, optInSource(tool));
+            optedIn.push(relative(cwd, file));
+        }
+    }
+    return { removed, optedIn };
+}

package/dist/sandbox-cleanup.d.ts

@@ -0,0 +1,18 @@
+export declare const SANDBOX_CLEANUP_HOOK_FILE = "sandbox-cleanup.ts";
+export declare function terminalSandboxCleanupHookTs(): string;
+export declare function sandboxCleanupScaffoldFiles(host: "vercel" | "exe", subagents: string[]): Array<{
+    path: string;
+    content: string;
+}>;
+/**
+ * Add the dedicated managed hook where it is missing, without replacing an
+ * authored file that happens to use the same path.
+ *
+ * Only scopes that can have a sandbox get it. `ctx.getSandbox()` PROVISIONS
+ * a sandbox when the session has none (eve docs, "Delete a sandbox": the next
+ * call provisions a fresh workspace), so a cleanup hook on a scope that has
+ * disabled its sandbox tools would start a container at session end in order
+ * to delete it — on Kyber, ten knowledge specialists doing that per closed
+ * session.
+ */
+export declare function repairTerminalSandboxCleanupHooks(cwd: string): string[];

package/dist/sandbox-cleanup.js

@@ -0,0 +1,57 @@
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { scopeHasSandboxTools } from "./removed-default-tools.js";
+export const SANDBOX_CLEANUP_HOOK_FILE = "sandbox-cleanup.ts";
+export function terminalSandboxCleanupHookTs() {
+    return `export { terminalSandboxCleanupHook as default } from "@kybernesis/exe/sandbox-cleanup";\n`;
+}
+export function sandboxCleanupScaffoldFiles(host, subagents) {
+    if (host !== "exe")
+        return [];
+    return ["agent", ...subagents.map((name) => join("agent/subagents", name))].map((scope) => ({
+        path: join(scope, "hooks", SANDBOX_CLEANUP_HOOK_FILE),
+        content: terminalSandboxCleanupHookTs(),
+    }));
+}
+function findLocalSubagents(directory) {
+    if (!existsSync(directory))
+        return [];
+    const found = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const child = join(directory, entry.name);
+        if (existsSync(join(child, "agent.ts")))
+            found.push(child);
+        found.push(...findLocalSubagents(child));
+    }
+    return found;
+}
+/**
+ * Add the dedicated managed hook where it is missing, without replacing an
+ * authored file that happens to use the same path.
+ *
+ * Only scopes that can have a sandbox get it. `ctx.getSandbox()` PROVISIONS
+ * a sandbox when the session has none (eve docs, "Delete a sandbox": the next
+ * call provisions a fresh workspace), so a cleanup hook on a scope that has
+ * disabled its sandbox tools would start a container at session end in order
+ * to delete it — on Kyber, ten knowledge specialists doing that per closed
+ * session.
+ */
+export function repairTerminalSandboxCleanupHooks(cwd) {
+    const agent = join(cwd, "agent");
+    if (!existsSync(agent))
+        return [];
+    const scopes = [agent, ...findLocalSubagents(join(agent, "subagents"))].filter(scopeHasSandboxTools);
+    const added = [];
+    for (const scope of scopes) {
+        const hooks = join(scope, "hooks");
+        const target = join(hooks, SANDBOX_CLEANUP_HOOK_FILE);
+        if (existsSync(target))
+            continue;
+        mkdirSync(hooks, { recursive: true });
+        writeFileSync(target, terminalSandboxCleanupHookTs());
+        added.push(target);
+    }
+    return added;
+}

package/dist/systemd.d.ts

@@ -0,0 +1,41 @@
+export declare const LEGACY_RESTART_COMMAND = "bash scripts/eve-server.sh restart";
+export declare function systemdRestartCommand(name: string): string;
+export interface ManageRestartDiagnosis {
+    verdict: "pass" | "warn" | "fail";
+    label: string;
+    detail?: string;
+}
+export declare function diagnoseManageRestart(serviceName: string | null, restartCommand: string | undefined): ManageRestartDiagnosis;
+export interface UnitValues {
+    name: string;
+    user: string;
+    app: string;
+    port: string;
+}
+export declare function parseAgentServiceUnit(path: string, contents: string): UnitValues | null;
+export type RestartMigration = "absent" | "missing" | "migrated" | "systemd" | "custom" | "blocked";
+export declare function reconcileManageRestart(cwd: string, name: string): RestartMigration;
+export interface InstalledAgentService {
+    path: string;
+    contents: string;
+    values: UnitValues;
+    mode: number;
+}
+export declare function findMatchingAgentServiceUnit(cwd: string, systemdDir?: string): InstalledAgentService | null;
+/**
+ * Refresh an existing package-generated unit. Deliberately never creates a
+ * missing unit, enables it, or restarts it; upgrade only reconciles artifacts
+ * whose systemd ownership is already established.
+ */
+/**
+ * Once systemd owns the agent, a Studio install that restarts through
+ * scripts/eve-server.sh starts a second supervisor beside it: the script
+ * kills systemd's child and starts its own while Restart=always starts
+ * another, and two executors race over one durable store. Migrate the exact
+ * scaffolded literal in agent/channels/kyb.ts to the systemd restart; leave
+ * anything an operator wrote, with the exact line to use.
+ *
+ * The unit itself is package-managed by repairHostArtifacts (managed marker,
+ * .bak copy); this only follows what that unit implies for restarts.
+ */
+export declare function repairManageRestart(cwd: string, deps: Record<string, string>, systemdDir?: string): RestartMigration | null;

package/dist/systemd.js

@@ -0,0 +1,136 @@
+import { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { dim, green, yellow } from "./util.js";
+export const LEGACY_RESTART_COMMAND = "bash scripts/eve-server.sh restart";
+export function systemdRestartCommand(name) {
+    return `sudo -n systemctl restart ${name}-agent`;
+}
+export function diagnoseManageRestart(serviceName, restartCommand) {
+    if (!serviceName) {
+        return restartCommand
+            ? { verdict: "pass", label: "management routes can restart the agent after an install" }
+            : {
+                verdict: "warn",
+                label: "management routes have no restartCommand",
+                detail: "installing edits this repo and rebuilds; without a restart the response says a restart is still required. Install the systemd service, then use the exact restartCommand its installer prints",
+            };
+    }
+    const desired = systemdRestartCommand(serviceName);
+    const remediation = `set restartCommand in agent/channels/kyb.ts to ${JSON.stringify(desired)}. ` +
+        `Verify passwordless sudo with: ${desired}. systemctl restart does not wait for an in-flight turn; an install can interrupt it.`;
+    if (restartCommand === LEGACY_RESTART_COMMAND) {
+        return {
+            verdict: "fail",
+            label: "management restart uses eve-server.sh while systemd owns the agent",
+            detail: `this can start two servers against one durable store; ${remediation}`,
+        };
+    }
+    if (restartCommand === desired) {
+        return { verdict: "pass", label: `management routes restart the systemd owner (${serviceName}-agent)` };
+    }
+    if (restartCommand) {
+        return {
+            verdict: "warn",
+            label: `management restartCommand is customized and was preserved (${JSON.stringify(restartCommand)})`,
+            detail: `confirm it cannot start a second supervisor; ${remediation}`,
+        };
+    }
+    return { verdict: "warn", label: "management routes have no restartCommand", detail: remediation };
+}
+export function parseAgentServiceUnit(path, contents) {
+    const fileName = /^(.+)-agent\.service$/.exec(basename(path))?.[1];
+    const user = /^User=(.+)$/m.exec(contents)?.[1];
+    const app = /^WorkingDirectory=(.+)$/m.exec(contents)?.[1];
+    const port = /^Environment=PORT=(.+)$/m.exec(contents)?.[1];
+    if (!fileName || !user || !app || !port)
+        return null;
+    return { name: fileName, user, app, port };
+}
+export function reconcileManageRestart(cwd, name) {
+    const path = join(cwd, "agent/channels/kyb.ts");
+    let before;
+    try {
+        before = readFileSync(path, "utf8");
+    }
+    catch {
+        return "absent";
+    }
+    const property = /\brestartCommand\s*:\s*(["'`])([^"'`]+)\1/m.exec(before);
+    const configured = property?.[2];
+    if (!configured)
+        return "missing";
+    if (configured === systemdRestartCommand(name))
+        return "systemd";
+    if (configured !== LEGACY_RESTART_COMMAND || property?.[1] !== '"')
+        return "custom";
+    try {
+        const replacement = property[0].replace(`${property[1]}${configured}${property[1]}`, JSON.stringify(systemdRestartCommand(name)));
+        writeFileSync(path, before.slice(0, property.index) + replacement + before.slice(property.index + property[0].length));
+        return "migrated";
+    }
+    catch {
+        return "blocked";
+    }
+}
+export function findMatchingAgentServiceUnit(cwd, systemdDir = "/etc/systemd/system") {
+    try {
+        for (const file of readdirSync(systemdDir).filter((entry) => entry.endsWith("-agent.service"))) {
+            const path = join(systemdDir, file);
+            const contents = readFileSync(path, "utf8");
+            const values = parseAgentServiceUnit(path, contents);
+            if (values && resolve(values.app) === resolve(cwd)) {
+                return { path, contents, values, mode: statSync(path).mode & 0o777 };
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function printRestartGuidance(state, cwd, name) {
+    if (state === "absent" || state === "systemd")
+        return;
+    const desired = systemdRestartCommand(name);
+    if (state === "migrated") {
+        console.log(`  ${green("+")} migrated agent/channels/kyb.ts to ${desired}`);
+    }
+    else if (state === "custom" || state === "blocked") {
+        console.log(`  ${yellow("!")} ${state === "blocked" ? "could not migrate" : "preserved customized"} restartCommand in agent/channels/kyb.ts. systemd owns ` +
+            `this agent; scripts/eve-server.sh would create a second supervisor. Review it and use exactly:\n` +
+            `    ${dim(`restartCommand: ${JSON.stringify(desired)},`)}\n` +
+            `    ${dim(`Verify passwordless sudo with: ${desired}`)}\n` +
+            `    ${dim("systemctl restart does not wait for an in-flight turn; an install can interrupt it.")}`);
+    }
+    else {
+        console.log(`  ${yellow("!")} ${join(cwd, "agent/channels/kyb.ts")} has no restartCommand. Add exactly:\n` +
+            `    ${dim(`restartCommand: ${JSON.stringify(desired)},`)}\n` +
+            `    ${dim("It needs passwordless sudo and can interrupt an in-flight turn.")}`);
+    }
+}
+/**
+ * Refresh an existing package-generated unit. Deliberately never creates a
+ * missing unit, enables it, or restarts it; upgrade only reconciles artifacts
+ * whose systemd ownership is already established.
+ */
+/**
+ * Once systemd owns the agent, a Studio install that restarts through
+ * scripts/eve-server.sh starts a second supervisor beside it: the script
+ * kills systemd's child and starts its own while Restart=always starts
+ * another, and two executors race over one durable store. Migrate the exact
+ * scaffolded literal in agent/channels/kyb.ts to the systemd restart; leave
+ * anything an operator wrote, with the exact line to use.
+ *
+ * The unit itself is package-managed by repairHostArtifacts (managed marker,
+ * .bak copy); this only follows what that unit implies for restarts.
+ */
+export function repairManageRestart(cwd, deps, systemdDir = "/etc/systemd/system") {
+    if (!deps["@kybernesis/exe"])
+        return null;
+    const match = findMatchingAgentServiceUnit(cwd, systemdDir);
+    if (!match)
+        return null;
+    const state = reconcileManageRestart(cwd, match.values.name);
+    printRestartGuidance(state, cwd, match.values.name);
+    return state;
+}

package/dist/templates.d.ts

@@ -50,3 +50,15 @@ export declare function engineerPlan(host: HostKind, model: string): EngineerPla
  * endpoint, so none of the subscription backend's constraints apply.
  */
 export declare function exeEvalConfigTs(): string;
+/**
+ * An eve 0.49 memory slot backed by Arcana.
+ *
+ * Written by `kyb add memory`. The slot gives the agent recall before every
+ * turn without a skill telling the model to go and look; capture stays off
+ * because the remember skill already stores facts deliberately. When the
+ * Arcana extension is mounted the slot offers no tools of its own — the
+ * extension's `arcana_*` set is the same brain through the same key.
+ */
+export declare function arcanaMemorySlotTs(options: {
+    extensionMounted: boolean;
+}): string;

package/dist/templates.js

@@ -383,8 +383,9 @@ export function hostSteps(host, name) {
             `Attach an LLM integration (ChatGPT subscription, your API key, or exe's gateway):`,
             `    ssh exe.dev integrations setup chatgpt --name work   # once, device-code`,
             `    ssh exe.dev integrations edit llm --openai=chatgpt --openai-account=work`,
-            `Install Node 24 + deps on the VM, then: npx eve build && bash scripts/eve-server.sh start`,
-            `\`eve start\` does NOT read .env.local — scripts/eve-server.sh loads it for you`,
+            `Install Node 24 + deps on the VM, fill .env.local, then install the production service:`,
+            `    bash node_modules/@kybernesis/exe/scripts/install-service.sh`,
+            `The systemd unit exports .env.local, builds before every start, and is the single supervisor`,
         ];
     }
     return [
@@ -571,6 +572,12 @@ export { default } from "@kybernesis/engineer";
             content: workshopSandbox(host),
         },
     ];
+    if (onExe) {
+        files.push({
+            path: "agent/subagents/builder/hooks/sandbox-cleanup.ts",
+            content: `export { terminalSandboxCleanupHook as default } from "@kybernesis/exe/sandbox-cleanup";\n`,
+        });
+    }
     if (onExe) {
         files.push({
             path: "agent/subagents/builder/tools/preview.ts",
@@ -627,3 +634,47 @@ export default defineEvalConfig({
 });
 `;
 }
+/**
+ * An eve 0.49 memory slot backed by Arcana.
+ *
+ * Written by `kyb add memory`. The slot gives the agent recall before every
+ * turn without a skill telling the model to go and look; capture stays off
+ * because the remember skill already stores facts deliberately. When the
+ * Arcana extension is mounted the slot offers no tools of its own — the
+ * extension's `arcana_*` set is the same brain through the same key.
+ */
+export function arcanaMemorySlotTs(options) {
+    return `import { defineMemory } from "eve/memory";
+import { byPrincipal } from "eve/memory/scope";
+import { arcanaMemory } from "@kybernesis/arcana/memory";
+
+/**
+ * Recall before every turn, from the company brain. eve resolves who the
+ * memory belongs to (byPrincipal: the authenticated caller; local-dev while
+ * developing) and delivers what Arcana finds as one message the model sees
+ * before it answers. Greetings and other short turns skip recall.
+ *
+ * Capture is off: this agent remembers deliberately through arcana_remember.
+ * Set capture: { enabled: true } for an agent that should learn passively.
+ */
+const COMPANY = process.env.ARCANA_COMPANY_WORKSPACE!;
+const DM = process.env.ARCANA_DM_WORKSPACE ?? COMPANY;
+
+export default defineMemory({
+  description: "Durable company memory in Arcana: people, decisions, projects, preferences.",
+  provider: arcanaMemory({
+    // Keys are workspace-scoped. The eval script points every workspace at the
+    // -eval brain, which has its own key; the same choice the extension makes.
+    apiKey:
+      (COMPANY.endsWith("-eval") ? process.env.ARCANA_EVAL_API_KEY : undefined) ??
+      process.env.ARCANA_API_KEY!,
+    workspace: COMPANY,
+    // A DM is a private surface with its own brain; verified from session auth,
+    // never from the message.
+    resolveWorkspace: (ctx) =>
+      ctx.session.auth.current?.attributes.surface === "dm" ? DM : undefined,${options.extensionMounted ? "\n    // The Arcana extension already mounts the full arcana_* tool set.\n    tools: false," : ""}
+  }),
+  scope: byPrincipal,
+});
+`;
+}