kairos-cli 0.0.3

package/README.md

@@ -0,0 +1,48 @@
+# kairos-cli
+
+Local CLI bridge for KairOS agent tools.
+
+## Install
+
+```bash
+npm install -g kairos-cli
+```
+
+## Login
+
+```bash
+kairos login --api-url https://your-kairos-url.com
+kairos whoami
+```
+
+## Example commands
+
+```bash
+kairos tools
+kairos call query_today '{}'
+kairos call query_tasks '{"activeOnly":true}'
+```
+
+## Local development
+
+From the monorepo root:
+
+```bash
+pnpm cli:build
+pnpm kairos --help
+```
+
+## Publish and release
+
+`kairos-cli` is published by GitHub Actions (`.github/workflows/release-cli.yml`).
+
+- Workflow permissions include `id-token: write` for npm trusted publishing support.
+- Current publish step also supports token-based auth via `NPM_TOKEN`.
+- A `403 Forbidden` during publish means the npm credentials lack publish rights for the package/account.
+
+Before release troubleshooting, verify:
+
+```bash
+npm whoami
+pnpm --filter kairos-cli build
+```

package/dist/auth/device-token-client.d.ts

@@ -0,0 +1,11 @@
+export type DeviceTokenResponse = {
+    access_token: string;
+    token_type: "Bearer";
+    expires_in: number;
+};
+/** POST /api/cli/device/token — shared by loopback auth. */
+export declare function exchangeDeviceTokenAtApi(apiBaseUrl: string, body: {
+    code: string;
+    code_verifier: string;
+    redirect_uri: string;
+}): Promise<DeviceTokenResponse>;

package/dist/auth/device-token-client.js

