@suwujs/king-ai 0.2.0

package/dist/src/team-workflow.js

@@ -0,0 +1,253 @@
+export const KING_AI_ROLE_TEMPLATES = [
+    {
+        id: "planner",
+        name: "Planner",
+        responsibility: "Break ambiguous goals into ordered work, assign owners, track dependencies, and decide when human input is needed.",
+        defaultRoutingMode: "one-of-us",
+        capabilityHints: ["planning", "triage", "coordination"]
+    },
+    {
+        id: "builder",
+        name: "Builder",
+        responsibility: "Implement assigned product, code, document, or analysis changes and report exact artifacts produced.",
+        defaultRoutingMode: "one-of-us",
+        capabilityHints: ["implementation", "code", "docs"]
+    },
+    {
+        id: "reviewer",
+        name: "Reviewer",
+        responsibility: "Review scope, risks, correctness, and acceptance evidence before work is marked done.",
+        defaultRoutingMode: "review-required",
+        capabilityHints: ["review", "quality", "risk"]
+    },
+    {
+        id: "tester",
+        name: "Tester",
+        responsibility: "Design and run verification, regression, and release-readiness checks with reproducible commands.",
+        defaultRoutingMode: "review-required",
+        capabilityHints: ["testing", "verification", "regression"]
+    },
+    {
+        id: "ops",
+        name: "Ops",
+        responsibility: "Handle environment, queue, release, deployment, audit, and operational safety work.",
+        defaultRoutingMode: "human-decision",
+        capabilityHints: ["ops", "release", "deployment", "audit"]
+    },
+    {
+        id: "researcher",
+        name: "Researcher",
+        responsibility: "Collect evidence, compare options, preserve source quality, and turn findings into structured artifacts.",
+        defaultRoutingMode: "each",
+        capabilityHints: ["research", "evidence", "analysis"]
+    },
+    {
+        id: "doc-writer",
+        name: "Doc Writer",
+        responsibility: "Turn verified decisions and artifacts into user-facing documentation, release notes, and briefs.",
+        defaultRoutingMode: "one-of-us",
+        capabilityHints: ["documentation", "release-notes", "summary"]
+    },
+    {
+        id: "summarizer",
+        name: "Summarizer",
+        responsibility: "Close loops with concise status, residual risks, decisions, and artifact links.",
+        defaultRoutingMode: "one-of-us",
+        capabilityHints: ["summary", "handoff", "status"]
+    }
+];
+export function defaultTeamSpec(id = "default-team", name = "Default Team") {
+    const role = (template, overrides = {}) => {
+        const base = roleTemplateById(template);
+        return {
+            id: overrides.id ?? template,
+            template,
+            responsibility: overrides.responsibility ?? base.responsibility,
+            capabilities: overrides.capabilities ?? base.capabilityHints,
+            handoffPolicy: overrides.handoffPolicy ?? {
+                mode: base.defaultRoutingMode,
+                reviewerRole: template === "builder" ? "reviewer" : undefined,
+                escalation: template === "ops" ? "human" : "coordinator",
+                acceptanceRequired: template === "builder" || template === "reviewer" || template === "tester"
+            }
+        };
+    };
+    return {
+        id,
+        name,
+        roles: [
+            role("planner"),
+            role("builder"),
+            role("reviewer"),
+            role("tester"),
+            role("ops"),
+            role("researcher"),
+            role("doc-writer"),
+            role("summarizer")
+        ],
+        routingPolicy: {
+            defaultMode: "one-of-us",
+            capabilityFirst: true,
+            reviewRequiredFor: ["code", "release", "ops", "external"],
+            humanDecisionFor: ["production-deploy", "scope-change", "spend", "security-risk"]
+        },
+        permissionPolicy: {
+            defaultDecision: "deny",
+            rules: [
+                { role: "planner", allow: ["assign-task", "claim-task", "create-artifact", "create-decision", "close-task", "change-scope", "view-audit", "manage-queue", "view-cost"], requireHumanDecision: ["change-scope"] },
+                { role: "builder", allow: ["claim-task", "create-artifact"], requireReviewBy: "reviewer" },
+                { role: "reviewer", allow: ["claim-task", "create-artifact", "create-decision", "approve-decision", "close-task", "view-audit", "view-cost"] },
+                { role: "tester", allow: ["claim-task", "create-artifact", "create-decision", "view-audit"] },
+                { role: "ops", allow: ["claim-task", "create-artifact", "create-decision", "approve-decision", "deploy-release", "view-audit", "manage-queue", "view-cost"], requireHumanDecision: ["deploy-release"] },
+                { role: "researcher", allow: ["claim-task", "create-artifact", "view-audit"] },
+                { role: "doc-writer", allow: ["claim-task", "create-artifact", "view-audit"] },
+                { role: "summarizer", allow: ["claim-task", "create-artifact", "view-audit"] }
+            ]
+        }
+    };
+}
+export function checkTeamPermission(team, role, action) {
+    const normalizedRole = normalizeTeamRoleId(role);
+    const rule = team.permissionPolicy.rules.find((entry) => entry.role === normalizedRole);
+    if (!rule || !rule.allow.includes(action))
+        return { decision: "deny" };
+    if (rule.requireHumanDecision?.includes(action))
+        return { decision: "human-decision", rule };
+    return { decision: "allow", rule };
+}
+export function normalizeTeamRoleId(role) {
+    const value = role.trim();
+    const aliases = {
+        ceo: "planner",
+        "king-ai-ceo": "planner",
+        cto: "reviewer",
+        dev: "builder",
+        devops: "ops",
+        feedback: "researcher",
+        marketing: "doc-writer",
+        docs: "doc-writer"
+    };
+    return aliases[value] ?? value;
+}
+export function roleTemplateForAgent(agent) {
+    const text = `${agent.id ?? ""} ${agent.name ?? ""} ${agent.role ?? ""}`.toLowerCase();
+    const explicit = text.match(/role template:\s*([a-z-]+)/)?.[1];
+    if (explicit && isRoleTemplateId(explicit))
+        return explicit;
+    if (agent.id === "dev")
+        return "builder";
+    if (agent.id === "reviewer")
+        return "reviewer";
+    if (agent.id === "king-ai-ceo")
+        return "planner";
+    if (text.includes("tester"))
+        return "tester";
+    if (text.includes("doc-writer") || text.includes("doc writer") || text.includes("documentation"))
+        return "doc-writer";
+    if (text.includes("ops") || text.includes("devops") || text.includes("release"))
+        return "ops";
+    if (text.includes("researcher") || text.includes("research"))
+        return "researcher";
+    if (text.includes("reviewer"))
+        return "reviewer";
+    if (text.includes("builder") || text.includes("implement"))
+        return "builder";
+    if (text.includes("planner") || text.includes("ceo") || text.includes("coordinate"))
+        return "planner";
+    return "builder";
+}
+export function requiredCapabilitiesForText(text) {
+    const value = text.toLowerCase();
+    if (/\b(test|verify|verification|regression|qa)\b/.test(value))
+        return ["testing", "verification"];
+    if (/\b(release|deploy|queue|approval|audit|ops)\b/.test(value))
+        return ["ops", "release", "audit"];
+    if (/\b(research|compare|brief|market|source|evidence)\b/.test(value))
+        return ["research", "evidence"];
+    if (/\b(doc|docs|readme|release note|write|summary)\b/.test(value))
+        return ["documentation", "summary"];
+    return ["implementation", "code"];
+}
+export function roleTemplateById(id) {
+    const template = KING_AI_ROLE_TEMPLATES.find((entry) => entry.id === id);
+    if (!template)
+        throw new Error(`unknown role template: ${id}`);
+    return template;
+}
+function isRoleTemplateId(value) {
+    return KING_AI_ROLE_TEMPLATES.some((template) => template.id === value);
+}
+export function scenarioTemplate(id) {
+    const team = defaultTeamSpec(`${id}-team`, `${titleCase(id)} Team`);
+    const commonAcceptance = [
+        "Every task has an owner role and acceptance evidence.",
+        "Review-required work has a reviewer role before completion.",
+        "Human decisions are represented as decision workflow objects."
+    ];
+    const scenarios = {
+        "repo-takeover": {
+            id,
+            name: "Repo Takeover",
+            goal: "Understand a repository, establish safe operating boundaries, and produce a takeover-ready plan.",
+            team,
+            acceptance: [...commonAcceptance, "Repository structure, build/test commands, and risk areas are captured."],
+            tasks: [
+                { title: "Map repository structure and ownership boundaries", ownerRole: "researcher", reviewerRole: "planner", acceptance: ["Key modules and commands are documented."] },
+                { title: "Create takeover backlog and capsule boundaries", ownerRole: "planner", reviewerRole: "reviewer", dependsOn: ["task-1"], acceptance: ["Backlog has ordered tasks and scoped capsules."] },
+                { title: "Verify build and test entrypoints", ownerRole: "tester", reviewerRole: "ops", dependsOn: ["task-1"], acceptance: ["Verification commands and failures are recorded."] }
+            ]
+        },
+        "bug-investigation": {
+            id,
+            name: "Bug Investigation",
+            goal: "Find root cause, propose a focused fix, verify behavior, and produce a concise incident artifact.",
+            team,
+            acceptance: [...commonAcceptance, "Root cause is linked to code/runtime evidence."],
+            tasks: [
+                { title: "Reproduce and isolate symptom", ownerRole: "tester", reviewerRole: "researcher", acceptance: ["Reproduction or strongest available evidence is recorded."] },
+                { title: "Trace root cause and candidate fix", ownerRole: "builder", reviewerRole: "reviewer", dependsOn: ["task-1"], acceptance: ["Cause and changed files are identified."] },
+                { title: "Verify fix and summarize residual risk", ownerRole: "reviewer", reviewerRole: "planner", dependsOn: ["task-2"], acceptance: ["Regression evidence and risk summary are recorded."] }
+            ]
+        },
+        "product-design": {
+            id,
+            name: "Product Design",
+            goal: "Turn a product idea into roles, user flows, acceptance criteria, and implementation-ready artifacts.",
+            team,
+            acceptance: [...commonAcceptance, "Design decisions are explicit and unresolved choices are escalated."],
+            tasks: [
+                { title: "Research user goals and competing workflows", ownerRole: "researcher", reviewerRole: "planner", acceptance: ["Insights and assumptions are captured."] },
+                { title: "Define user flow and acceptance criteria", ownerRole: "planner", reviewerRole: "reviewer", dependsOn: ["task-1"], acceptance: ["Flow, scope, and non-goals are written."] },
+                { title: "Draft implementation-facing design artifact", ownerRole: "doc-writer", reviewerRole: "builder", dependsOn: ["task-2"], acceptance: ["Artifact is ready for build planning."] }
+            ]
+        },
+        "release-check": {
+            id,
+            name: "Release Check",
+            goal: "Validate readiness for release with testing, risk review, approvals, and release notes.",
+            team,
+            acceptance: [...commonAcceptance, "Release decision is represented as an approval or decision object."],
+            tasks: [
+                { title: "Run release verification checklist", ownerRole: "tester", reviewerRole: "ops", acceptance: ["Commands, pass/fail state, and gaps are recorded."] },
+                { title: "Review operational and regression risk", ownerRole: "reviewer", reviewerRole: "ops", dependsOn: ["task-1"], acceptance: ["Risks and mitigations are recorded."] },
+                { title: "Prepare release notes and human decision", ownerRole: "doc-writer", reviewerRole: "planner", dependsOn: ["task-2"], acceptance: ["Release notes and approval question exist."] }
+            ]
+        },
+        "research-brief": {
+            id,
+            name: "Research Brief",
+            goal: "Produce a sourced, confidence-scored brief with decisions, artifacts, and follow-up tasks.",
+            team,
+            acceptance: [...commonAcceptance, "Claims include source quality and confidence."],
+            tasks: [
+                { title: "Collect evidence and competing viewpoints", ownerRole: "researcher", reviewerRole: "reviewer", acceptance: ["Artifacts include source and confidence."] },
+                { title: "Synthesize brief and recommendations", ownerRole: "doc-writer", reviewerRole: "planner", dependsOn: ["task-1"], acceptance: ["Brief includes recommendation and caveats."] },
+                { title: "Record decision points and follow-up tasks", ownerRole: "planner", reviewerRole: "reviewer", dependsOn: ["task-2"], acceptance: ["Open decisions and next tasks are explicit."] }
+            ]
+        }
+    };
+    return scenarios[id];
+}
+function titleCase(value) {
+    return value.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}

