@kybernesis/create 0.15.7 → 0.16.0

package/dist/doctor.js

@@ -9,6 +9,7 @@ import { classifyModelReach } from "./model-reach.js";
 import { countAbandonedRuns } from "./run-store.js";
 import { describeStaleSidecar, newestPackageChange, staleSidecars } from "./stale-sidecar.js";
 import { checkSelfVersion } from "./self-version.js";
+import { envUrlProblems } from "./env-urls.js";
 const MARK = {
     pass: green("✓"),
     warn: yellow("!"),
@@ -215,6 +216,22 @@ export async function doctor() {
     };
     if (!existsSync(envPath))
         add("warn", ".env.local missing", "copy .env.example and fill it");
+    /**
+     * Config that is shaped wrong rather than missing.
+     *
+     * A URL-valued setting with no scheme does not fail at start; it fails inside
+     * whatever background drain uses it, once per turn, forever. The reference
+     * fleet logged 121 of these and lost every analytics event of a deployment
+     * while reporting healthy throughout. The value alone is enough to know, so
+     * this costs nothing and lands before a client's first turn.
+     */
+    const urlProblems = existsSync(envPath) ? envUrlProblems(readFileSync(envPath, "utf8")) : [];
+    for (const problem of urlProblems) {
+        add("fail", `${problem.name} cannot build a request (${problem.reason})`, problem.fix);
+    }
+    if (existsSync(envPath) && urlProblems.length === 0) {
+        add("pass", "every URL-valued setting is an absolute http(s) URL");
+    }
     const githubCheck = githubToolsDoctorCheck(existsSync(join(cwd, "agent/extensions/github.ts")), env);
     if (githubCheck)
         add(githubCheck.verdict, githubCheck.label, githubCheck.detail);
@@ -363,6 +380,20 @@ export async function doctor() {
             add("warn", "@kybernesis/dispatch installed but no edges or dispatch channel found", "see the connect-agents skill");
         }
     }
+    // ── .agent identity (ARP) ──────────────────────────────────────────────
+    // The owner connects the agent from the ARP console; the only thing that
+    // has to be true in this repo is that deliveries get in.
+    if (deps["@kybernesis/identity"]) {
+        if (!existsSync(join(cwd, "agent/channels/arp.ts")))
+            add("warn", "identity: agent/channels/arp.ts missing", "npx eve add @kybernesis/identity  (serves /eve/v1/arp for Connect your agent)");
+        if (eveChannelSrc && !eveChannelSrc.includes("arpAuth("))
+            add("fail", "identity: eve channel has no arpAuth()", "add arpAuth() to the channel's auth list — without it every delivery from a paired agent is a 401");
+        else if (eveChannelSrc)
+            add("pass", "identity: eve channel accepts ARP deliveries (arpAuth)");
+    }
+    else {
+        add("warn", "no .agent identity add-on", "npx eve add @kybernesis/identity — lets the owner connect this agent to a .agent name from the console");
+    }
     // ── self-hosted agents (host !== Vercel) ───────────────────────────────
     // Every check here cost a real debugging session on the first exe.dev
     // deployment. None of them are theoretical.

package/dist/env-urls.d.ts

@@ -0,0 +1,17 @@
+/** Does this name hold a whole URL? */
+export declare function expectsUrl(name: string): boolean;
+export type EnvUrlProblem = {
+    readonly name: string;
+    /** Why it cannot be used to build a request. Never includes the value. */
+    readonly reason: "no scheme" | "not a url" | "not http(s)";
+    readonly fix: string;
+};
+/**
+ * Check one value. Returns undefined when it is fine.
+ *
+ * The value never appears in the result: these files sit beside real secrets
+ * and a diagnostic that echoes them turns a config warning into a leak.
+ */
+export declare function checkEnvUrl(name: string, value: string): EnvUrlProblem | undefined;
+/** Every URL-shaped value in this env text that cannot build a request. */
+export declare function envUrlProblems(text: string): EnvUrlProblem[];

package/dist/env-urls.js