@@ -0,0 +1,35 @@
+function parseErrorBody(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const record = body;
+    if (typeof record.error !== "string" || typeof record.code !== "string") {
+        return null;
+    }
+    return { error: record.error, code: record.code };
+}
+function deviceTokenErrorMessageFromResponse(status, bodyText) {
+    try {
+        const parsed = parseErrorBody(JSON.parse(bodyText));
+        if (parsed)
+            return parsed.error;
+    }
+    catch {
+        if (bodyText)
+            return `Token exchange failed: ${bodyText}`;
+    }
+    return `Token exchange failed (HTTP ${status})`;
+}
+/** POST /api/cli/device/token — shared by loopback auth. */
+export async function exchangeDeviceTokenAtApi(apiBaseUrl, body) {
+    const baseUrl = apiBaseUrl.replace(/\/$/, "");
+    const res = await fetch(`${baseUrl}/api/cli/device/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(deviceTokenErrorMessageFromResponse(res.status, text));
+    }
+    return JSON.parse(text);
+}

package/dist/auth/loopback.d.ts

@@ -0,0 +1,19 @@
+/** 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). */
+export declare const LOGIN_HEARTBEAT_MS = 15000;
+/** Minimum `kairos login --timeout` value (seconds). */
+export declare const MIN_LOGIN_TIMEOUT_SEC = 30;
+export type LoopbackAuthOptions = {
+    /** Skip `open` / `xdg-open` (for agents and headless terminals). */
+    noOpen?: boolean;
+    /** Max time to wait for loopback callback (default 5 minutes). */
+    timeoutMs?: number;
+};
+/**
+ * Runs PKCE loopback auth against the KairOS web app.
+ */
+export declare function authenticateViaLoopback(apiUrl: string, options?: LoopbackAuthOptions): Promise<{
+    access_token: string;
+    expires_in: number;
+}>;

package/dist/auth/loopback.js

@@ -0,0 +1,153 @@
+import { spawn } from "node:child_process";
+import http from "node:http";
+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). */
+export const LOGIN_HEARTBEAT_MS = 15_000;
+/** Minimum `kairos login --timeout` value (seconds). */
+export const MIN_LOGIN_TIMEOUT_SEC = 30;
+function openBrowser(url) {
+    const opts = { stdio: "ignore", detached: true };
+    let child;
+    if (process.platform === "darwin") {
+        child = spawn("open", [url], opts);
+    }
+    else if (process.platform === "win32") {
+        child = spawn("cmd", ["/c", "start", "", url], { ...opts, shell: false });
+    }
+    else {
+        child = spawn("xdg-open", [url], opts);
+    }
+    child.on("error", (err) => {
+        console.error("Failed to launch browser opener:", err);
+    });
+    child.unref();
+}
+const SUCCESS_HTML = `<!DOCTYPE html>
+<html>
+  <body style="font-family:system-ui,sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;background:#0b0f19;color:#f3f4f6">
+    <div style="padding:2rem;border-radius:12px;background:#111827;border:1px solid #1f2937;text-align:center;max-width:400px">
+      <h1 style="color:#10b981;margin:0 0 1rem">Authenticated</h1>
+      <p style="margin:0;color:#9ca3af">You can close this tab and return to the terminal.</p>
+    </div>
+  </body>
+</html>`;
+function loopbackRedirectUri(port) {
+    return `http://127.0.0.1:${port}/callback`;
+}
+function listenOnLoopback(server) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (!addr || typeof addr === "string") {
+                reject(new Error("Could not bind loopback server"));
+                return;
+            }
+            resolve(addr.port);
+        });
+    });
+}
+function closeLoopbackServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+    });
+}
+function waitForAuthorizationCode(server, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearInterval(heartbeat);
+            clearTimeout(timeout);
+            cleanup();
+            fn();
+        };
+        const onError = (err) => {
+            finish(() => reject(err));
+        };
+        const onRequest = (req, res) => {
+            let urlObj;
+            try {
+                urlObj = new URL(req.url ?? "/", "http://127.0.0.1");
+            }
+            catch {
+                res.writeHead(400, { Connection: "close" });
+                res.end();
+                return;
+            }
+            if (urlObj.pathname !== "/callback") {
+                res.writeHead(404, { Connection: "close" });
+                res.end();
+                return;
+            }
+            const code = urlObj.searchParams.get("code");
+            if (!code) {
+                res.writeHead(400, {
+                    "Content-Type": "text/html",
+                    Connection: "close",
+                });
+                res.end("<h1>Auth failed: missing code</h1>");
+                finish(() => reject(new Error("No authorization code received")));
+                return;
+            }
+            res.writeHead(200, {
+                "Content-Type": "text/html",
+                Connection: "close",
+            });
+            res.end(SUCCESS_HTML);
+            finish(() => resolve(code));
+        };
+        const cleanup = () => {
+            server.off("error", onError);
+            server.off("request", onRequest);
+        };
+        server.on("error", onError);
+        server.on("request", onRequest);
+        console.error("Waiting for browser authorization… Sign in if prompted, then click Authorize.");
+        console.error("Press Ctrl+C to cancel.");
+        const heartbeat = setInterval(() => {
+            console.error("Still waiting… Open the URL above and click Authorize when ready.");
+        }, LOGIN_HEARTBEAT_MS);
+        heartbeat.unref();
+        const timeout = setTimeout(() => {
+            finish(() => reject(new Error(`Login timed out after ${Math.round(timeoutMs / 1000)}s. Run kairos login again.`)));
+        }, timeoutMs);
+        timeout.unref();
+    });
+}
+/**
+ * Runs PKCE loopback auth against the KairOS web app.
+ */
+export async function authenticateViaLoopback(apiUrl, options = {}) {
+    const { verifier, challenge } = createPkcePair();
+    const baseUrl = apiUrl.replace(/\/$/, "");
+    const timeoutMs = options.timeoutMs ?? DEFAULT_LOGIN_TIMEOUT_MS;
+    const server = http.createServer();
+    try {
+        const port = await listenOnLoopback(server);
+        const redirectUri = loopbackRedirectUri(port);
+        const loginUrl = `${baseUrl}/cli/device?code_challenge=${challenge}&redirect_uri=${encodeURIComponent(redirectUri)}`;
+        console.log(`\nOpen this URL to authenticate:\n${loginUrl}\n`);
+        if (options.noOpen) {
+            console.error("Browser not opened (--no-open). Copy the URL above into your browser.");
+        }
+        else {
+            openBrowser(loginUrl);
+        }
+        const code = await waitForAuthorizationCode(server, timeoutMs);
+        console.error("Authorization received, exchanging token…");
+        return await exchangeDeviceTokenAtApi(baseUrl, {
+            code,
+            code_verifier: verifier,
+            redirect_uri: redirectUri,
+        });
+    }
+    finally {
+        await closeLoopbackServer(server).catch(() => undefined);
+    }
+}

package/dist/auth/pkce.d.ts

@@ -0,0 +1,5 @@
+/** PKCE verifier + S256 challenge for the CLI loopback flow. */
+export declare function createPkcePair(): {
+    verifier: string;
+    challenge: string;
+};

package/dist/auth/pkce.js

@@ -0,0 +1,9 @@
+import crypto from "node:crypto";
+function pkceS256Challenge(verifier) {
+    return crypto.createHash("sha256").update(verifier).digest("base64url");
+}
+/** PKCE verifier + S256 challenge for the CLI loopback flow. */
+export function createPkcePair() {
+    const verifier = crypto.randomBytes(32).toString("base64url");
+    return { verifier, challenge: pkceS256Challenge(verifier) };
+}

package/dist/auth/token-store.d.ts

