@kybernesis/create 0.5.2 → 0.7.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,33 @@ 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 a credential 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. This is NOT a value to go and set by hand: the
+        // switch in Studio installs it, and a missing one means nobody has turned
+        // local access on yet.
+        if (process.env.KYBERNESIS_AGENT_CREDENTIAL) {
+            add("pass", "local execution can identify this agent to the control plane");
+        }
+        else {
+            add("warn", "local execution is installed but this agent has no credential yet", "turn on 'Work on this computer' in the agent's settings in KYBER Studio — it mints and installs one; do not paste a credential by hand");
+        }
+    }
+    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 …"));
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.5.2",
+  "version": "0.7.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/control-plane/SKILL.md

@@ -46,6 +46,32 @@ This exact sequence was verified against production 2026-08-05. The demo
 moment for clients is step 3→4 — access appearing and disappearing from the
 admin screen.
 
+## It also brokers connectors and the user's own machine
+
+Governance was the first job; the plane now also holds the two things an agent
+cannot hold itself.
+
+**Connectors** (`/api/connectors`, `link`, `disconnect`, `tools`, `execute`,
+`custom`, `mcp`, `mcp/test`). Each ORG holds its own broker (Composio) API key,
+encrypted at rest with `SECRET_ENCRYPTION_KEY` (AES-256-GCM,
+`v1:<iv>:<tag>:<ct>`), set
+through the admin — never an env var, never our key used for a client. The
+agent asks the plane which services the CURRENT principal has connected;
+`@kybernesis/connectors` turns the answer into tools for that turn only. The
+broker's entity is `<registered-agent-name>:<userId>` — the registered NAME,
+not the agent's UUID.
+
+**Local access** (`/api/local-exec/*`). A device enrolls, the user grants it
+once, and that grant is STANDING — no expiry. Requests and responses are relayed
+as frames; the plane never executes anything. See `@kybernesis/local`.
+
+**A client must refresh on the earlier of the token and the bundle.** They have
+independent lifetimes: a token with 57 minutes left and a bundle with 12 will
+start returning 401 while every dashboard says the session is fine. This cost a
+full day, presented to the user as "log out and log back in", and the fix is one
+line — `Math.min(tokenExpiry, bundleExpiry)`. On a 401, force a refresh and
+retry ONCE before showing a human anything.
+
 ## Boundaries to state plainly
 
 Control-plane grants govern the HTTP/desktop doors — NOT the Slack door

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
 ```
@@ -1870,6 +1873,45 @@ client with an existing ChatGPT or Claude subscription pays no incremental
 inference cost for the pilot. Say the number out loud in the discovery
 conversation — it changes the shape of the deal.
 
+**Grok, on a SuperGrok or X Premium+ subscription.** Same arrangement, without
+the broker: xAI's Grok Build CLI does a device login and writes a credential
+that is a valid bearer for `https://api.x.ai/v1`. Proven in production on Sid —
+twelve evals, twenty-nine gates, green on the subscription.
+
+```bash
+# on the host, as the unix user the agent runs as
+curl -fsSL https://x.ai/cli/install.sh | bash
+grok login                              # device flow → ~/.grok/auth.json
+```
+
+```ts title="agent/agent.ts"
+import { createOpenAI } from "@ai-sdk/openai";
+import { grokSubscription } from "@kybernesis/exe";
+
+export default defineAgent({
+  model: grokSubscription({ model: "grok-4.6", createOpenAI }),
+  modelContextWindowTokens: 400_000,
+});
+```
+
+Three things to know before you promise it to a client:
+
+- The credential is **per-machine and per-user**. It lives in a home directory.
+  A different unix user cannot see it; a new host needs its own login.
+- It **expires in six hours** and the CLI refreshes it in place, so the agent
+  must re-read the file per request. `grokSubscription` does this in a `fetch`
+  wrapper. (Do not reach for a Proxy around the model object — the AI SDK's
+  methods depend on their own `this` and every call dies inside the SDK.)
+- **Unattended refresh over days is unverified.** If nobody runs `grok` on that
+  host for a week, it is an open question, and it would present to the client as
+  the agent breaking for no reason.
+
+**The model will lie about which model it is.** Sid, running Grok, stated it was
+"Claude Opus 4.6, Anthropic" and attributed it to an instruction that exists
+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.
+
 ### 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
