@kybernesis/create 0.2.0 → 0.3.1

package/dist/doctor.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { bold, capture, dim, green, parseEnv, red, yellow } from "./util.js";
 const MARK = {
@@ -45,10 +45,13 @@ export async function doctor() {
     if (env.ARCANA_API_KEY && env.ARCANA_COMPANY_WORKSPACE)
         arcanaPairs.push({ key: env.ARCANA_API_KEY, ws: env.ARCANA_COMPANY_WORKSPACE, label: "company brain" });
     if (env.ARCANA_EVAL_API_KEY) {
-        const evalWs = /ARCANA_COMPANY_WORKSPACE=([a-z0-9-]+)-eval|([a-z0-9-]+)-eval/.exec(pkg.scripts?.eval ?? "");
-        const ws = evalWs?.[1] ? `${evalWs[1]}-eval` : evalWs?.[2] ? `${evalWs[2]}-eval` : null;
-        if (ws)
-            arcanaPairs.push({ key: env.ARCANA_EVAL_API_KEY, ws, label: "eval workspace" });
+        // Match both `WORKSPACE=name-eval` and the shell-default form
+        // `WORKSPACE=${ARCANA_EVAL_WORKSPACE:-name-eval}`.
+        const script = pkg.scripts?.eval ?? "";
+        const evalWs = /=\$\{[A-Z0-9_]+:-([a-z0-9][a-z0-9-]*-eval)\}/.exec(script) ??
+            /=([a-z0-9][a-z0-9-]*-eval)\b/.exec(script);
+        if (evalWs?.[1])
+            arcanaPairs.push({ key: env.ARCANA_EVAL_API_KEY, ws: evalWs[1], label: "eval workspace" });
     }
     for (const [k, v] of Object.entries(env)) {
         const m = /^ARCANA_([A-Z0-9_]+)_API_KEY$/.exec(k);
@@ -120,6 +123,51 @@ export async function doctor() {
         else
             add("warn", "no VERCEL_OIDC_TOKEN — local sandbox/eval runs cannot reach Vercel Sandbox", "vercel link && vercel env pull");
     }
+    // ── dispatch edges (agent-to-agent — checked only when present) ────────
+    const subagentsDir = join(cwd, "agent/subagents");
+    const edgeFiles = [];
+    if (existsSync(subagentsDir)) {
+        for (const entry of readdirSync(subagentsDir)) {
+            const flat = join(subagentsDir, entry);
+            const nested = join(subagentsDir, entry, "agent.ts");
+            const path = entry.endsWith(".ts") ? flat : existsSync(nested) ? nested : null;
+            if (!path)
+                continue;
+            const src = readFileSync(path, "utf8");
+            if (src.includes("remotePeer") || src.includes("defineRemoteAgent"))
+                edgeFiles.push(path);
+        }
+    }
+    const eveChannelPath = join(cwd, "agent/channels/eve.ts");
+    const eveChannelSrc = existsSync(eveChannelPath) ? readFileSync(eveChannelPath, "utf8") : null;
+    const hasDispatch = Boolean(deps["@kybernesis/dispatch"]) || edgeFiles.length > 0 ||
+        Boolean(eveChannelSrc && (eveChannelSrc.includes("dispatchChannel") || eveChannelSrc.includes("trustedForwarders")));
+    if (hasDispatch) {
+        for (const path of edgeFiles) {
+            const src = readFileSync(path, "utf8");
+            const name = path.split("/agent/subagents/")[1];
+            const envVar = /envVar:\s*"([A-Z0-9_]+)"/.exec(src)?.[1] ?? /process\.env\.([A-Z0-9_]+)/.exec(src)?.[1];
+            if (!envVar)
+                add("warn", `dispatch edge ${name}: no env-var URL found`, "use remotePeer({ envVar }) so the target is repointable");
+            else if (env[envVar])
+                add("pass", `dispatch edge ${name} → $${envVar} set locally`, "confirm it's also set on the Vercel project");
+            else
+                add("warn", `dispatch edge ${name}: $${envVar} unset locally`, `printf "<peer-url>" | vercel env add ${envVar} production (and vercel env pull)`);
+            if (src.includes("defineRemoteAgent") && !src.includes("forwardPrincipal"))
+                add("warn", `dispatch edge ${name}: forwardPrincipal not set`, "peer will see this app's service identity, not the human — use remotePeer() for the safe defaults");
+        }
+        if (edgeFiles.length > 0)
+            add("warn", "dispatch: verify BOTH ends run compatible eve versions", "an old receiver silently drops forwardPrincipal (runs as service identity)");
+        if (eveChannelSrc) {
+            if (/trustedForwarders:\s*(\(\s*\)|\([^)]*\))\s*=>\s*true/.test(eveChannelSrc))
+                add("fail", "eve channel: trustedForwarders is () => true", "any authenticated caller can assert any identity — enumerate peers (dispatchChannel)");
+            else if (eveChannelSrc.includes("dispatchChannel") || eveChannelSrc.includes("trustedForwarders"))
+                add("pass", "eve channel accepts forwarded principals from enumerated peers only");
+        }
+        else if (Boolean(deps["@kybernesis/dispatch"]) && edgeFiles.length === 0) {
+            add("warn", "@kybernesis/dispatch installed but no edges or dispatch channel found", "see the connect-agents skill");
+        }
+    }
     // ── eve discovery + local port ─────────────────────────────────────────
     const info = capture("npx", ["eve", "info"], cwd);
     if (info === null)

package/dist/upgrade.js

@@ -5,6 +5,8 @@ const PACKAGES = [
     "@kybernesis/arcana",
     "@kybernesis/enterprise",
     "@kybernesis/multiplayer",
+    "@kybernesis/engineer",
+    "@kybernesis/dispatch",
     "@kybernesis/evals",
 ];
 function versionLt(a, b) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",
@@ -40,5 +40,8 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/skills/certification/SKILL.md

@@ -33,7 +33,23 @@ model under test.
 - Stale sandbox state (migration errors, re-baking templates):
   `rm -rf .eve/sandbox-cache .eve/dev-runtime` and rerun.
 - Don't pipe the eval command through `tail` in scripts — it masks the exit
-  code.
+  code (and `| tail -N` on a backgrounded run destroys the per-eval detail —
+  `tee` to a file instead).
+- **Heavy-model suites: `maxConcurrency: 1` locally.** At 2, long opus turns
+  overload the local world-queue transport (`Queue delivery failed … fetch
+  failed`); crashed deliveries REPLAY subagent steps, surfacing as
+  `lost continuationToken` races and phantom failures that move between runs.
+  The deployed runtime uses real queue infra — this is a local-harness limit.
+- **AI Gateway budget is a silent eval killer**: Vercel applies a default
+  per-project budget (e.g. $10/daily); a suite of real opus turns can exhaust
+  it MID-RUN → `MODEL_CALL_FAILED` on whatever ran last. Check/raise:
+  `vercel ai-gateway budgets list` / `budgets set project <name> --limit 30
+  --refresh-period monthly`.
+- **"run parked on N unanswered input request(s)"** = the agent called a
+  human-in-the-loop tool (`approval: status=pending tool=ask_question` in the
+  turn log) — no one answers in an eval. Usually a behavior finding: the
+  fixture was self-contained and the agent asked instead of acting. Fix the
+  agent's bias-to-act instructions, not the fixture.
 
 ## eve version certification
 

package/skills/connect-agents/SKILL.md

@@ -0,0 +1,92 @@
+---
+description: Use when connecting two deployed eve agents so one can delegate to the other — "connect agent A to agent B", agent-to-agent communication, remote peers, cross-deployment delegation. Wires @kybernesis/dispatch edges end to end.
+---
+
+# Connecting two eve agents (@kybernesis/dispatch)
+
+An **edge** lets one deployed eve agent call another as if it were a local
+subagent, with the human's identity carried across the hop. One edge covers a
+full question-and-answer round trip (the caller parks until the peer's callback
+returns). Wire the mirror-image edge only if the other agent should also be
+able to *initiate*.
+
+## Before wiring — gather the facts
+
+1. **Both repos' eve versions must be compatible** (`node_modules/eve/package.json`
+   in each). An old receiver silently drops principal forwarding and runs as
+   service identity — no error. Upgrade both ends together first if they differ.
+2. **Vercel identities** of both projects: team slug + project name as shown in
+   `npx vercel ls <project>` (slugs, not `team_…`/`prj_…` IDs).
+3. **Stable production URL** of the callee: `npx vercel inspect <latest-prod-url>`
+   → Aliases — then **verify the alias is OPEN before wiring it**:
+   `curl -s -o /dev/null -w "%{http_code}" <url>/eve/v1/health` must return
+   **200**. The `<project>-<team>.vercel.app` aliases commonly sit behind
+   Vercel SSO deployment protection (302 → vercel.com/sso-api) and CANNOT
+   receive dispatches; the shorter production alias is usually the open one.
+4. Both repos need `@kybernesis/dispatch` installed (`npm i @kybernesis/dispatch`).
+
+## Caller side — one file
+
+`agent/subagents/<peer-name>.ts` (file name = tool name the model routes to):
+
+```ts
+import { remotePeer } from "@kybernesis/dispatch";
+
+export default remotePeer({
+  envVar: "GTM_AGENT_URL",
+  description: "…",   // see below — this is the whole routing story
+});
+```
+
+**Write the description from the CALLEE's actual capabilities.** Read the peer
+repo's `agent/instructions*`, subagent descriptions, and skills, then write the
+concrete topics people ask about ("posting cadence, open GTM plays, outreach
+targets, content drafting in the house voice") — not a generic blurb. If the
+caller has local subagents with overlapping remits, differentiate explicitly or
+routing will be ambiguous.
+
+Set the env var on the caller's Vercel project:
+`printf "<stable-prod-url>" | npx vercel env add GTM_AGENT_URL production`
+
+## Receiver side — one file
+
+`agent/channels/eve.ts` on the callee:
+
+```ts
+import { dispatchChannel } from "@kybernesis/dispatch";
+
+export default dispatchChannel({
+  trustedPeers: [{ teamSlug: "<caller-team>", projectName: "<caller-project>" }],
+});
+```
+
+If the callee already has an authored `agent/channels/eve.ts` with app auth,
+either migrate it to `dispatchChannel({ trustedPeers, extraAuth: […] })` or add
+the peer by hand to BOTH the `vercelOidc({ subjects })` list and the
+`trustedForwarders` predicate — they must never drift apart. Never write
+`trustedForwarders: () => true`.
+
+## Verify
+
+1. `npx eve info` in both repos: 0 diagnostics; the caller's manifest gains a
+   `remoteAgents` entry (it does NOT appear in the local subagent count).
+2. `npm run typecheck` both.
+3. Deploy BOTH (`npx eve deploy` / git push per repo convention). The edge is
+   live only when both ends are.
+4. Live test from the caller's real surface (e.g. Slack): ask something only
+   the peer knows. Confirm delegation in the caller's reply, then check
+   telemetry (PostHog): the peer-side turn should carry the human's
+   distinct_id, plus the `eve:forwarded-by` attribute naming the caller.
+
+## Failure signatures
+
+- **403 on dispatch** → receiver has no authored eve channel, or the caller
+  isn't in `trustedPeers`. Check team slug/project name spelling — a typo
+  silently rejects everything.
+- **`principal_required` on the peer's user-scoped connections** → forwarding
+  isn't arriving: receiver predates forwarding, or the assertion was dropped.
+- **Peer never gets called** → routing description too vague, or it collides
+  with a local subagent's remit. Rewrite from the callee's real capabilities.
+- **Works locally, 401 in production** → caller's OIDC not accepted: the
+  receiver's `trustedPeers` names the wrong environment (default is
+  production-only) or wrong project.

package/skills/eve-building/SKILL.md

@@ -85,6 +85,18 @@ Inherit NOTHING. Own tools/skills/connections/instructions/sandbox; on eve
 into that subagent). No channels/schedules; no user principal; whole job must
 fit one delegation call. Docs: `docs/subagents.mdx`.
 
