@suwujs/king-ai 0.2.0

package/README.md

@@ -0,0 +1,96 @@
+# king-ai
+
+King AI is a local BYOA multi-agent collaboration system. It connects remote agent runtimes to Claude and Codex running on your own machine, then layers team roles, task routing, review handoffs, claims, and human decision gates on top of those local engines.
+
+Repository: `sukbearai/king-ai`.
+
+Packages:
+
+- CLI: `@suwujs/king-ai`, exposing the `king-ai` command.
+- GUI worker app: `@king-ai/gui-worker`.
+
+The primary CLI command is `king-ai`. Local runtime state lives under `~/.king-ai`; existing `~/.king/computer.json` is read only as a one-time upgrade fallback when the new config has not been written yet.
+
+## Install And Develop
+
+```sh
+pnpm install
+pnpm verify
+pnpm dev -- agent computer --doctor
+```
+
+The GUI worker can be run locally with:
+
+```sh
+pnpm gui:dev
+```
+
+## Rename And Migration Notes
+
+This project was renamed to `king-ai`. New installs and generated commands should use only `king-ai`, `@suwujs/king-ai`, `@king-ai/gui-worker`, `KING_AI_*`, `king-ai://`, and `~/.king-ai`.
+
+The old `king` command is not exposed as a bin alias. The only retained legacy behavior is reading `~/.king/computer.json` when the new `~/.king-ai/computer.json` has not been written yet, so an already paired computer can migrate without losing its token.
+
+## Architecture
+
+```text
+                      +------------------------------------------------+
+                      |             Remote Runtime Server              |
+                      |  pair / roster / inbox / wake-stream / status  |
+                      +------------------------+-----------------------+
+                                                           |
+                                                           v
+      +--------------------------------------------------------------------------------+
+      |                                Local Machine                                   |
+      |                                                                                |
+      |  +----------------------+      +----------------------------------------+      |
+      |  | king-ai CLI          |----->| King AI daemon                         |      |
+      |  | status / run / logs  |      | pairing, heartbeat, SSE, host SDK      |      |
+      |  +----------------------+      +-------------------+--------------------+      |
+      |                                                   |                            |
+      |                                                   v                            |
+      |                                +----------------------------------------+      |
+      |                                | agent runner                          |       |
+      |                                | triage, prompts, session reuse        |       |
+      |                                +-------------------+--------------------+      |
+      |                                                   |                            |
+      |                         +-------------------------+---------------------+      |
+      |                         |                                               |      |
+      |                         v                                               v      |
+      |              +--------------------+                  +--------------------+    |
+      |              | Claude CLI         |                  | Codex CLI          |    |
+      |              +---------+----------+                  +----------+---------+    |
+      |                        |                                      |                |
+      |                        +------------------+-------------------+                |
+      |                                           |                                    |
+      |                                           v                                    |
+      |                                +----------------------------------------+      |
+      |                                | per-agent home                        |       |
+      |                                | skills, runtime shim, state files     |       |
+      |                                +-------------------+--------------------+      |
+      |                                                   |                            |
+      |                                                   v                            |
+      |                                +----------------------------------------+      |
+      |                                | allowed local workspaces              |       |
+      |                                | source repos, worktrees, artifacts    |       |
+      |                                +----------------------------------------+      |
+      +--------------------------------------------------------------------------------+
+```
+
+## Multi-Role Collaboration
+
+King AI models agent work as a small software team, not just a single chat bot. A conversation can run in single-agent, team, or custom team mode with a coordinator and selected team agents.
+
+The default role templates are `planner`, `builder`, `reviewer`, `tester`, `ops`, `researcher`, `doc-writer`, and `summarizer`. Each role carries responsibilities, capability hints, handoff policy, and permission rules. Built-in workflow scenarios such as `repo-takeover`, `bug-investigation`, `product-design`, `release-check`, and `research-brief` materialize those roles into assigned tasks with acceptance criteria.
+
+Routing is capability-first when possible. New work can be assigned to the role whose capabilities best match the request; completed work can automatically create a review, handoff, or human decision card. Routing modes include `one-of-us`, `each`, `review-required`, and `human-decision`.
+
+Runtime coordination uses shared conversation state. Agents are prompted to check `king-ai glance` before posting, use cards or claims before taking shared work, avoid duplicate replies, and trust current board state over memory. This keeps multiple local Claude/Codex-backed teammates from racing on the same deliverable.
+
+## Collaboration Governance
+
+King AI is automation-first. Team roles, permission rules, and human-decision gates are a collaboration governance layer for routing, audit, and handoff discipline; they are not the primary security boundary.
+
+Host commands apply role governance only when an actor role is supplied with `--role` or `KING_AI_TEAM_ROLE`. Without a role, trusted local automation can continue without being blocked. `human-decision` records a decision card and asks for an approval marker, but the trusted local operator can bypass role governance for unattended automation by not supplying a role.
+
+Use OS account isolation, local workspace boundaries, runtime tokens, host command allowlists, destructive-command confirmation, and per-agent homes as the security boundary.

