kairos-cli 0.0.4 → 0.0.5

package/README.md

@@ -1,53 +1,79 @@
 # kairos-cli
 
-The local command-line bridge for KairOS AI tools.
+Local command-line bridge for KairOS AI tools.
 
-`kairos-cli` lets an AI agent (or you) authenticate once and then call KairOS tools from your machine.
-
-## Install
+**AI agents** need this CLI **and** the **kairos-skill** skill on [skills.sh](https://skills.sh):
 
 ```bash
 npm install -g kairos-cli
 ```
 
+Add **kairos-skill** using the `npx skills add …` command from the user's KairOS **Dashboard → Connect your AI agent** (each host includes the correct GitHub source).
+
 ## Authenticate
 
 ```bash
 kairos login --api-url https://your-kairos-url.com
-kairos whoami
+kairos whoami    # expect: Token valid: yes
 ```
 
-`kairos login` opens a browser consent flow and stores local credentials for future calls.
+`kairos login` opens a browser consent flow (or prints a URL with `--no-open`) and stores credentials at `~/.config/kairos/credentials.json`.
+
+| Flag              | Purpose                                             |
+| ----------------- | --------------------------------------------------- |
+| `--api-url <url>` | KairOS app URL; stored in credentials               |
+| `--no-open`       | Print URL only — for agents / headless environments |
+| `--timeout <sec>` | Max wait for authorize (default 300, minimum 30)    |
 
-## Common commands
+Default API URL: `KAIROS_API_URL` env, else `https://kairos.querobines.com`. Stored `api_url` in credentials wins for later commands.
+
+## Commands
 
 ```bash
+kairos logout
 kairos tools
 kairos call query_today '{}'
 kairos call query_tasks '{"activeOnly":true}'
 kairos call create_task '{"title":"Follow up","status":"todo"}'
 ```
 
-## Command summary
+- `kairos call <toolName> '<json>'` — invoke a tool (requires valid token)
+- Tool names and payloads: in **kairos-skill** (`references/tools.md` after install)
+
+## Credentials
 
-- `kairos login [--api-url <url>] [--no-open] [--timeout <seconds>]`
-- `kairos logout`
-- `kairos whoami`
-- `kairos tools`
-- `kairos call <toolName> '<json>'`
+`~/.config/kairos/credentials.json` (file mode `600`):
+
+```json
+{
+  "api_url": "https://your-kairos-url.com",
+  "access_token": "<jwt>",
+  "expires_at": "2026-05-18T12:00:00.000Z"
+}
+```
+
+v1 has **no refresh token** (~1 hour JWT). Re-run `kairos login` when `Token valid: no` or tools return **401**.
 
 ## Troubleshooting
 
-- `Not authenticated. Run: kairos login`
-  - Run `kairos login` again to refresh credentials.
-- Login opened the wrong environment
-  - Re-run with explicit URL: `kairos login --api-url https://your-kairos-url.com`
-- Agent/non-browser environment
-  - Use `kairos login --no-open`, copy the printed URL, open it manually, then approve.
+| Symptom                                | Fix                                                 |
+| -------------------------------------- | --------------------------------------------------- |
+| `Not authenticated. Run: kairos login` | Missing or expired credentials — login again        |
+| `Token valid: no`                      | JWT past `expires_at` — `kairos login`              |
+| Login silent after URL                 | Waiting for **Authorize** in browser — check stderr |
+| `Login timed out after Ns`             | Re-run login; authorize within timeout              |
+| `fetch failed` / wrong data            | Wrong host — `kairos login --api-url <correct>`     |
+| Redirect to `/login` on consent page   | Sign in on the web app first, then authorize        |
+| `CODE_EXPIRED` / `PKCE_INVALID`        | Fresh login; use the **latest** printed URL only    |
+| Tool **401**                           | `kairos login`                                      |
+
+Agent-driven login (`--no-open`, do not background): see `references/auth.md` in **kairos-skill**.
 
 ## Local development (monorepo)
 
-From the monorepo root:
+> **Maintainers:** Keep customer-facing sections free of repo-internal links (`docs/`, monorepo paths). Monorepo notes below only.
+
+Skill source (before skills.sh publish): `packages/kairos-skill/` · sync with `pnpm skill:sync` from repo root.
 
 ```bash
 pnpm cli:build

package/dist/auth/loopback.d.ts

@@ -1,6 +1,6 @@
 /** Default wait for browser consent (matches server auth code TTL). */
 export declare const DEFAULT_LOGIN_TIMEOUT_MS: number;
-/** stderr heartbeat while waiting for loopback callback (documented in docs/cli-auth.md §7). */
+/** stderr heartbeat while waiting for loopback callback (`kairos login --no-open`). */
 export declare const LOGIN_HEARTBEAT_MS = 15000;
 /** Minimum `kairos login --timeout` value (seconds). */
 export declare const MIN_LOGIN_TIMEOUT_SEC = 30;

package/dist/auth/loopback.js

@@ -4,7 +4,7 @@ import { createPkcePair } from "./pkce.js";
 import { exchangeDeviceTokenAtApi } from "./device-token-client.js";
 /** Default wait for browser consent (matches server auth code TTL). */
 export const DEFAULT_LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
-/** stderr heartbeat while waiting for loopback callback (documented in docs/cli-auth.md §7). */
+/** stderr heartbeat while waiting for loopback callback (`kairos login --no-open`). */
 export const LOGIN_HEARTBEAT_MS = 15_000;
 /** Minimum `kairos login --timeout` value (seconds). */
 export const MIN_LOGIN_TIMEOUT_SEC = 30;
@@ -85,6 +85,17 @@ function waitForAuthorizationCode(server, timeoutMs) {
                 res.end();
                 return;
             }
+            const error = urlObj.searchParams.get("error");
+            const errorDescription = urlObj.searchParams.get("error_description");
+            if (error) {
+                res.writeHead(400, {
+                    "Content-Type": "text/html",
+                    Connection: "close",
+                });
+                res.end(`<h1>Auth failed: ${error}</h1><p>${errorDescription || ""}</p>`);
+                finish(() => reject(new Error(`Authorization failed: ${error}${errorDescription ? ` - ${errorDescription}` : ""}`)));
+                return;
+            }
             const code = urlObj.searchParams.get("code");
             if (!code) {
                 res.writeHead(400, {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kairos-cli",
-  "version": "0.0.4",
-  "description": "KairOS Agent CLI — login and tool calls",
+  "version": "0.0.5",
+  "description": "KairOS Agent CLI — pair with kairos-skill on skills.sh (install via KairOS dashboard)",
   "type": "module",
   "bin": {
     "kairos": "./dist/bin.js"