package/dist/src/text.d.ts

@@ -0,0 +1,7 @@
+export declare const ANSI_RE: RegExp;
+export declare function stripLoneSurrogates(s: string): string;
+export declare function cleanLine(line: string): string;
+export declare function concise(text: string, max?: number): string;
+export declare function hashText(text: string): string;
+export declare function isRateLimited(text: string): boolean;
+export declare function authFailureHint(engine: string, detail: string): string;

package/dist/src/text.js

@@ -0,0 +1,27 @@
+import { engineRemediationAdvice, formatRemediationAdvice } from "./remediation.js";
+export const ANSI_RE = /\x1B\[[0-?]*[ -/]*[@-~]/g;
+export function stripLoneSurrogates(s) {
+    return s
+        .replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])/g, "")
+        .replace(/(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "");
+}
+export function cleanLine(line) {
+    return line.replace(ANSI_RE, "").replace(/\r/g, "").trim();
+}
+export function concise(text, max = 900) {
+    return cleanLine(text).slice(0, max);
+}
+export function hashText(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i += 1) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, "0").slice(0, 8);
+}
+export function isRateLimited(text) {
+    return /\b(429|503)\b|too many requests|rate.?limit|\bquota\b|resource_exhausted|usage limit|session limit|overloaded|insufficient_quota|service (temporarily )?unavailable/i.test(text);
+}
+export function authFailureHint(engine, detail) {
+    return formatRemediationAdvice(engineRemediationAdvice(engine, detail));
+}

