@kynver-app/runtime 0.2.23 → 0.2.24

package/README.md

@@ -1,33 +1,49 @@
 # @kynver-app/runtime
 
-Standalone Kynver AgentOS execution runtime and CLI (`kynver`).
+Standalone Kynver AgentOS execution runtime and CLI (`kynver`) — run Kynver's agent harness on **your own machine**, on your own provider subscriptions. Provider credentials stay local to the box; the daemon talks to Kynver over scoped, revocable `krc1.*` runner tokens.
 
-## Supported Node.js
+## Requirements
 
-The Kynver fleet runs **Node.js 24.11.0+** (npm 11). The `0.1.x` line still
-declares `engines >=18` for compatibility, but new runner hosts should install
-Node 24 — the coming `0.2.0` release raises the enforced floor to `>=24.11.0`
-and startup will fail closed below it. Check any host with:
+- **Node.js 24.11.0+** (npm 11). This is a hard engine floor: below it the CLI **fails closed at startup** — every work-executing command refuses to run, and only `--version` and the `doctor` diagnostic commands stay reachable for diagnosis. Check any host with:
+
+  ```bash
+  kynver doctor node-runtime   # report-only JSON classification + remediation
+  ```
+
+- A worker-provider CLI on PATH with an active login/subscription (see [Worker providers](#worker-providers)).
+- **Agentic OS access** on your Kynver account. Access is **admin-approved**: if `kynver bootstrap` reports that your account has no access, request it at <https://www.kynver.com/agent-os/early-access> — once approved, your account works here with no further changes (just re-run `kynver bootstrap`).
+
+## Quick start
 
 ```bash
-kynver doctor node-runtime   # report-only JSON classification + remediation
+npm install -g @kynver-app/runtime
+kynver bootstrap --api-base-url https://www.kynver.com
+kynver start
 ```
 
-## Quick start
+That is the whole golden path: `bootstrap` links this machine to your account and workspace; `start` brings the agent online (keeper-supervised daemon — Ctrl-C stops it). For a persistent background agent on Linux: `kynver start --install-systemd`.
+
+### What `kynver bootstrap` does
+
+1. **Device login** — prints a URL and a short code; approve in the browser. No API-key pasting; the minted key is saved to `~/.kynver/credentials`.
+2. **Workspace resolution** — resolves your account's primary AgentOS workspace. If the account is not approved for Agentic OS yet, bootstrap says so and links the request page (see Requirements above).
+3. **Machine setup** — persists `~/.kynver/config.json` (API base URL, workspace id, repo discovery, worker caps, box identity) and mints a scoped `krc1.*` runner credential.
+
+Bootstrap does **not** start any work — bringing workers online is `kynver start`.
+
+### Troubleshooting → `kynver doctor runner-install`
+
+If `bootstrap` or `start` fails, or the agent seems dead:
 
 ```bash
-npm run kynver:build
-npm run kynver -- setup --api-base-url http://localhost:3000 --agent-os-id <id> [--repo /path/to/repo] --max-workers 13
-npm run kynver -- login --api-key "$KYNVER_API_KEY"
-npm run kynver -- runner credential --agent-os-id <id>
-npm run kynver -- config ensure-default-repo   # persist defaultRepo in ~/.kynver/config.json
-npm run kynver -- run create [--repo /path/to/repo] --name my-run
-npm run kynver -- daemon --run <runId> --agent-os-id <id> --execute
+kynver doctor runner-install
 ```
 
+It walks the whole first-run lifecycle — install, device login, workspace binding, repo selection, runner credential, daemon liveness — plus the first-run blockers: worker-provider CLI on PATH, `boxKind` identity, repo base ref (`origin/main` / remote default branch), and live API reachability/auth (a 401 means a revoked key → `kynver login`; a 403 means access is gated → request it at the early-access page). Every failing check carries the exact command that fixes it.
+
 ### Callback auth (scoped runner tokens)
 
-User-hosted runners should **not** use deployment-wide `OPENCLAW_CRON_SECRET` / `KYNVER_RUNTIME_SECRET`. After `kynver login`, mint a workspace-bound token:
+User-hosted runners should **not** use deployment-wide `OPENCLAW_CRON_SECRET` / `KYNVER_RUNTIME_SECRET`. `kynver bootstrap` mints a workspace-bound token automatically; to re-mint one:
 
 ```bash
 kynver runner credential --agent-os-id <id>
@@ -40,12 +56,15 @@ Global env secrets are accepted on by-id callbacks **only** when the deployment
 ## CLI verbs
 
 ```text
+bootstrap | start | status | setup | login | daemon
 run create | list | status | dispatch | sweep
 worker start | status | tail | stop | complete
-login | runner credential | setup | config ensure-default-repo | doctor runtime-takeover | daemon
+runner credential [mint|status|list|revoke|rotate]
+config ensure-default-repo
+doctor runner-install | node-runtime | local-store | context-envelope | runtime-takeover
 ```
 
-`scripts/opus-harness.mjs` is a compatibility shim that delegates to this package.
+Run `kynver help` for the full flag-level usage. `scripts/opus-harness.mjs` is a compatibility shim that delegates to this package.
 
 ## Worker providers
 
@@ -63,6 +82,21 @@ Install Cursor CLI (Windows PowerShell): `irm 'https://cursor.com/install?win32=
 
 Default Cursor model: `composer-2.5`. Override with `--model` on dispatch/worker start.
 
+## Advanced / monorepo development
+
+Power users and monorepo contributors can drive the harness explicitly instead of `kynver start` (from the Kynver repo root, `npm run kynver -- <verb…>` invokes the workspace build):
+
+```bash
+kynver setup --api-base-url http://localhost:3000 --agent-os-id <id> [--repo /path/to/repo] --max-workers 13
+kynver login --api-key "$KYNVER_API_KEY"
+kynver runner credential --agent-os-id <id>
+kynver config ensure-default-repo   # persist defaultRepo in ~/.kynver/config.json
+kynver run create [--repo /path/to/repo] --name my-run
+kynver daemon --run <runId> --agent-os-id <id> --execute
+```
+
+New runs are cut from `origin/main`; when that ref does not exist the run falls back to the remote default branch (`origin/HEAD`), and `--base <ref>` / `KYNVER_RUN_BASE_REF` / `defaultBase` in `~/.kynver/config.json` override the base explicitly.
+
 ### Targeted dispatch (after creating a board task)
 
 Broad `lane:any` dispatch still sweeps the ready queue (review lane first, then priority/age). To start **one specific task** you just created — without admitting an older ready row — pass the task id:

package/dist/bootstrap.d.ts

@@ -1 +1,49 @@
+interface PrimaryAgentOs {
+    id: string;
+    slug: string;
+}
+/**
+ * Workspace resolution outcome, discriminated so the CLI can tell "your
+ * account is not approved for Agentic OS" (HTTP 401/403 — a human/approval
+ * problem) apart from "the network/server is unhappy" (a retry problem).
+ */
+export type PrimaryAgentOsResult = {
+    ok: true;
+    primary: PrimaryAgentOs;
+} | {
+    ok: false;
+    kind: "access_denied";
+    status: number;
+} | {
+    ok: false;
+    kind: "no_workspace";
+    status: number;
+} | {
+    ok: false;
+    kind: "server_error";
+    status: number;
+} | {
+    ok: false;
+    kind: "network";
+    detail: string;
+};
+/** Where a gated account requests Agentic OS access (admin-approved). */
+export declare function agentOsAccessRequestUrl(base?: string): string;
+/**
+ * The access-gated message: Agentic OS access is admin-approved, so a 401/403
+ * here is not a bug on the user's box — it means the account needs approval.
+ */
+export declare function formatAgentOsAccessGatedMessage(base?: string): string;
+/** The retry-oriented message for network/transport failures (not an access problem). */
+export declare function formatBootstrapNetworkErrorMessage(base: string, detail: string): string;
+/** Resolve the account's primary AgentOS workspace (id + slug) via GET /api/agent-os. */
+export declare function fetchPrimaryAgentOs(base: string, apiKey: string, fetchImpl?: typeof fetch): Promise<PrimaryAgentOsResult>;
+/**
+ * Classify a runner-credential mint failure by its error message.
+ * `fetchRunnerCredential` embeds the HTTP status as `(NNN)`; 401/403 mean the
+ * account/workspace is gated or the key was revoked — an approval problem the
+ * early-access page solves, not something a retry fixes.
+ */
+export declare function classifyRunnerCredentialMintError(message: string): "access_denied" | "transient";
 export declare function runBootstrap(args: Record<string, string | boolean>): Promise<void>;
+export {};

package/dist/cli.d.ts

@@ -1,3 +1,14 @@
 #!/usr/bin/env node
+/**
+ * Every routable CLI verb path, exactly as `main()` dispatches them. This is
+ * the docs-truth contract: the README + user-hosted-runner runbook tests pin
+ * every `kynver <verb…>` command they mention against this list, so a doc can
+ * never again teach a command that does not exist (`kynver runner start`,
+ * bare `kynver doctor`, `kynver selftest`). Keep in lockstep with the
+ * scope/action routing in `main()` below.
+ */
+export declare const KNOWN_CLI_VERBS: readonly string[];
+/** Snapshot of {@link KNOWN_CLI_VERBS} for docs-truth tests and tooling. */
+export declare function listKnownCliVerbs(): string[];
 export declare function usage(code?: number): never;
 export declare function main(argv?: string[]): Promise<void>;