@@ -1971,6 +2013,40 @@ Also: a long-lived channel session caches the compiled agent. After changing
 capabilities, start a **fresh conversation** before deciding the change did not
 work.
 
+**A restart script must do two more things, and both were learned from a
+stranded user.**
+
+*Serialize restarts.* `@kybernesis/manage` fires one 20s after any change, and
+you will also run one by hand. Two overlapping runs both finish killing before
+either starts, and you end up with **two supervisors and two servers writing to
+one durable store** — two executors racing over the same runs. That is not a
+slow agent, it is a corrupt one. Take a `flock` at the top of the script, and
+assert exactly one server process at the bottom.
+
+*Wait for in-flight turns.* eve does **not** resume a step killed mid-flight.
+Restart into a live turn and that turn never emits another event, the session
+never parks, and every later message queues behind a turn that will never
+finish. The user watches a spinner forever, and no further restart fixes it,
+because the session is stranded rather than stuck. Poll
+`.eve/.workflow-data/runs/*.json` for a `turnWorkflow` in `running` state and
+wait for it to clear — with a cap, so a wedged turn cannot block the restart
+that would clear it.
+
+*And measure it correctly.* `pgrep -f 'server/index.mjs'` run over ssh matches
+**the shell running the pgrep** — the pattern is in its own command line — so it
+reports two servers when there is one. An entire investigation went into hunting
+a phantom supervisor that a `ps -eo pid,ppid,args` would have dismissed in
+thirty seconds. Same family as `pkill -f` killing its caller. Inside a script
+file it is safe (the script's command line is `bash restart.sh`); typed at a
+shell or sent over ssh it is not. When a process count surprises you, **list the
+matches before believing the number.**
+
+The escape from an already-stranded session is a **session reset**
+(`ClientSession.reset()`, or Reset in Studio's agent settings), which releases
+the durable owner so the next message starts a fresh conversation. Cancelling
+often does not help: the executor that would honour the cancel is the one that
+died.
+
 ### 11.9 Credential checklist — collect ALL of these from the client
 
 Nothing here can be borrowed from another agent or another account.
@@ -1990,7 +2066,192 @@ 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`: nothing to configure.** Setup is one switch in Studio — the
+   agent's settings, *Work on this computer*. Behind it, Studio mints the
+   agent's credential from the control plane, installs it over the manage
+   channel, and records a standing grant for that machine; the agent restarts
+   once to load it. Never hand anyone a credential to paste into an env file.
+   The admin UI's "mint agent credential (shown once)" button remains for
+   recovery and is not the path: a setup step that asks someone to carry a
+   secret between two screens gets done wrong or skipped.
+
+### 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
+
+- **Two things gate a laptop, and they fail differently.** *Identity* is the
+  agent's signed credential — "the local-execution relay rejected my
+  credentials" means that. *Consent* is a standing per-device grant — "you have
+  not allowed this agent to work on this computer" means that. Neither alone
+  reaches anything. The grant is permanent on purpose: "always allow" means
+  always, from a chat window, a schedule, or a message sent from a phone, and it
+  ends on revoke, device removal, or disabling the agent.
+- **Reaching a desktop is still not its own revocable capability.** "May talk to
+  this agent" and "may run commands on my laptop" remain one decision, taken
+  when the person allows the machine. Say so at a client who would treat it as a
+  surprise.
+- **Installing the credential restarts the agent**, and a turn in flight during
+  that restart is lost for good — eve does not resume a step killed mid-flight.
+  It reads as a spinner that never resolves, often alongside a "credential is
+  unset" error from the process that was replaced. Send a new message, and reset
+  the conversation if the session itself is stranded. §11.8 is why a restart
+  script must wait for in-flight turns.
+- **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.
+
+### 12.7 Connectors — the apps library
+
+The Apps tab in Studio is a shelf of services a person connects in one click:
+Gmail, Calendar, Drive, Slack, Notion, Linear, GitHub, Attio, Outlook, HubSpot.
+Connecting one makes its tools appear in that person's next session.
+
+**Setup is one field, and it belongs to the client.** The org's own Composio key
+goes in their control plane at **Settings → Connectors**, set by an owner, the
+same way SSO is. It is never a deployment env var and never ours: each control
+plane belongs to one company, and nobody's people connect their mailboxes under
+another org's account. Direct them to composio.dev → Settings → API Keys.
+
+**What makes it one click** is that Composio has already registered the OAuth
+app for each service. Without a broker, every client has to create a developer
+app per provider — which is exactly the hour lost to Notion on the first
+deployment, version pin and all.
+
+**Two things on every card, because both are load-bearing:**
+
+*Connects as you* versus *for the company*. A user-scoped connection cannot fire
+from a schedule — a routine at 8am has no signed-in person. Anything a briefing
+depends on must be the company's connection.
+
+*An admin must approve*. True for Slack, Notion, and Google Workspace. Say it on
+the card; a client who discovers it at the end of a redirect chain reads the
+product as broken.
+
+**How tools reach the agent.** `@kybernesis/connectors` mounts a dynamic
+resolver in `agent/tools/connectors.ts`. It resolves per session from the
+principal on the turn, asks the control plane what that person has connected,
+and calls back through it to execute. The agent never holds the broker key — it
+proves which agent it is with its own credential, and the control plane decides
+whose account the call runs against.
+
+Resolution is per session, not per turn: a tool set is part of the prompt, and
+rebuilding it every turn re-ingests the conversation at uncached prices. Pass
+`perTurn: true` where people connect things mid-conversation and expect them to
+work immediately.
+
+**Say this to the client.** Their Composio account holds refresh tokens for
+their Google Workspace and Slack — a fourth party alongside the model provider,
+the host, and us. Most will not blink; a regulated one will, and the answer for
+them is `eve-connect`, native eve connections with no broker. That is why every
+card carries a `provider`.
+
+**And watch the bill.** Composio prices per action. An agent in a loop is a very
+different cost profile from a person clicking, and that belongs in the pricing
+conversation before the first invoice, not after.
+
+### 12.8 MCP servers — the client's own tools, local and remote
+
+The MCP tab is the escape hatch from the shelf: anything with an MCP server
+becomes agent tools, whether it runs on the person's laptop or on a URL.
+
+**Local** — a command Studio runs on that machine (`npx -y @acme/mcp`, with env
+vars if the server needs them). Studio keeps it alive, and the deployed agent
+reaches it through the same relay as local execution. This is how a client's
+internal tooling — the CLI nobody will ever expose to the internet — becomes
+something the agent can use, without opening a port.
+
+**Remote** — a URL and optional headers. Studio runs the handshake before
+saving, so a bad URL fails at the moment someone types it rather than in the
+middle of a demo.
+
+Consent is **per server**, and approving one does not approve the next. The
+discovery call (listing what a server offers) is exempt — otherwise a person is
+asked to approve something before they can see what it is.
+
+The things that cost real sessions here:
+
+- **The command in a vendor's README is often the installer**, not the server.
+  Plaud's documented line runs an `install` subcommand and exits; the stdio
+  server is the bare command. If a server "connects" and never answers, check
+  that you are running the server.
+- **A server declares its arguments and you must honour them.** Studio passes
+  the published `inputSchema` through to the model (`@kybernesis/local` ≥0.5.0).
+  Before that it did not, and watching the result is the best argument for the
+  fix: nine consecutive calls guessing the name of an argument the server had
+  documented, steered only by error strings.
+- **Discovery must have a deadline.** These resolvers run before a turn and
+  reach across a network to a laptop that might be shut. Budgeted at 6s with a
+  five-minute cache; without that, one closed lid makes every turn hang.
+
+## 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.
 
@@ -2007,9 +2268,12 @@ Being straight about these is a feature. Clients have met vendors who were not.
    requester or a `manage`-grant holder may approve — are the planned governance half in
    `@kybernesis/enterprise`.
 
-3. **Eve Studio sign-in is specced, not built.** Employees who do not live in Slack have
-   no polished desktop door yet; HTTP access is token-by-hand via the device flow. The
-   implementation brief is in [[kybernesis-architecture-and-studio-signin]].
+3. **The desktop door is built** — KYBER Studio, signed and notarized, with device-flow
+   sign-in and in-app updates. What is NOT built is a second consent system talking to
+   the first: the control plane holds the standing per-device grant, Studio holds
+   per-effect permissions in a local file, and revoking in one does not revoke the
+   other. An off-boarding story that says "we revoke access centrally" must be qualified
+   at any client that asks the follow-up question.
 
 4. **Off-boarding SLA equals the token TTL** (1h default) for already-minted sessions.
    Suspension is immediate; revocation is not. Tune `IDENTITY_TOKEN_TTL_SECONDS` to the
@@ -2020,9 +2284,20 @@ Being straight about these is a feature. Clients have met vendors who were not.
    a time per session — simultaneous speakers resolve in arrival order, with mid-turn
    messages folded into the next turn best-effort.
 
-6. **Per-user OAuth into personal SaaS and local-file work (the device bridge) are future
-   builds.** Org service accounts with static tokens cover most pilot asks. Subagents in
-   particular *cannot* use per-user OAuth at all — no user principal.
+6. **Per-user OAuth and local-file work are BUILT** — §12.6 and §12.7, both proven end
+   to end. The remaining edge is the one that bites unattended: anything without a
+   signed-in person (a schedule, a subagent) has no user principal, so a user-scoped
+   connection is not available to it. A morning briefing built on someone's personal
+   Gmail connection does not fail loudly — it quietly has no tools. Company-scoped
+   connections are the answer, and that path has not yet been exercised in production.
+
+   Two more, worth saying because a client will meet them:
+
+   - **Tool volume is unmanaged.** Gmail and Calendar alone are 51 tool definitions in
+     every prompt. Real tokens per turn, and measurably worse tool selection as a client
+     connects more. Curation is designed, not shipped — connect what the pilot needs.
+   - **Local MCP servers are per-machine.** A person's second laptop silently has a
+     different set, and nothing in the UI says which machine a server is on.
 
 7. **DM memory is per-workspace, not per-employee, unless you build it.** Splitting DMs
    into one Arcana workspace per person needs a Slack-user-id → workspace-slug map in the

package/skills/kybernesis-packages/SKILL.md

@@ -1,10 +1,10 @@
 ---
-description: Use when installing, configuring, or debugging any @kybernesis package — arcana (memory), enterprise (governance), multiplayer (Slack), engineer (build+ship), dispatch (agent-to-agent), evals (QA), create (kyb CLI) — or the Kybernesis registry. Includes every production-learned gotcha.
+description: Use when installing, configuring, or debugging any @kybernesis package — arcana (memory), enterprise (governance), multiplayer (Slack), engineer (build+ship), dispatch (agent-to-agent), connectors (Gmail/Calendar/remote MCP), local (the user's own machine), manage (Studio→agent), exe (off-Vercel hosting), evals (QA), create (kyb CLI) — or the Kybernesis registry. Includes every production-learned gotcha.
 ---
 
 # The Kybernesis packages
 
-Seven packages, npm-public under `@kybernesis`, Apache-2.0, monorepo
+Eleven packages, npm-public under `@kybernesis`, Apache-2.0, monorepo
 `KybernesisAI/platform`. Registry: `https://registry.kybernesis.ai`
 (`eve registry add @kybernesis=https://registry.kybernesis.ai/r/{name}.json`,
 then `eve add @kybernesis/<item>`). Each covers one axis:
@@ -60,6 +60,28 @@ then `eve add @kybernesis/<item>`). Each covers one axis:
   0.2.1 lesson: eve resolves remote URLs at BOOT — url() must degrade
   (env → discovery-if-credentialed → fallbackUrl), never throw on a missing
   credential, or the whole agent (and its evals) fails to boot.
+- **connectors** — the user's SaaS accounts, brokered. `connectorTools()` is a
+  dynamic resolver: at turn start it asks the control plane which services THIS
+  principal has connected and returns those tools. Composio is the broker; the
+  API key is per-org, held in the control plane (never an env var, never a
+  client's key in our account). Tools are named `<toolkit>_<action>`. Also
+  exports `toolInputSchema` (broker JSON Schema → zod) and a minimal MCP client
+  for `mcp-direct` servers that speaks BOTH JSON and text/event-stream.
+- **local** — the user's own machine, through KYBER Studio. `localShellTool`,
+  `localRead/List/Write/Edit/SearchTool`, plus `localMcpTools()` for MCP servers
+  running on that machine, relayed. Every effect is consented in Studio; the
+  agent never holds a shell. `LOCAL_INSTRUCTIONS` explains the arrangement to
+  the model — mount it or the agent will offer to do things it cannot do.
+- **manage** — the other direction: `manageChannel()` lets Studio install
+  capabilities and write schedules onto a running agent, and `routineTools()`
+  turns "every morning at 8, brief me" into a real schedule file. This is how a
+  routine gets created from chat without anyone touching the repo.
+- **exe** — running off Vercel. `exeModel()` for exe.dev's LLM integration,
+  `grokSubscription()` / `readGrokCredential()` for a SuperGrok or X Premium+
+  login (`grok login` → `~/.grok/auth.json`, a valid bearer for api.x.ai —
+  same shape as eve's `experimental_chatgpt()`), `hostPreflight()`, Photon
+  iMessage credentials, and a `/preview` tool. Subpaths: `/slack`, `/photon`,
+  `/sandbox`, `/preview`. See the `self-hosting` skill.
 - **evals** — QA. `kybernesisBaseline({ agentDisplayName, routing,
   engineer? })` = smoke + 5 memory + routing per dept + optional vision-loop
   eval. Judge model ≠ model under test. Hermetic runs force all workspaces to
@@ -91,6 +113,36 @@ then `eve add @kybernesis/<item>`). Each covers one axis:
   company-general wording (dept-flavored prompts delegate and hide tool
   calls), no security vocabulary ("canary" triggers refusals), long routing
   timeouts. Do not "clean up" the odd-looking patterns.
+- **A per-turn dynamic resolver needs a deadline.** `connectorTools()` and
+  `localMcpTools()` run before every turn and reach across a network. Without a
+  budget (6s) and a cache (60s connectors, 5min local discovery) one unreachable
+  laptop makes every turn hang — the agent looks broken and nothing in the log
+  says why.
+- **Composio: one request per toolkit.** Repeating `toolkit_slug` in a single
+  `/api/v3/tools` call returns an EMPTY list, so connecting a second service
+  silently emptied the first. The logo is at `meta.logo`, not `logo`. A 200 can
+  still carry `successful: false` — check the body, not the status.
+- **The broker's entity is the agent's REGISTERED name**, not its UUID.
+  `<agent>:<userId>`. Studio knows agents by id; normalize before you ask the
+  broker, or a connected account looks unconnected.
+- **MCP requires the handshake.** `initialize` AND `notifications/initialized`
+  before `tools/list`, or the server never answers. Spawn through a LOGIN shell
+  (a bare spawn misses the user's PATH and node) and always bind
+  `child.on("error")` — without it a failed spawn is an unhandled rejection
+  that takes the process, not a error message.
+- **Translate the MCP/broker inputSchema — never pass an open object.** A tool
+  with no declared arguments makes the model guess: nine calls to find a
+  `file_id` the server had documented all along. `mcpInputSchema` (local) and
+  `toolInputSchema` (connectors) do this; keep them permissive where the server
+  says nothing.
+- **Never wrap a model object in a Proxy.** The AI SDK's model methods depend on
+  their own `this`; intercepting them detaches it and every call dies inside the
+  SDK on a missing internal. To swap a credential, wrap `fetch` instead — and
+  re-read the credential per request: a Grok login expires in six hours and the
+  CLI refreshes it in place.
+- **Credentials are never a user's problem.** No client ever puts a key in a
+  `.env` — broker keys live per-org in the control plane, encrypted at rest, set
+  through an admin screen. A design that ends in "paste this token" is wrong.
 - **npm**: only the `kybernesis` account creates new packages in the scope;
   publishes need the human's browser auth; new versions take 1–3 min to
   propagate to anonymous reads.

package/skills/self-hosting/SKILL.md

@@ -25,7 +25,7 @@ kyb init <name> --host=exe --channel=<imessage|slack|telegram|none> --engineer
 
 | Capability | On Vercel | Self-hosted replacement |
 | --- | --- | --- |
-| Model access | AI Gateway | exe.dev LLM integration (`exeModel`) — managed, BYO key, or a **ChatGPT subscription** |
+| Model access | AI Gateway | exe.dev LLM integration (`exeModel`) — managed, BYO key, or a **ChatGPT / Grok subscription** |
 | Slack/Photon/Linear credentials | Vercel Connect | **Portable/static credentials the client issues** |
 | Sandbox | `vercel()` hosted | `docker()` on the host |
 | File delivery | Vercel Blob | Blob **or** `DELIVER_DIR` + `DELIVER_BASE_URL` |
@@ -38,6 +38,44 @@ Vercel MCP connection, Linear, everything. Each becomes a static credential
 someone must issue and rotate. `kyb doctor` fails loudly if a `@vercel/connect`
 import survives into a self-hosted agent.
 
+## Running on the client's own subscription
+
+A client who already pays for ChatGPT Plus/Pro or SuperGrok / X Premium+ can
+run the agent on it instead of on metered API billing. Both work the same way:
+a CLI performs a device login on the host, writes a credential to the home
+directory, and that credential is a valid bearer for an OpenAI-compatible
+endpoint. eve ships `experimental_chatgpt()` for the first;
+`@kybernesis/exe` ships `grokSubscription()` for the second.
+
+```bash
+# on the host, as the user the agent runs as
+curl -fsSL https://x.ai/cli/install.sh | bash
+grok login          # device flow → ~/.grok/auth.json
+```
+
+```ts title="agent/agent.ts"
+import { createOpenAI } from "@ai-sdk/openai";
+import { grokSubscription } from "@kybernesis/exe";
+
+export default defineAgent({
+  model: grokSubscription({ model: "grok-4.6", createOpenAI }),
+  modelContextWindowTokens: 400_000,
+});
+```
+
+What this arrangement costs you, and it is worth saying to the client:
+
+- **It is per-machine and per-user.** The login belongs to the host's home
+  directory. Moving the agent means logging in again; running it as a different
+  unix user means it cannot see the credential at all.
+- **The token expires in hours** (Grok: six) and the CLI refreshes it in place.
+  Read it per request, never once at boot, or the agent works all afternoon and
+  starts failing authentication at dinner for no reason a user can see.
+- **Nobody has proven unattended refresh over days.** If no one runs `grok` on
+  that host, whether the refresh keeps happening is an open question — and it
+  presents as the agent "breaking".
+- **Ask the vendor's terms question before a client demo**, not after.
+
 ## The failure modes, each of which cost a real session
 
 - **Docker ships disabled on some images.** exe.dev's exeuntu runs
@@ -144,3 +182,20 @@ yesterday's agent. Assert the process started AFTER the build it should serve
 (`scripts/eve-server.sh` and the restart pattern in `@kybernesis/exe` do this).
 Related: a long-lived channel session caches the compiled agent, so start a
 fresh conversation after changing capabilities.
+
+A restart script also has to **serialize** (`flock`, released by the child with
+`9>&-`) and **wait for in-flight turns** — eve does not resume a step killed
+mid-flight, and restarting into a live turn strands the session behind a turn
+that will never finish.
+
+Run restarts **detached** from your ssh connection —
+`setsid nohup bash restart.sh >/tmp/r.log 2>&1 </dev/null &` — or a dropped
+connection SIGHUPs the script halfway through and leaves exactly the mess it
+exists to prevent.
+
+**And measure it correctly.** `pgrep -f 'server/index.mjs'` typed over ssh
+matches the shell running it: the pattern is in that shell's own command line,
+so it reports two servers when there is one. A whole investigation went into a
+phantom "second server" that `ps -eo pid,ppid,args` would have dismissed
+immediately. Inside a script file it is safe; typed at a shell it is not. List
+the matches before you believe the count.