package/dist/src/types.d.ts

@@ -0,0 +1,98 @@
+export type EngineId = "claude" | "codex";
+export type AgentLifecycle = "on-demand" | "24/7" | "idle_cached" | "disabled";
+export interface ComputerConfig {
+    serverUrl: string;
+    computerId: string;
+    deviceToken: string;
+    tenantId?: string;
+}
+export interface AgentConfig {
+    id: string;
+    name: string;
+    role?: string;
+    engine?: EngineId;
+    model?: string;
+    fastModel?: string;
+    lifecycle?: AgentLifecycle;
+}
+export interface RuntimeRun {
+    runId?: string;
+}
+export interface TriageVerdict {
+    actionable: boolean;
+    reason?: string;
+    promptNote?: string;
+    source?: string;
+    responseMode?: "me" | "each" | "one-of-us";
+    routeHint?: "ignore" | "monitor" | "respond" | "steer";
+    priority?: "normal" | "steer" | "urgent";
+}
+export interface EngineUsage {
+    input_tokens?: number;
+    cache_read_input_tokens?: number;
+    output_tokens?: number;
+}
+export interface EngineResult {
+    exitCode: number;
+    error?: string;
+    sessionId?: string | null;
+    usage?: EngineUsage;
+    model?: string | null;
+}
+export interface EngineTurnOptions {
+    imagePaths?: string[];
+}
+export interface EngineSession {
+    readonly alive: boolean;
+    readonly sessionId: string | null;
+    readonly carriesStandingPrompt: boolean;
+    send(prompt: string, options?: EngineTurnOptions): Promise<EngineResult>;
+    steer(text: string): void;
+    stop(): void;
+}
+export interface EngineRunArgs {
+    home: string;
+    prompt: string;
+    env: NodeJS.ProcessEnv;
+    model?: string;
+    fastModel?: string;
+    resumeSessionId?: string | null;
+    standingPrompt?: string;
+    imagePaths?: string[];
+    signal: AbortSignal;
+    onLog: (line: string) => void;
+}
+export interface EngineProbeArgs {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    tier: "small" | "big";
+    signal: AbortSignal;
+}
+export interface EngineClassifyArgs {
+    cwd: string;
+    prompt: string;
+    env: NodeJS.ProcessEnv;
+    model?: string;
+    signal: AbortSignal;
+    onLog?: (line: string) => void;
+}
+export interface EngineAdapter {
+    id: EngineId;
+    bin: string;
+    seedHome(home: string, persona: {
+        id: string;
+        name: string;
+        role?: string;
+    }): Promise<void>;
+    classify(args: EngineClassifyArgs): Promise<{
+        text: string;
+        error?: string;
+        usage?: EngineUsage;
+    }>;
+    probe(args: EngineProbeArgs): Promise<{
+        text: string;
+        error?: string;
+    }>;
+    run(args: EngineRunArgs): Promise<EngineResult>;
+    startSession?(args: Omit<EngineRunArgs, "prompt" | "signal">): EngineSession | null;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/usage.d.ts

@@ -0,0 +1,116 @@
+export interface UsageTotals {
+    inputTokens: number;
+    cacheReadInputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+export interface UsagePricingRule {
+    key: string;
+    currency: string;
+    inputPerMillionTokens?: number;
+    cacheReadInputPerMillionTokens?: number;
+    outputPerMillionTokens?: number;
+    source?: string;
+}
+export interface UsageCostSummary {
+    amount: number;
+    currency: string;
+    inputCost: number;
+    cacheReadInputCost: number;
+    outputCost: number;
+    pricedTokens: number;
+    unpricedTokens: number;
+    pricingKeys: string[];
+}
+export interface AgentRunStats extends UsageTotals {
+    turns: number;
+    completed: number;
+    failed: number;
+    lastRunAt?: string;
+    lastDurationMs?: number;
+    lastStatus?: "completed" | "failed";
+    lastModel?: string | null;
+}
+export interface TokenBudgetCheck {
+    budget: number;
+    used: number;
+    remaining: number;
+    warning: boolean;
+    exceeded: boolean;
+    state: "ok" | "warning" | "exceeded";
+}
+export interface UsageAgentInput {
+    id: string;
+    name?: string;
+    engine: string;
+    model?: string | null;
+    runStats?: AgentRunStats;
+    tokenBudget?: TokenBudgetCheck;
+}
+export interface UsageGroupSummary extends UsageTotals {
+    key: string;
+    turns: number;
+    completed: number;
+    failed: number;
+    agents: number;
+    cost?: UsageCostSummary;
+}
+export interface UsageAgentSummary extends UsageGroupSummary {
+    id: string;
+    name?: string;
+    engine: string;
+    model?: string | null;
+    lastRunAt?: string;
+    lastStatus?: "completed" | "failed";
+    tokenBudget?: TokenBudgetCheck;
+    cost?: UsageCostSummary;
+}
+export interface UsageSummary extends UsageTotals {
+    agents: UsageAgentSummary[];
+    byEngine: UsageGroupSummary[];
+    byModel: UsageGroupSummary[];
+    turns: number;
+    completed: number;
+    failed: number;
+    budget?: TokenBudgetCheck;
+    cost?: UsageCostSummary;
+}
+export interface UsageExpenseRow extends UsageTotals {
+    agentId: string;
+    agentName?: string;
+    engine: string;
+    model: string;
+    turns: number;
+    completed: number;
+    failed: number;
+    currency: string;
+    amount: number;
+    inputCost: number;
+    cacheReadInputCost: number;
+    outputCost: number;
+    pricedTokens: number;
+    unpricedTokens: number;
+    pricingKeys: string[];
+    lastRunAt?: string;
+    lastStatus?: "completed" | "failed";
+}
+export declare function normalizeEngineUsage(usage: unknown): UsageTotals;
+export declare function emptyAgentRunStats(): AgentRunStats;
+export declare function recordAgentRunStats(current: AgentRunStats, args: {
+    status: "completed" | "failed";
+    usage?: unknown;
+    durationMs: number;
+    model?: string | null;
+    at?: string;
+}): AgentRunStats;
+export declare function formatAgentRunStats(stats?: AgentRunStats): string;
+export declare function tokenBudgetFromEnv(env?: NodeJS.ProcessEnv): number | null;
+export declare function usagePricingFromEnv(env?: NodeJS.ProcessEnv): UsagePricingRule[];
+export declare function normalizeUsagePricing(value: unknown): UsagePricingRule[];
+export declare function estimateUsageCost(totals: UsageTotals, pricing?: UsagePricingRule | null): UsageCostSummary | undefined;
+export declare function checkTokenBudget(stats: AgentRunStats | undefined, budget: number | null | undefined): TokenBudgetCheck | undefined;
+export declare function formatTokenBudgetCheck(check?: TokenBudgetCheck): string;
+export declare function summarizeAgentUsage(agents?: UsageAgentInput[], budget?: number | null | undefined, pricingRules?: UsagePricingRule[]): UsageSummary;
+export declare function formatUsageSummary(summary: UsageSummary): string;
+export declare function listUsageExpenses(summary: UsageSummary): UsageExpenseRow[];
+export declare function formatUsageExpenses(rows: UsageExpenseRow[]): string;