package/dist/src/agent-config-validation.d.ts

@@ -0,0 +1,9 @@
+import type { AgentConfig, EngineId } from "./types.js";
+export type AgentConfigWarningCode = "idle-cached-without-resume" | "missing-preferred-engine" | "unknown-lifecycle";
+export interface AgentConfigWarning {
+    code: AgentConfigWarningCode;
+    severity: "warning";
+    summary: string;
+    detail: string;
+}
+export declare function validateAgentConfig(agent: AgentConfig, effectiveEngine: EngineId | string, availableEngines?: EngineId[]): AgentConfigWarning[];

package/dist/src/agent-config-validation.js

@@ -0,0 +1,30 @@
+import { normalizeAgentLifecycle } from "./lifecycle.js";
+export function validateAgentConfig(agent, effectiveEngine, availableEngines = []) {
+    const warnings = [];
+    const lifecycle = normalizeAgentLifecycle(agent.lifecycle);
+    if (agent.lifecycle && agent.lifecycle !== lifecycle) {
+        warnings.push({
+            code: "unknown-lifecycle",
+            severity: "warning",
+            summary: `unknown lifecycle ${agent.lifecycle} normalized to ${lifecycle}`,
+            detail: "The daemon only understands on-demand, 24/7, idle_cached, and disabled."
+        });
+    }
+    if (agent.engine && !availableEngines.includes(agent.engine)) {
+        warnings.push({
+            code: "missing-preferred-engine",
+            severity: "warning",
+            summary: `${agent.engine} is requested but not installed on this machine`,
+            detail: `The daemon will use ${effectiveEngine || "the first available engine"} until ${agent.engine} is available.`
+        });
+    }
+    if (lifecycle === "idle_cached" && effectiveEngine !== "claude") {
+        warnings.push({
+            code: "idle-cached-without-resume",
+            severity: "warning",
+            summary: "idle_cached has engine-specific resume semantics",
+            detail: "Claude uses CLI session resume. Codex may reuse an app-server thread when available, but the daemon treats it as best-effort and falls back to a fresh thread."
+        });
+    }
+    return warnings;
+}

package/dist/src/api.d.ts

@@ -0,0 +1,4 @@
+export declare function api<T>(serverUrl: string, path: string, init?: RequestInit): Promise<T>;
+export declare function tenantHeader(tenantId?: string): Record<string, string>;
+export declare function runtimePost<T>(serverUrl: string, path: string, token: string, body: unknown, tenantId?: string): Promise<T | null>;
+export declare function runtimeGet<T>(serverUrl: string, path: string, token: string, tenantId?: string): Promise<T | null>;

package/dist/src/api.js