@@ -0,0 +1,11 @@
+export type Credentials = {
+    api_url: string;
+    access_token: string;
+    expires_at: string;
+};
+export declare function getDefaultApiUrl(): string;
+export declare function loadCredentials(): Credentials | null;
+export declare function saveCredentials(creds: Credentials): void;
+export declare function clearCredentials(): void;
+export declare function getValidAccessToken(): string | null;
+export declare function credentialsPath(): string;

package/dist/auth/token-store.js

@@ -0,0 +1,43 @@
+import { mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getCliDefaultApiUrl } from "../env.js";
+const CONFIG_DIR = join(homedir(), ".config", "kairos");
+const CREDENTIALS_PATH = join(CONFIG_DIR, "credentials.json");
+export function getDefaultApiUrl() {
+    return getCliDefaultApiUrl();
+}
+export function loadCredentials() {
+    try {
+        const raw = readFileSync(CREDENTIALS_PATH, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function saveCredentials(creds) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CREDENTIALS_PATH, JSON.stringify(creds, null, 2), {
+        mode: 0o600,
+    });
+}
+export function clearCredentials() {
+    try {
+        unlinkSync(CREDENTIALS_PATH);
+    }
+    catch {
+        // ignore
+    }
+}
+export function getValidAccessToken() {
+    const creds = loadCredentials();
+    if (!creds?.access_token)
+        return null;
+    if (new Date(creds.expires_at) <= new Date())
+        return null;
+    return creds.access_token;
+}
+export function credentialsPath() {
+    return CREDENTIALS_PATH;
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import { authenticateViaLoopback, DEFAULT_LOGIN_TIMEOUT_MS, MIN_LOGIN_TIMEOUT_SEC, } from "./auth/loopback.js";
+import { clearCredentials, credentialsPath, getDefaultApiUrl, getValidAccessToken, loadCredentials, saveCredentials, } from "./auth/token-store.js";
+import { KairosClient } from "./client.js";
+function usage() {
+    console.log(`KairOS Agent CLI
+
+Usage:
+  kairos login [--api-url <url>] [--no-open] [--timeout <seconds>]
+  kairos logout
+  kairos whoami
+  kairos tools
+  kairos call <toolName> '<json>'
+
+Examples:
+  kairos login --no-open
+  kairos call query_calendar '{"from":"2026-05-18","to":"2026-05-25"}'
+  kairos call create_task '{"title":"Follow up"}'
+  kairos call query_tasks '{"activeOnly":true}'
+  kairos call create_lead '{"company":"Acme","role":"Staff Engineer"}'
+  kairos call query_leads '{"activeOnly":true}'
+
+Environment:
+  KAIROS_API_URL  API base URL (default: https://kairos.querobines.com)
+`);
+}
+function takeFlagValue(args, index, flag) {
+    const value = args[index + 1];
+    if (!value || value.startsWith("-")) {
+        console.error(`Missing value for ${flag}`);
+        usage();
+        process.exit(1);
+    }
+    return value;
+}
+function parseLoginArgs(args) {
+    let apiUrl = getDefaultApiUrl();
+    let noOpen = false;
+    let timeoutSec = Math.round(DEFAULT_LOGIN_TIMEOUT_MS / 1000);
+    for (let i = 0; i < args.length; i++) {
+        const flag = args[i];
+        if (flag === "--no-open") {
+            noOpen = true;
+            continue;
+        }
+        if (flag === "--api-url") {
+            apiUrl = takeFlagValue(args, i, flag);
+            i++;
+            continue;
+        }
+        if (flag === "--timeout") {
+            const value = takeFlagValue(args, i, flag);
+            const parsed = Number.parseInt(value, 10);
+            if (!/^\d+$/.test(value) || parsed < MIN_LOGIN_TIMEOUT_SEC) {
+                console.error(`--timeout must be an integer of at least ${MIN_LOGIN_TIMEOUT_SEC} seconds`);
+                process.exit(1);
+            }
+            timeoutSec = parsed;
+            i++;
+            continue;
+        }
+        if (flag.startsWith("-")) {
+            console.error(`Unknown flag: ${flag}`);
+            usage();
+            process.exit(1);
+        }
+        console.error(`Unexpected argument: ${flag}`);
+        usage();
+        process.exit(1);
+    }
+    return { apiUrl, noOpen, timeoutMs: timeoutSec * 1000 };
+}
+async function cmdLogin(args) {
+    const { apiUrl, noOpen, timeoutMs } = parseLoginArgs(args);
+    const tokens = await authenticateViaLoopback(apiUrl, { noOpen, timeoutMs });
+    const expiresAt = new Date(Date.now() + tokens.expires_in * 1000).toISOString();
+    saveCredentials({
+        api_url: apiUrl,
+        access_token: tokens.access_token,
+        expires_at: expiresAt,
+    });
+    console.log(`Saved credentials to ${credentialsPath()}`);
+}
+async function cmdWhoami() {
+    const creds = loadCredentials();
+    if (!creds) {
+        console.log("Not logged in. Run: kairos login");
+        process.exit(1);
+    }
+    const valid = getValidAccessToken() !== null;
+    console.log(`API: ${creds.api_url}`);
+    console.log(`Expires: ${creds.expires_at ?? "unknown"}`);
+    console.log(`Token valid: ${valid ? "yes" : "no (run kairos login)"}`);
+}
+async function cmdCall(args) {
+    const toolName = args[0];
+    const jsonArg = args[1];
+    if (!toolName || !jsonArg) {
+        console.error("Usage: kairos call <toolName> '<json>'");
+        process.exit(1);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonArg);
+    }
+    catch {
+        console.error("Invalid JSON input");
+        process.exit(1);
+    }
+    const client = KairosClient.fromEnv();
+    const data = await client.callTool(toolName, parsed);
+    console.log(JSON.stringify(data, null, 2));
+}
+async function cmdTools() {
+    const client = KairosClient.fromEnv();
+    const tools = await client.listTools();
+    for (const t of tools) {
+        const flag = t.implemented ? "" : " (pending)";
+        console.log(`${t.name}${flag} — ${t.description}`);
+    }
+}
+async function main() {
+    const [, , command, ...rest] = process.argv;
+    switch (command) {
+        case "login":
+            await cmdLogin(rest);
+            break;
+        case "logout":
+            clearCredentials();
+            console.log("Logged out.");
+            break;
+        case "whoami":
+            await cmdWhoami();
+            break;
+        case "tools":
+            await cmdTools();
+            break;
+        case "call":
+            await cmdCall(rest);
+            break;
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            usage();
+            break;
+        default:
+            console.error(`Unknown command: ${command}`);
+            usage();
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,14 @@
+export declare class KairosClient {
+    private readonly apiUrl;
+    constructor(apiUrl: string);
+    static fromEnv(): KairosClient;
+    private baseUrl;
+    private authHeaders;
+    private request;
+    callTool<T = unknown>(toolName: string, input: Record<string, unknown>): Promise<T>;
+    listTools(): Promise<Array<{
+        name: string;
+        description: string;
+        implemented: boolean;
+    }>>;
+}

package/dist/client.js

@@ -0,0 +1,51 @@
+import { getDefaultApiUrl, getValidAccessToken, loadCredentials, } from "./auth/token-store.js";
+export class KairosClient {
+    apiUrl;
+    constructor(apiUrl) {
+        this.apiUrl = apiUrl;
+    }
+    static fromEnv() {
+        const creds = loadCredentials();
+        return new KairosClient(creds?.api_url ?? getDefaultApiUrl());
+    }
+    baseUrl() {
+        return this.apiUrl.replace(/\/$/, "");
+    }
+    async authHeaders() {
+        const token = getValidAccessToken();
+        if (!token) {
+            throw new Error("Not authenticated. Run: kairos login");
+        }
+        return {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+        };
+    }
+    async request(path, init) {
+        const res = await fetch(`${this.baseUrl()}${path}`, {
+            ...init,
+            headers: { ...(await this.authHeaders()), ...init?.headers },
+        });
+        const text = await res.text();
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`HTTP ${res.status}: ${text || res.statusText || "Empty response"}`);
+        }
+        if (!res.ok || !body.ok) {
+            throw new Error(body.error ?? `HTTP ${res.status}`);
+        }
+        return body.data;
+    }
+    async callTool(toolName, input) {
+        return this.request(`/api/ai/tools/${toolName}`, {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    async listTools() {
+        return this.request("/api/ai/tools");
+    }
+}

package/dist/env.d.ts

@@ -0,0 +1,4 @@
+/** Returns a trimmed env value, or null when unset/blank. */
+export declare function getOptionalEnv(name: string): string | null;
+/** Default API base for CLI login and calls when not set explicitly. */
+export declare function getCliDefaultApiUrl(): string;

package/dist/env.js

@@ -0,0 +1,9 @@
+/** Returns a trimmed env value, or null when unset/blank. */
+export function getOptionalEnv(name) {
+    const value = process.env[name]?.trim();
+    return value ? value : null;
+}
+/** Default API base for CLI login and calls when not set explicitly. */
+export function getCliDefaultApiUrl() {
+    return getOptionalEnv("KAIROS_API_URL") ?? "https://kairos.querobines.com";
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "kairos-cli",
+  "version": "0.0.3",
+  "description": "KairOS Agent CLI — login and tool calls",
+  "type": "module",
+  "bin": {
+    "kairos": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/bin.js"
+  }
+}