@@ -0,0 +1,79 @@
+import { parseEnv } from "./util.js";
+/**
+ * Environment values that are used to build a URL, and whether they can be.
+ *
+ * An SDK handed `POSTHOG_HOST=eu.i.posthog.com` does not complain at start. It
+ * fails once per turn, forever, inside a background drain: `Failed to parse URL
+ * from eu.i.posthog.com/batch/`. On the reference fleet that was 121 logged
+ * failures and every analytics event of the deployment silently discarded,
+ * while the agent itself looked perfectly healthy. Nothing surfaces it because
+ * nothing that matters to the turn depends on it.
+ *
+ * Hence checking the SHAPE of the value at rest, which costs nothing and finds
+ * it before a client's first turn.
+ */
+/**
+ * Names whose value is unambiguously a whole URL.
+ *
+ * `_HOST` is deliberately NOT here: plenty of them legitimately hold a bare
+ * hostname (`SMTP_HOST`, `PGHOST`, `REDIS_HOST`), and flagging those would make
+ * doctor cry wolf on a correct config.
+ */
+const URL_SUFFIXES = ["_URL", "_ENDPOINT", "_ISSUER"];
+/**
+ * `_HOST` names that specific SDKs use as a base URL, so they do need a scheme.
+ * An allowlist rather than a rule, because only the SDK knows which it is.
+ */
+const BASE_URL_HOSTS = new Set(["POSTHOG_HOST"]);
+/** Does this name hold a whole URL? */
+export function expectsUrl(name) {
+    if (BASE_URL_HOSTS.has(name))
+        return true;
+    return URL_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+/**
+ * Check one value. Returns undefined when it is fine.
+ *
+ * The value never appears in the result: these files sit beside real secrets
+ * and a diagnostic that echoes them turns a config warning into a leak.
+ */
+export function checkEnvUrl(name, value) {
+    const trimmed = value.trim().replace(/^["']|["']$/g, "");
+    if (trimmed === "")
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        // A bare host is by far the common case, and the remedy differs from junk.
+        const bare = /^[a-z0-9.-]+(:\d+)?(\/.*)?$/i.test(trimmed);
+        return {
+            name,
+            reason: bare ? "no scheme" : "not a url",
+            fix: bare
+                ? `${name} has no scheme, so anything built from it fails to parse. Prefix it with https://`
+                : `${name} is not a URL. Set it to an absolute https:// URL.`,
+        };
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        return {
+            name,
+            reason: "not http(s)",
+            fix: `${name} is a ${parsed.protocol.replace(":", "")} URL. Set it to an absolute https:// URL.`,
+        };
+    }
+    return undefined;
+}
+/** Every URL-shaped value in this env text that cannot build a request. */
+export function envUrlProblems(text) {
+    const problems = [];
+    for (const [name, value] of Object.entries(parseEnv(text))) {
+        if (!expectsUrl(name))
+            continue;
+        const problem = checkEnvUrl(name, value);
+        if (problem)
+            problems.push(problem);
+    }
+    return problems;
+}

package/dist/init.d.ts

@@ -39,3 +39,9 @@ export interface InitOptions {
     yes?: boolean;
 }
 export declare function init(rawName: string | undefined, options?: InitOptions): Promise<void>;
+/**
+ * Put `arpAuth()` first in the eve channel's auth walk so ARP Cloud deliveries
+ * are accepted. Returns the new source, the same source when already wired,
+ * or null when the file has no recognisable auth list.
+ */
+export declare function wireArpAuth(src: string): string | null;

package/dist/init.js

@@ -13,7 +13,9 @@ import { MODEL_REACH_ENV, resolveModelScaffold } from "./model-reach.js";
  * host bindings — is opt-in, because assuming them means the FDE deletes files
  * AND undoes real setup work (an Arcana workspace + scoped key per subagent).
  */
-const CORE_ITEMS = ["enterprise", "arcana", "evals"];
+// `identity` gives the agent its .agent name surface: the owner connects it
+// from the ARP console with one click and never touches this repo again.
+const CORE_ITEMS = ["enterprise", "arcana", "evals", "identity"];
 // Official eve-registry limbs installed with the engineer subagent.
 // connection/vercel is Vercel-Connect-backed, so it is VERCEL-HOST ONLY: on a
 // self-hosted agent it cannot get an OIDC token and the agent fails to boot.
@@ -194,6 +196,20 @@ export async function init(rawName, options = {}) {
     }
     console.log(bold("\n3/6  Writing identity, model config, memory mount, and evals …"));
     mkdirSync(join(dir, "agent/instructions"), { recursive: true });
+    // .agent identity: the channel + peers tool came from the registry item;
+    // deliveries need arpAuth() on the eve channel, and the model needs to know
+    // what the ask_<name>_agent tools are. Both are idempotent.
+    writeFileSync(join(dir, "agent/instructions/arp.md"), arpInstructionsMd());
+    {
+        const eveChannelPath = join(dir, "agent/channels/eve.ts");
+        if (existsSync(eveChannelPath)) {
+            const wired = wireArpAuth(readFileSync(eveChannelPath, "utf8"));
+            if (wired)
+                writeFileSync(eveChannelPath, wired);
+            else
+                console.log(yellow("  ! agent/channels/eve.ts: could not add arpAuth() — add it to the channel's auth list by hand"));
+        }
+    }
     writeFileSync(join(dir, "agent/instructions/identity.md"), identityMd(displayName, depts));
     try {
         unlinkSync(join(dir, "agent/instructions.md"));
@@ -398,3 +414,35 @@ ${steps.map((s, i) => `  ${i + 1}. ${s}`).join("\n")}
 ${dim("  Add more later: kyb add channel <kind> · kyb add subagent <name>")}
 `);
 }
+/**
+ * Put `arpAuth()` first in the eve channel's auth walk so ARP Cloud deliveries
+ * are accepted. Returns the new source, the same source when already wired,
+ * or null when the file has no recognisable auth list.
+ */
+export function wireArpAuth(src) {
+    if (src.includes("arpAuth("))
+        return src;
+    const lines = src.split("\n");
+    const lastImport = lines.reduce((acc, l, i) => (l.startsWith("import ") ? i : acc), -1);
+    lines.splice(lastImport + 1, 0, 'import { arpAuth } from "@kybernesis/identity";');
+    let out = lines.join("\n");
+    const comment = "// Deliveries from paired .agent peers: a per-message token ARP Cloud signs,\n    // verified offline against its JWKS; skips to the next entry otherwise.";
+    if (/extraAuth:\s*\[/.test(out))
+        return out.replace(/extraAuth:\s*\[/, `extraAuth: [\n    ${comment}\n    arpAuth(),`);
+    if (/\bauth:\s*\[/.test(out))
+        return out.replace(/\bauth:\s*\[/, `auth: [\n    ${comment}\n    arpAuth(),`);
+    return null;
+}
+function arpInstructionsMd() {
+    return `## Your .agent identity
+
+You have a registered name on the agent network. Other agents that are paired
+with you appear as \`ask_<name>_agent\` tools (the name is their .agent name; a
+plain \`ask_<name>\` tool, if present, is a different, non-network peer); use
+them when a request belongs to that agent rather than to you. When a message
+arrives from a paired agent, the caller's identity has already been verified
+and the message has already been checked against what its owner allowed —
+answer it as you would a trusted colleague, and honour any obligations
+attached (for example, do not include fields you were told to redact).
+`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.15.7",
-  "description": "The Kybernesis agent scaffolder and FDE toolkit: one command to a governed, remembering, multiplayer, self-testing eve agent — plus doctor and upgrade.",
+  "version": "0.16.0",
+  "description": "The Kybernesis agent scaffolder and FDE toolkit: one command to a governed, remembering, multiplayer, self-testing eve agent \u2014 plus doctor and upgrade.",
   "license": "Apache-2.0",
   "type": "module",
   "homepage": "https://kybernesis.ai",
@@ -46,5 +46,6 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "peerDependencies": {}
 }

package/skills/self-hosting/SKILL.md

@@ -86,6 +86,31 @@ What this arrangement costs you, and it is worth saying to the client:
   presents as the agent "breaking".
 - **Ask the vendor's terms question before a client demo**, not after.
 
+### A Claude subscription expires on a ~28-day clock, and lies on the way out
+
+Claude is the third provider and behaves differently enough to plan around.
+Grok and ChatGPT are a file a CLI keeps fresh; Claude is a **proxy process**
+holding Claude Code's own OAuth (`scripts/claude-subscription.sh` in
+`@kybernesis/exe`). Two things follow, both learned on Sid:
+
+- **The sign-in has a hard expiry of about 28 days.** The access token refreshes
+  hourly and does so happily the whole time, which tells you nothing — the
+  *refresh* token underneath carries its own fixed expiry, and using it does not
+  extend it. On expiry the proxy blanks the credential file to empty strings and
+  every turn 401s. Only `login` recovers it; `reload` and restarts cannot.
+  **Diary the re-login for every subscription-backed agent you deploy.**
+- **`/ready` cannot see a dead credential.** It reports that a credential was
+  *loaded*, not that it is *valid*, so it answers 200 over a blanked file while
+  the API 401s — `status` read "signed in, answering" straight through an
+  outage. `status` now probes `/v1/models` as well and warns from the refresh
+  expiry (`✓ sign-in valid for 27d`, escalating at 7 and 3 days). Run it on a
+  schedule; the failure is silent and looks like a model outage, so people go
+  and read Anthropic's status page instead of opening a browser.
+
+Say the re-login cadence out loud to a client before it strands their agent at
+a weekend. It is the one piece of operational debt this arrangement creates in
+exchange for not billing metered API usage.
+
 ## The failure modes, each of which cost a real session
 
 - **`EXE_MODEL` is deliberately empty after `kyb init`.** Set it from the