@@ -0,0 +1,48 @@
+export async function api(serverUrl, path, init = {}) {
+    const res = await fetch(`${serverUrl}${path}`, {
+        ...init,
+        headers: {
+            "Content-Type": "application/json",
+            ...(init.headers ?? {})
+        }
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`${init.method ?? "GET"} ${path} -> HTTP ${res.status} ${body.slice(0, 200)}`);
+    }
+    return (await res.json());
+}
+export function tenantHeader(tenantId) {
+    return tenantId ? { "X-King-AI-Tenant": tenantId } : {};
+}
+export async function runtimePost(serverUrl, path, token, body, tenantId) {
+    try {
+        const res = await fetch(`${serverUrl}/runtime${path}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${token}`,
+                ...tenantHeader(tenantId)
+            },
+            body: JSON.stringify(body)
+        });
+        return res.ok ? (await res.json().catch(() => null)) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runtimeGet(serverUrl, path, token, tenantId) {
+    try {
+        const res = await fetch(`${serverUrl}/runtime${path}`, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                ...tenantHeader(tenantId)
+            }
+        });
+        return res.ok ? (await res.json().catch(() => null)) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/attachments.d.ts

@@ -0,0 +1,45 @@
+export type AttachmentKind = "image" | "file" | "audio" | "video" | "unknown";
+export type AttachmentDecision = "accepted" | "rejected" | "skipped";
+export interface RuntimeAttachmentInput {
+    id?: string;
+    name?: string;
+    kind?: string;
+    mime?: string;
+    size?: number;
+    sha256?: string;
+    url?: string;
+    filePath?: string;
+    required?: boolean;
+    source?: string;
+}
+export interface RuntimeAttachment {
+    id: string;
+    name: string;
+    kind: AttachmentKind;
+    mime: string;
+    size: number;
+    sha256?: string;
+    url?: string;
+    filePath?: string;
+    source?: string;
+    required: boolean;
+    decision: AttachmentDecision;
+    rejectionReason?: string;
+    localPath?: string;
+}
+export interface AttachmentPolicy {
+    maxCount: number;
+    maxBytes: number;
+    maxFileBytes: number;
+    imageMaxBytes: number;
+    allowedImageMimes: string[];
+    allowedFileMimes: string[];
+}
+export declare const DEFAULT_ATTACHMENT_POLICY: AttachmentPolicy;
+export declare function normalizeRuntimeAttachments(input: unknown, policy?: Partial<AttachmentPolicy>): RuntimeAttachment[];
+export declare function requiredAttachmentsRejected(attachments: readonly RuntimeAttachment[]): RuntimeAttachment[];
+export declare function formatAttachmentPrompt(attachments: readonly RuntimeAttachment[]): string;
+export declare function mediaCacheDir(root?: string): string;
+export declare function cacheLocalAttachment(attachment: RuntimeAttachment, root?: string): Promise<RuntimeAttachment>;
+export declare function cacheLocalAttachments(attachments: readonly RuntimeAttachment[], root?: string): Promise<RuntimeAttachment[]>;
+export declare function gcMediaCache(root?: string, maxAgeMs?: number): Promise<number>;

package/dist/src/attachments.js

