@kybernesis/create 0.10.0 → 0.12.0

package/dist/doctor.js

@@ -250,6 +250,31 @@ export async function doctor() {
             add("warn", "self-hosted: export .env.local into the server process", "eve start does NOT read it; use the supervision script from @kybernesis/exe (scripts/eve-server.sh)");
             add("warn", "self-hosted: start via `npx eve start`, not `node .output/server/index.mjs`", "sandbox templates are prewarmed by the CLI; starting the server directly skips prewarm and every sandbox tool fails with SandboxTemplateNotProvisionedError");
         }
+        /**
+         * A self-hosted agent answering everything twice.
+         *
+         * The local queue delivers a turn by POSTing it to this same server and
+         * holds that connection open for the whole turn, but its client gives up
+         * after 30 seconds by default. Every turn slower than that is redelivered,
+         * and the workflow re-executes steps that already ran — so the person gets
+         * two differently-worded answers to one question, and the log says only
+         * that a retry recovered. It is reported as the model being odd, which
+         * sends the search nowhere near the transport.
+         *
+         * Hosted agents never see it; real queue infrastructure runs there. This is
+         * a cost of self-hosting that nothing in the environment announces.
+         */
+        const QUEUE_TIMEOUT_FLOOR_MS = 120_000;
+        const shortQueueTimeouts = [
+            "WORKFLOW_LOCAL_HEADERS_TIMEOUT_MS",
+            "WORKFLOW_LOCAL_BODY_TIMEOUT_MS",
+        ].filter((name) => Number(env[name] ?? 30_000) < QUEUE_TIMEOUT_FLOOR_MS);
+        if (shortQueueTimeouts.length === 0) {
+            add("pass", "local queue delivery survives turns longer than 30s");
+        }
+        else {
+            add("fail", `self-hosted: ${shortQueueTimeouts.join(" and ")} left at the 30s default`, "one queue delivery holds a connection open for the entire turn, so any turn slower than the timeout is redelivered and its steps re-run — the agent answers the same question twice, with two different answers, and nothing reports an error. Set both to 900000 in .env.local and restart the server");
+        }
         // The exe VM sandbox backend needs a credential that cannot be scoped.
         // Surface the blast radius here, where it is still cheap to change course.
         const sandboxFile = join(cwd, "agent/sandbox/sandbox.ts");

package/dist/init.js

@@ -166,6 +166,21 @@ export async function init(rawName, options = {}) {
          * curl https://llm.int.exe.xyz/models.json
          */
         known.EXE_MODEL = "";
+        /**
+         * Longer than any turn, because the alternative is answering twice.
+         *
+         * The local queue delivers a turn by POSTing it to this same server and
+         * holds the connection open until the turn finishes, but its client gives
+         * up after 30 seconds by default. Any turn slower than that is redelivered
+         * and its steps re-run, so the person gets two differently-worded answers
+         * to one question with nothing in any log that looks like a fault.
+         *
+         * Written at scaffold rather than documented: it only affects self-hosted
+         * agents, it has one sensible value, and the failure it prevents is one
+         * nobody recognises in time.
+         */
+        known.WORKFLOW_LOCAL_HEADERS_TIMEOUT_MS = "900000";
+        known.WORKFLOW_LOCAL_BODY_TIMEOUT_MS = "900000";
     }
     upsertEnv(dir, known);
     if (!options.yes)