+**Sandbox layout trap:** a FLAT `agent/sandbox.ts` is discovered but scopes to
+the ROOT agent only — subagents silently fall back to the default backend
+chain (Docker → microsandbox → just-bash), which surfaces as
+`opening sandbox session "subagents/<id>" on backend "docker"` in eval logs.
+Use the directory form `agent/sandbox/sandbox.ts` — that one is app-level and
+subagents get it free. (Cost a debugging session on eve-gtm, 2026-08-07.)
+
+**Parallel same-subagent delegation collides** (`Session … lost
+continuationToken … to session …`, failed subagent-result actions): two
+delegations to the SAME subagent fired in one step race on child sessions.
+Instruct serial delegation ("one draft at a time, wait for each result").
+
 ## Test in eve dev
 
 `npx eve dev` boots the local runtime + chat TUI. Walk: identity → skill

package/skills/fde-engagement/references/playbook.md

@@ -866,6 +866,43 @@ diff before running the agent**, same as any dependency. For client work,
 prefer authoring the client's own procedures; pull from skills.sh for generic
 craft (framework best practices, review checklists) after review.
 
+### 4.3f Install `@kybernesis/dispatch` (optional — when the client runs MORE THAN ONE agent)
+
+When the client has (or grows into) a second deployed agent — an ops agent
+next to the company assistant, a specialist per business unit — they will ask
+for the agents to talk to each other. Dispatch is the governed way: one
+declared **edge** per direction, human identity carried across the hop.
+
+The concept in one breath: the caller mounts the peer as a remote subagent
+(`remotePeer` under `agent/subagents/` — eve's `defineRemoteAgent` underneath,
+durable park→callback dispatch, so a reply comes back on the SAME edge); the
+receiver authors `agent/channels/eve.ts` with `dispatchChannel({ trustedPeers })`,
+which feeds one peer list into BOTH the OIDC subjects allowlist and
+`trustedForwarders`. Forwarding is on by default: the receiving agent runs as
+the human who asked, so Arcana scoping, per-user connections, and PostHog
+attribution compose across the hop unchanged (`eve:forwarded-by` records the
+edge for audit).
+
+**Don't hand-wire it — use the `connect-agents` Claude Code skill** (in the
+seeded `.claude/skills/`): tell Claude "connect <agent A> to <agent B>" and it
+reads both repos, writes the edge with a routing description derived from the
+callee's REAL capabilities, sets the URL env var, and walks the deploy+verify
+steps. `kyb doctor` then checks the edges (env var set, no `() => true`
+trust, forwardPrincipal present).
+
+Client-conversation rules of thumb:
+
+- One edge = ask-and-answer in one direction. Mirror-image edge only if the
+  other agent should also INITIATE. Quote them separately.
+- **Both ends must run compatible eve versions** — an old receiver silently
+  drops principal forwarding and runs the session as the calling app's
+  service identity. Upgrade edges as a unit (`kyb upgrade` both repos).
+- Peers are pinned to production deployments of named Vercel projects.
+  Previews never get trust implicitly. The client's Vercel team is still the
+  outer boundary, same as §4.3b.
+- Cross-ORG edges (client agent ↔ another company's agent) are a different
+  product conversation — purpose-scoped grants, §2.5 disclosures. Don't wire
+  one as if it were internal.
 
 ### 4.4 Author the agent's identity and instructions
 
@@ -1009,6 +1046,44 @@ result to a configured Slack user. Note that DMing a user from a schedule needs
 `im:write` scope on the Slack connector — add it during Phase 5 or the first run fails
 silently at the last step.
 
+### 4.6b Observability — evlog → PostHog (the Operate-phase deliverable)
+
+One hook file gives the agent per-turn structured telemetry — who talked,
+which tools/subagents fired, timings, token usage, outcome — with message
+text redacted and tool-failure turns always kept:
+
+```ts
+// agent/hooks/evlog.ts
+import { defineEvlogHook } from "evlog/eve";
+import { createPostHogDrain } from "evlog/posthog";
+
+export default defineEvlogHook({
+  init: { env: { service: "acme-atlas" } },
+  // mode "events" is REQUIRED for dashboards: the default "logs" mode
+  // ships OTLP to the separate PostHog Logs product — invisible to
+  // Activity/insights, and it looks exactly like "no events arriving".
+  drain: createPostHogDrain({ mode: "events" }),
+  redactMessage: true,
+});
+```
+
+Env: `POSTHOG_API_KEY` = the **project** key (`phc_…`, ingestion-only — a
+`phx_…` personal key is account-privileged and wrong here). The default host
+is `https://us.i.posthog.com`; EU-hosted projects need
+`POSTHOG_HOST=https://eu.i.posthog.com` or events silently vanish. To verify
+region + key in one shot, curl a test event at each region's `/batch/` and
+see which appears in Activity. Turns then land as `evlog_wide_event` — build
+the starter insights on its properties: turns/day by surface, tool failure
+rate, delegation mix, p50/p95 duration.
+
+**Person attribution (optional — a DISCLOSURE item, §2.5):** wide events carry no
+userId by default, so PostHog sees one anonymous actor named after the service. To
+attribute turns to the verified speaker, add a sibling hook that stamps the
+per-message-authenticated principal via evlog's `useLogger` — on `step.started`, not
+`turn.started`, so evlog's turn state exists regardless of hook ordering (crib
+`~/kyber/agent/hooks/attribution.ts`). Then a one-time $identify per person maps ids
+to names. Per-employee telemetry must be a deliberate, disclosed choice at a client.
+
 ### 4.7 Environment variables
 
 Two places must agree: `.env.local` for local development, and the Vercel project's

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), 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), evals (QA), create (kyb CLI) — or the Kybernesis registry. Includes every production-learned gotcha.
 ---
 
 # The Kybernesis packages
 
-Six packages, npm-public under `@kybernesis`, Apache-2.0, monorepo
+Seven 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:
@@ -38,6 +38,17 @@ then `eve add @kybernesis/<item>`). Each covers one axis:
   domain allowlist = the client's security posture. Ship loop: preview deploys
   via the Vercel MCP connection (inline file tree, no git needed, no token in
   the VM); production promotion is ALWAYS human-approved.
+- **dispatch** — agent-to-agent. `remotePeer({ envVar, description })` under
+  `agent/subagents/` = a separately DEPLOYED eve agent as a callable peer
+  (eve's `defineRemoteAgent` underneath: durable park→callback dispatch);
+  `dispatchChannel({ trustedPeers, extraAuth? })` as `agent/channels/eve.ts` =
+  the receiver, one declaration feeding BOTH the OIDC subjects allowlist and
+  `trustedForwarders`. Principal forwarding ON by default — the peer runs as
+  the human who asked. `() => true` trust is not expressible. Peers are
+  production-environment by default. BOTH ends must run compatible eve
+  versions (old receivers silently drop forwarding → service identity).
+  Composes with enterprise via `extraAuth: [kybernesisAuth(...)]`. See the
+  `connect-agents` skill for the end-to-end wiring flow.
 - **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