@@ -0,0 +1,322 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { CONFIG_DIR } from "./paths.js";
+export const DEFAULT_ATTACHMENT_POLICY = {
+    maxCount: 10,
+    maxBytes: 100 * 1024 * 1024,
+    maxFileBytes: 25 * 1024 * 1024,
+    imageMaxBytes: 25 * 1024 * 1024,
+    allowedImageMimes: ["image/jpeg", "image/png", "image/webp", "image/gif"],
+    allowedFileMimes: [
+        "application/javascript",
+        "application/json",
+        "application/pdf",
+        "application/typescript",
+        "application/zip",
+        "text/css",
+        "text/csv",
+        "text/html",
+        "text/javascript",
+        "text/jsx",
+        "text/markdown",
+        "text/plain",
+        "text/tsv",
+        "text/tsx",
+        "text/xml",
+        "application/xml",
+        "application/xhtml+xml"
+    ]
+};
+const SAFE_EXT_BY_MIME = {
+    "application/javascript": "js",
+    "application/json": "json",
+    "application/pdf": "pdf",
+    "application/typescript": "ts",
+    "application/zip": "zip",
+    "image/gif": "gif",
+    "image/jpeg": "jpg",
+    "image/png": "png",
+    "image/webp": "webp",
+    "text/css": "css",
+    "text/csv": "csv",
+    "text/html": "html",
+    "text/javascript": "js",
+    "text/jsx": "jsx",
+    "text/markdown": "md",
+    "text/plain": "txt",
+    "text/tsv": "tsv",
+    "text/tsx": "tsx",
+    "text/xml": "xml",
+    "application/xml": "xml",
+    "application/xhtml+xml": "html"
+};
+export function normalizeRuntimeAttachments(input, policy = {}) {
+    const merged = { ...DEFAULT_ATTACHMENT_POLICY, ...policy };
+    const rows = Array.isArray(input) ? input : [];
+    let acceptedCount = 0;
+    let acceptedBytes = 0;
+    return rows.map((row, index) => {
+        const attachment = normalizeRuntimeAttachment(row, index);
+        const rejection = attachmentDecision(attachment, merged, acceptedCount, acceptedBytes);
+        if (rejection) {
+            return { ...attachment, decision: rejection.decision, rejectionReason: rejection.reason };
+        }
+        acceptedCount += 1;
+        acceptedBytes += attachment.size;
+        return { ...attachment, decision: "accepted" };
+    });
+}
+export function requiredAttachmentsRejected(attachments) {
+    return attachments.filter((attachment) => attachment.required && attachment.decision !== "accepted");
+}
+export function formatAttachmentPrompt(attachments) {
+    const accepted = attachments.filter((attachment) => attachment.decision === "accepted");
+    const rejected = attachments.filter((attachment) => attachment.decision !== "accepted");
+    const lines = [];
+    if (accepted.length) {
+        lines.push("Runtime attachments:");
+        for (const attachment of accepted) {
+            const location = attachment.localPath ?? attachment.filePath ?? attachment.url ?? "(unavailable)";
+            const pathHint = attachment.localPath || attachment.filePath ? ` @${location}` : ` ${location}`;
+            lines.push(`- [${attachment.name}] ${attachment.mime} ${attachment.size}B${pathHint}`);
+        }
+    }
+    if (rejected.length) {
+        lines.push("Rejected or skipped attachments:");
+        for (const attachment of rejected) {
+            lines.push(`- ${attachment.name}: ${attachment.rejectionReason ?? attachment.decision}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function mediaCacheDir(root = CONFIG_DIR) {
+    return join(root, "media");
+}
+export async function cacheLocalAttachment(attachment, root = mediaCacheDir()) {
+    if (attachment.decision !== "accepted")
+        return attachment;
+    if (attachment.filePath)
+        return cacheFilePathAttachment(attachment, root);
+    if (attachment.url)
+        return cacheUrlAttachment(attachment, root);
+    return attachment;
+}
+async function cacheFilePathAttachment(attachment, root) {
+    const filePath = attachment.filePath;
+    if (!filePath)
+        return attachment;
+    const source = resolve(filePath);
+    const sourceStat = await stat(source);
+    if (!sourceStat.isFile()) {
+        return { ...attachment, decision: "rejected", rejectionReason: "not-a-file" };
+    }
+    const sha256 = attachment.sha256 ?? await hashFile(source);
+    const ext = safeExtensionForMime(attachment.mime);
+    const target = join(root, `${sha256}.${ext}`);
+    await mkdir(root, { recursive: true });
+    try {
+        await stat(target);
+    }
+    catch {
+        const tmp = join(root, `.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        await copyByRename(source, tmp, target);
+    }
+    return {
+        ...attachment,
+        size: sourceStat.size,
+        sha256,
+        localPath: target
+    };
+}
+async function cacheUrlAttachment(attachment, root) {
+    const url = parseDownloadUrl(attachment.url);
+    if (!url)
+        return { ...attachment, decision: "rejected", rejectionReason: "invalid-url" };
+    const res = await fetch(url, { redirect: "follow" });
+    if (!res.ok)
+        return { ...attachment, decision: "rejected", rejectionReason: `download-failed-${res.status}` };
+    const contentType = res.headers.get("Content-Type")?.split(";")[0]?.trim().toLowerCase();
+    if (contentType && contentType !== attachment.mime) {
+        return { ...attachment, decision: "rejected", rejectionReason: "mime-mismatch" };
+    }
+    const contentLength = Number(res.headers.get("Content-Length") ?? "");
+    const maxBytes = attachment.kind === "image" ? DEFAULT_ATTACHMENT_POLICY.imageMaxBytes : DEFAULT_ATTACHMENT_POLICY.maxFileBytes;
+    if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+        return { ...attachment, decision: "rejected", rejectionReason: "download-too-large" };
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    if (bytes.byteLength > maxBytes)
+        return { ...attachment, decision: "rejected", rejectionReason: "download-too-large" };
+    const expectedSize = attachment.size > 0 ? attachment.size : bytes.byteLength;
+    if (bytes.byteLength !== expectedSize) {
+        return { ...attachment, decision: "rejected", rejectionReason: "size-mismatch" };
+    }
+    const sha256 = hashBytes(bytes);
+    if (attachment.sha256 && attachment.sha256 !== sha256) {
+        return { ...attachment, decision: "rejected", rejectionReason: "sha256-mismatch" };
+    }
+    const ext = safeExtensionForMime(attachment.mime);
+    const target = join(root, `${sha256}.${ext}`);
+    await mkdir(root, { recursive: true });
+    try {
+        await stat(target);
+    }
+    catch {
+        const tmp = join(root, `.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        await writeFile(tmp, bytes);
+        await rename(tmp, target);
+    }
+    return {
+        ...attachment,
+        size: bytes.byteLength,
+        sha256,
+        localPath: target
+    };
+}
+export async function cacheLocalAttachments(attachments, root = mediaCacheDir()) {
+    const out = [];
+    for (const attachment of attachments) {
+        out.push(await cacheLocalAttachment(attachment, root));
+    }
+    return out;
+}
+export async function gcMediaCache(root = mediaCacheDir(), maxAgeMs = 24 * 60 * 60 * 1000) {
+    const cutoff = Date.now() - maxAgeMs;
+    let removed = 0;
+    for (const file of await listFiles(root)) {
+        try {
+            const info = await stat(file);
+            if (info.isFile() && info.mtimeMs < cutoff) {
+                await rm(file, { force: true });
+                removed += 1;
+            }
+        }
+        catch {
+            // Ignore files that disappear during GC.
+        }
+    }
+    return removed;
+}
+function normalizeRuntimeAttachment(value, index) {
+    const row = value && typeof value === "object" ? value : {};
+    const name = cleanString(row.name) || (row.filePath ? basename(row.filePath) : `attachment-${index + 1}`);
+    const mime = normalizeAttachmentMime(cleanString(row.mime), name);
+    const kind = normalizeAttachmentKind(row.kind, mime);
+    const size = Number.isFinite(row.size) && Number(row.size) > 0 ? Math.floor(Number(row.size)) : 0;
+    return {
+        id: cleanString(row.id) || `attachment-${index + 1}`,
+        name,
+        kind,
+        mime,
+        size,
+        sha256: cleanString(row.sha256),
+        url: cleanString(row.url),
+        filePath: cleanString(row.filePath),
+        source: cleanString(row.source),
+        required: row.required === true,
+        decision: "accepted"
+    };
+}
+function attachmentDecision(attachment, policy, acceptedCount, acceptedBytes) {
+    if (!attachment.filePath && !attachment.url)
+        return { decision: "rejected", reason: "missing-location" };
+    if (attachment.kind === "audio" || attachment.kind === "video")
+        return { decision: "skipped", reason: "unsupported-kind" };
+    if (attachment.kind === "image" && !policy.allowedImageMimes.includes(attachment.mime))
+        return { decision: "rejected", reason: "unsupported-image-mime" };
+    if (attachment.kind === "file" && !policy.allowedFileMimes.includes(attachment.mime))
+        return { decision: "rejected", reason: "unsupported-file-mime" };
+    if (acceptedCount >= policy.maxCount)
+        return { decision: "rejected", reason: "too-many-attachments" };
+    if (attachment.size > policy.maxFileBytes)
+        return { decision: "rejected", reason: "file-too-large" };
+    if (attachment.kind === "image" && attachment.size > policy.imageMaxBytes)
+        return { decision: "rejected", reason: "image-too-large" };
+    if (acceptedBytes + attachment.size > policy.maxBytes)
+        return { decision: "rejected", reason: "run-too-large" };
+    return null;
+}
+function normalizeAttachmentKind(value, mime) {
+    if (value === "image" || value === "file" || value === "audio" || value === "video")
+        return value;
+    if (mime.startsWith("image/"))
+        return "image";
+    if (mime.startsWith("audio/"))
+        return "audio";
+    if (mime.startsWith("video/"))
+        return "video";
+    if (mime !== "application/octet-stream")
+        return "file";
+    return "unknown";
+}
+function safeExtensionForMime(mime) {
+    return SAFE_EXT_BY_MIME[mime] ?? "bin";
+}
+function normalizeAttachmentMime(value, name) {
+    const normalized = value?.toLowerCase() || "";
+    if (normalized && normalized !== "application/octet-stream")
+        return normalized;
+    return mimeFromName(name) ?? (normalized || "application/octet-stream");
+}
+function mimeFromName(name) {
+    const ext = name.toLowerCase().split(".").pop();
+    return {
+        css: "text/css",
+        csv: "text/csv",
+        htm: "text/html",
+        html: "text/html",
+        js: "text/javascript",
+        json: "application/json",
+        jsx: "text/jsx",
+        md: "text/markdown",
+        mjs: "text/javascript",
+        ts: "application/typescript",
+        tsx: "text/tsx",
+        tsv: "text/tsv",
+        txt: "text/plain",
+        xhtml: "application/xhtml+xml",
+        xml: "text/xml"
+    }[ext ?? ""];
+}
+function cleanString(value) {
+    return typeof value === "string" && value.trim() ? value.trim().slice(0, 1000) : undefined;
+}
+async function copyByRename(source, tmp, target) {
+    const { copyFile } = await import("node:fs/promises");
+    await copyFile(source, tmp);
+    await rename(tmp, target);
+}
+async function hashFile(path) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+function hashBytes(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function parseDownloadUrl(value) {
+    if (!value)
+        return null;
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:" ? url.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function listFiles(root) {
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const files = [];
+    for (const entry of entries) {
+        const full = join(root, entry.name);
+        if (entry.isDirectory())
+            files.push(...await listFiles(full));
+        else if (entry.isFile())
+            files.push(full);
+    }
+    return files;
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import type { CommandName } from "./paths.js";
+import type { KingScenarioTemplate } from "./team-workflow.js";
+export declare function commandNameFromArgv(argv0?: string): CommandName;
+export declare function versionText(commandName: string, version?: string): string;
+export declare function defaultServerForCommand(_commandName: string): string;
+export declare function hasExplicitServerArg(args: string[]): boolean;
+export declare function computerHelpText(defaultServer?: string, commandName?: string): string;
+export declare function normalizeComputerArgs(args: string[]): string[];
+export declare function shouldRunAfterPair(serviceInstalled: boolean): boolean;
+export declare function materializeTeamScenario(scenario: KingScenarioTemplate, outputDir: string, actorRole?: string): Promise<{
+    scenario: string;
+    outputDir: string;
+    cards: unknown[];
+}>;
+export declare function formatMaterializedTeamScenario(result: {
+    scenario: string;
+    outputDir: string;
+    cards: unknown[];
+}): string;