@@ -194,6 +209,30 @@ export async function init(rawName, options = {}) {
         catch {
             console.log(yellow("  ! could not install scripts/eve-server.sh — copy it from node_modules/@kybernesis/exe/scripts/"));
         }
+        /**
+         * The Claude subscription, as a script rather than a procedure.
+         *
+         * Same reasoning as the restart script above, and the same history: the
+         * provider (`claudeSubscription()`) was generalised into @kybernesis/exe
+         * after the first agent used it, but STANDING THE PROXY UP stayed a thing
+         * someone did by hand on one VM. So the capability was in every agent's
+         * packages while the only written procedure was a patch README telling the
+         * next person to clone a third-party repository — which is how a client
+         * ends up being walked through a git checkout by their consultant.
+         *
+         * Installed unconditionally for an exe host: it costs one file, and the
+         * alternative is rediscovering the procedure per deployment.
+         */
+        try {
+            const proxySource = join(dir, "node_modules/@kybernesis/exe/scripts/claude-subscription.sh");
+            const proxyTarget = join(dir, "scripts/claude-subscription.sh");
+            copyFileSync(proxySource, proxyTarget);
+            chmodSync(proxyTarget, 0o755);
+            console.log(dim("     scripts/claude-subscription.sh — put this agent on a Claude subscription, no API key"));
+        }
+        catch {
+            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.
          *

package/dist/upgrade.js

@@ -1,5 +1,6 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { upsertEnv } from "./envfile.js";
 import { EVE_VERSION, bold, capture, dim, green, red, run, yellow } from "./util.js";
 /**
  * Which packages to upgrade: every `@kybernesis/*` this agent depends on.
@@ -56,12 +57,43 @@ function warnIfStale() {
         `compiled into this tool, so an old kyb reports an old pin as current.`);
     console.log(`    ${dim("npm install -g @kybernesis/create@latest")}\n`);
 }
+/**
+ * Raise the local queue's delivery timeouts on an agent that already exists.
+ *
+ * @remarks
+ * Written as a repair rather than a warning because of what the bug looks like
+ * from outside: the agent answers the same question twice, in two different
+ * wordings, and no error appears in any log. Nobody reports that as a transport
+ * problem, so a warning would be read past — and the correct value is not a
+ * judgement call, it is "longer than a turn".
+ *
+ * Only for self-hosted agents. Hosted ones use real queue infrastructure and
+ * never touch this transport, so the variables would be noise in their
+ * environment.
+ */
+function repairLocalQueueTimeouts(cwd, deps) {
+    if (!deps["@kybernesis/exe"])
+        return;
+    const path = join(cwd, ".env.local");
+    if (!existsSync(path))
+        return;
+    const text = readFileSync(path, "utf8");
+    const missing = ["WORKFLOW_LOCAL_HEADERS_TIMEOUT_MS", "WORKFLOW_LOCAL_BODY_TIMEOUT_MS"].filter((name) => !new RegExp(`^${name}=`, "m").test(text));
+    if (missing.length === 0)
+        return;
+    upsertEnv(cwd, Object.fromEntries(missing.map((name) => [name, "900000"])));
+    console.log(`  ${green("+")} raised the local queue delivery timeout in .env.local ${dim("(was 30s)")}\n` +
+        `    ${dim("A delivery holds one connection open for the whole turn. Below this, any turn")}\n` +
+        `    ${dim("slower than 30s was redelivered and its steps re-run — the agent answered twice.")}\n` +
+        `    ${dim("Takes effect on the next server restart.")}\n`);
+}
 export async function upgrade(skipEval) {
     const cwd = process.cwd();
     const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     console.log(bold("\nkyb upgrade — checking @kybernesis/* and eve against npm\n"));
     warnIfStale();
+    repairLocalQueueTimeouts(cwd, deps);
     const toUpgrade = [];
     const unresolved = [];
     for (const name of kybernesisPackages(deps)) {

package/package.json

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

@@ -1968,6 +1968,53 @@ nowhere in its context. Verify from the host — the configured model id and the
 credential in use — never by asking the agent. Expect a client to ask it in a
 demo, and have the real answer ready.
 
+**Claude, on a Claude Max / Pro / Claude Code subscription.** The one that is
+a process rather than a file. Anthropic's billing validator accepts an OAuth
+bearer *instead of* an API key, and that bearer expires — so something has to
+own the refresh. A small proxy holds Claude Code's own credentials, refreshes
+them, and swaps them in; the agent speaks ordinary Anthropic API to loopback and
+never holds a long-lived secret.
+
+```bash
+# on the host, installed by kyb init for an exe host
+bash scripts/claude-subscription.sh up
+bash scripts/claude-subscription.sh login     # "Sign in with Claude", never an API key
+bash scripts/claude-subscription.sh status    # signed in? bound to loopback?
+```
+
+```ts title="agent/agent.ts"
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { claudeSubscription, CLAUDE_SUBSCRIPTION_CONTEXT_WINDOW } from "@kybernesis/exe";
+
+export default defineAgent({
+  model: claudeSubscription({ model: "claude-opus-5", createAnthropic }),
+  modelContextWindowTokens: CLAUDE_SUBSCRIPTION_CONTEXT_WINDOW,
+});
+```
+
+Four things to know before you promise it:
+
+- **The exe LLM integration also serves `anthropic/*` ids, and that is NOT this.**
+  It reaches Anthropic through a gateway, which bills metered usage. Same model,
+  entirely different invoice. If the point is that the client pays nothing
+  incremental, it has to be the proxy.
+- **If the agent searches the web, build the patched image** —
+  `scripts/claude-subscription.sh build-patched`. The published proxy renames
+  provider-defined tools, which Anthropic validates by name, and the failure
+  (`tools.N.web_search_20250305.name: Input should be 'web_search'`) reads like
+  a bug in the agent's own tool definitions.
+- **The sign-in is per host and interactive** — a browser step, once, in the
+  container. It survives restarts because it lives in a named volume, but a new
+  VM needs its own.
+- **It is a process to keep alive.** If the container stops, every turn fails
+  with a connection error from inside the model SDK, which reads like the model
+  being down. `hostPreflight({ claudeProxyUrl })` asks about it at boot; the
+  restart policy keeps it up.
+
+Scope it honestly with the client: this is their own subscription, on their own
+infrastructure, for their own agent. It is not a shared gateway or a resale of
+Anthropic access, and it should not be built as one.
+
 ### 11.5 Third-party APIs: broker the credential, pin the version
 
 Do not put a client's API token on the agent host. Put it in an exe.dev