@suwujs/king-ai 0.2.0

package/dist/src/host-loop-events.js

@@ -0,0 +1,288 @@
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+export const HOST_LOOP_RESULTS_HEADER = [
+    "run_id",
+    "loop",
+    "timestamp",
+    "classification",
+    "tasks_created",
+    "tasks_done",
+    "artifacts_created",
+    "pending_messages",
+    "completion_rate",
+    "notes"
+].join("\t") + "\n";
+export async function appendHostLoopEvent(input) {
+    const file = resolveLoopEventsPath(input);
+    await mkdir(dirname(file), { recursive: true });
+    await appendFile(file, `${JSON.stringify(dropUndefined({ ...input.event }))}\n`, "utf8");
+    return file;
+}
+export async function readHostLoopEvents(input = {}) {
+    const file = resolveLoopEventsPath(input);
+    const text = await readFile(file, "utf8").catch((err) => {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT")
+            return "";
+        throw err;
+    });
+    const events = parseLoopEvents(text);
+    const filtered = events.filter((event) => matchesLoopEvent(event, input));
+    const tail = normalizeTail(input.tail);
+    const display = filtered.slice(-tail);
+    const results = await maybeWriteLoopResults(events, input, file);
+    return {
+        file,
+        events: display,
+        totalEvents: events.length,
+        filteredEvents: filtered.length,
+        summary: summarizeLoopEvents(filtered),
+        results
+    };
+}
+export async function readHostLoopResults(input = {}) {
+    const eventsFile = resolveLoopEventsPath(input);
+    const file = resolveLoopResultsPath(input, eventsFile);
+    const existing = await readFile(file, "utf8").catch((err) => {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT")
+            return undefined;
+        throw err;
+    });
+    if (existing !== undefined) {
+        return {
+            file,
+            rows: parseLoopResultsTable(existing),
+            written: false,
+            text: existing
+        };
+    }
+    const eventsText = await readFile(eventsFile, "utf8").catch((err) => {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT")
+            return "";
+        throw err;
+    });
+    const rows = buildLoopResultsRows(parseLoopEvents(eventsText));
+    return {
+        file,
+        rows,
+        written: false,
+        text: formatLoopResultsTable(rows)
+    };
+}
+export function formatHostLoopEvents(result) {
+    if (result.events.length === 0) {
+        return [
+            `host run events: ${result.file}`,
+            "no loop events"
+        ].join("\n");
+    }
+    const lines = [
+        `host run events: ${result.file}`,
+        `${result.events.length} shown (${result.filteredEvents} matched, ${result.totalEvents} total)`
+    ];
+    for (const event of result.events) {
+        lines.push(formatHostLoopEvent(event));
+    }
+    if (result.summary.loops > 0) {
+        lines.push(`summary: ${result.summary.loops} classified loops, productive=${result.summary.productiveRate}%`);
+    }
+    if (result.results.written) {
+        lines.push(`results: ${result.results.file} (${result.results.rows.length} rows)`);
+    }
+    return lines.join("\n");
+}
+function resolveLoopEventsPath(input) {
+    if (input.file && input.file.trim())
+        return resolve(input.file);
+    const outputDir = input.outputDir && input.outputDir.trim() ? input.outputDir : "deliverables";
+    return resolve(join(outputDir, "loop-events.ndjson"));
+}
+function resolveLoopResultsPath(input, eventsFile) {
+    if (input.resultsFile && input.resultsFile.trim())
+        return resolve(input.resultsFile);
+    const outputDir = input.outputDir && input.outputDir.trim() ? input.outputDir : dirname(eventsFile);
+    return resolve(join(outputDir, "results.tsv"));
+}
+function parseLoopEvents(text) {
+    const events = [];
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === "object")
+                events.push(parsed);
+        }
+        catch {
+            // Ignore malformed lines so a partially written NDJSON file stays readable.
+        }
+    }
+    return events;
+}
+function matchesLoopEvent(event, input) {
+    if (input.runId && event.runId !== input.runId)
+        return false;
+    if (input.agent && event.agent !== input.agent)
+        return false;
+    if (input.type && event.type !== input.type)
+        return false;
+    if (input.classification && event.classification !== input.classification)
+        return false;
+    return true;
+}
+function summarizeLoopEvents(events) {
+    const classifications = {};
+    for (const event of events) {
+        if (event.type !== "loop.classified" || typeof event.classification !== "string")
+            continue;
+        classifications[event.classification] = (classifications[event.classification] ?? 0) + 1;
+    }
+    const loops = Object.values(classifications).reduce((sum, count) => sum + count, 0);
+    const productive = classifications.productive ?? 0;
+    return {
+        loops,
+        classifications,
+        productiveRate: loops > 0 ? Math.round((productive / loops) * 100) : 0
+    };
+}
+async function maybeWriteLoopResults(events, input, eventsFile) {
+    const file = resolveLoopResultsPath(input, eventsFile);
+    const rows = buildLoopResultsRows(events);
+    if (input.writeResults === false || (events.length === 0 && input.writeResults !== true))
+        return { file, rows, written: false };
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, formatLoopResultsTable(rows), "utf8");
+    return { file, rows, written: true };
+}
+export function buildLoopResultsRows(events) {
+    const rows = [];
+    for (const event of events) {
+        if (event.type !== "loop.classified" || typeof event.classification !== "string")
+            continue;
+        const runId = typeof event.runId === "string" && event.runId.trim() ? event.runId.trim() : "";
+        const loop = numberValue(event.loop);
+        if (loop === undefined)
+            continue;
+        const loopEvents = events.filter((entry) => sameLoop(entry, runId, loop));
+        rows.push({
+            runId,
+            loop,
+            timestamp: typeof event.timestamp === "string" ? event.timestamp : "",
+            classification: event.classification,
+            tasksCreated: loopEvents.filter((entry) => entry.type === "task.created").length,
+            tasksDone: loopEvents.filter((entry) => entry.type === "task.transition" && doneStatus(entry.to)).length,
+            artifactsCreated: loopEvents.filter((entry) => entry.type === "artifact.created").length,
+            pendingMessages: maxNumber(loopEvents.map((entry) => numberValue(entry.pendingMessages) ?? numberValue(entry.pending))),
+            completionRate: completionRateValue(event),
+            notes: notesValue(event)
+        });
+    }
+    return rows.sort((a, b) => a.runId.localeCompare(b.runId) || a.loop - b.loop || a.timestamp.localeCompare(b.timestamp));
+}
+export function formatLoopResultsTable(rows) {
+    return HOST_LOOP_RESULTS_HEADER + rows.map((row) => [
+        row.runId,
+        String(row.loop),
+        row.timestamp,
+        row.classification,
+        String(row.tasksCreated),
+        String(row.tasksDone),
+        String(row.artifactsCreated),
+        String(row.pendingMessages),
+        row.completionRate,
+        row.notes
+    ].map(tsvCell).join("\t")).join("\n") + (rows.length ? "\n" : "");
+}
+export function parseLoopResultsTable(text) {
+    const lines = text.split(/\r?\n/).filter((line) => line.trim());
+    if (lines.length <= 1)
+        return [];
+    const header = lines[0]?.split("\t") ?? [];
+    const index = new Map(header.map((name, i) => [name, i]));
+    return lines.slice(1).map((line) => {
+        const cells = line.split("\t");
+        return {
+            runId: cell(cells, index, "run_id"),
+            loop: Number.parseInt(cell(cells, index, "loop") || "0", 10) || 0,
+            timestamp: cell(cells, index, "timestamp"),
+            classification: cell(cells, index, "classification"),
+            tasksCreated: Number.parseInt(cell(cells, index, "tasks_created") || "0", 10) || 0,
+            tasksDone: Number.parseInt(cell(cells, index, "tasks_done") || "0", 10) || 0,
+            artifactsCreated: Number.parseInt(cell(cells, index, "artifacts_created") || "0", 10) || 0,
+            pendingMessages: Number.parseInt(cell(cells, index, "pending_messages") || "0", 10) || 0,
+            completionRate: cell(cells, index, "completion_rate"),
+            notes: cell(cells, index, "notes")
+        };
+    });
+}
+function cell(cells, index, name) {
+    const i = index.get(name);
+    return i === undefined ? "" : cells[i] ?? "";
+}
+function sameLoop(event, runId, loop) {
+    const eventRunId = typeof event.runId === "string" ? event.runId : "";
+    return eventRunId === runId && numberValue(event.loop) === loop;
+}
+function doneStatus(value) {
+    return value === "done" || value === "completed" || value === "complete";
+}
+function completionRateValue(event) {
+    const value = numberValue(event.completionRate) ?? numberValue(event.completion_rate);
+    return value === undefined ? "" : String(value);
+}
+function notesValue(event) {
+    if (Array.isArray(event.reasons))
+        return event.reasons.map(String).join("; ");
+    if (typeof event.notes === "string")
+        return event.notes;
+    if (typeof event.reason === "string")
+        return event.reason;
+    return "";
+}
+function maxNumber(values) {
+    const numeric = values.filter((value) => value !== undefined);
+    return numeric.length ? Math.max(...numeric) : 0;
+}
+function numberValue(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim()) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function tsvCell(value) {
+    return value.replace(/\t/g, " ").replace(/\r?\n/g, " ").trim();
+}
+function formatHostLoopEvent(event) {
+    const ts = typeof event.timestamp === "string" ? event.timestamp : "no-time";
+    const loop = event.loop === undefined ? "?" : String(event.loop);
+    const type = typeof event.type === "string" ? event.type : "unknown";
+    if (type === "loop.classified") {
+        const reasons = Array.isArray(event.reasons) ? event.reasons.join("; ") : "";
+        return `${ts} loop=${loop} ${type} ${event.classification ?? "unknown"}${reasons ? ` ${reasons}` : ""}`;
+    }
+    if (type === "task.transition") {
+        return `${ts} loop=${loop} ${type} task=${event.taskId ?? "?"} ${event.from ?? "?"}->${event.to ?? "?"}`;
+    }
+    if (type === "queue.backlog") {
+        return `${ts} loop=${loop} ${type} agent=${event.agent ?? "?"} pending=${event.pendingMessages ?? event.pending ?? "?"}`;
+    }
+    if (type === "agent.spawned") {
+        return `${ts} loop=${loop} ${type} agent=${event.agent ?? "?"} trigger=${event.trigger ?? "?"}`;
+    }
+    return `${ts} loop=${loop} ${type} ${JSON.stringify(event).slice(0, 120)}`;
+}
+function dropUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function normalizeTail(value) {
+    if (value === undefined || value === null || value === "")
+        return 20;
+    const tail = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+    if (!Number.isFinite(tail) || tail < 1)
+        throw new Error("loop event tail must be a positive integer");
+    return Math.floor(tail);
+}

package/dist/src/host-permission.d.ts

@@ -0,0 +1,36 @@
+import { type KingTeamPermissionAction, type KingTeamPermissionRule, type KingTeamSpec } from "./team-workflow.js";
+export interface HostPermissionRequest {
+    actorRole?: string;
+}
+export interface HostPermissionDeps {
+    teamSpec?: () => KingTeamSpec | null | undefined;
+    env?: NodeJS.ProcessEnv;
+}
+export interface HostPermissionOutcome {
+    enforced: boolean;
+    role?: string;
+    action: KingTeamPermissionAction | null;
+    decision?: "allow" | "deny" | "human-decision";
+    rule?: KingTeamPermissionRule;
+}
+export declare function hostCommandPermissionAction(command: string, input?: unknown): KingTeamPermissionAction | null;
+export declare function resolveActorRole(request: HostPermissionRequest, env?: NodeJS.ProcessEnv): string | undefined;
+export declare function resolveTeamSpec(deps?: HostPermissionDeps): KingTeamSpec;
+/**
+ * Evaluate whether `request.actorRole` may run `command` under the team governance policy.
+ * Governance is opt-in: when no role is resolved (request field or KING_AI_TEAM_ROLE), trusted local
+ * automation proceeds exactly as before. This is not the host security boundary.
+ */
+export declare function evaluateHostCommandPermission(command: string, input: unknown, request: HostPermissionRequest, deps?: HostPermissionDeps): HostPermissionOutcome;
+export interface HumanApprovalOutcome {
+    approved: boolean;
+    approver?: string;
+    reason?: string;
+}
+/**
+ * Evaluate a human-decision marker supplied on a re-issued command. The marker is only valid when
+ * `approvedBy` is present AND differs from the requesting role, so a role cannot clear its own
+ * governance gate by simply setting `humanApproved=true`. This is still an automation-friendly
+ * governance/audit control, not a cryptographic identity check.
+ */
+export declare function resolveHumanApproval(input: unknown, requesterRole?: string): HumanApprovalOutcome;

package/dist/src/host-permission.js

@@ -0,0 +1,180 @@
+import { checkTeamPermission, defaultTeamSpec, normalizeTeamRoleId } from "./team-workflow.js";
+/**
+ * Map an allowlisted host command (and its input) to the team governance action it represents.
+ * Returns null when the command has no role-governance concern (read-only, observability, or run
+ * lifecycle plumbing already gated by other policy).
+ */
+const PERMISSION_ACTIONS = [
+    "assign-task",
+    "claim-task",
+    "create-artifact",
+    "create-decision",
+    "approve-decision",
+    "close-task",
+    "change-scope",
+    "deploy-release",
+    "view-audit",
+    "manage-queue",
+    "view-cost"
+];
+export function hostCommandPermissionAction(command, input) {
+    // An explicit, valid `permissionAction` on the input is authoritative — callers that know their
+    // intent can opt out of the heuristic inference below. It can only tighten authorization (the
+    // action is still checked against the role policy), never bypass it.
+    const explicit = explicitPermissionAction(input);
+    if (explicit)
+        return explicit;
+    switch (command) {
+        case "timeline":
+            return "view-audit";
+        case "usage":
+        case "expenses":
+            return "view-cost";
+        case "task-create":
+        case "initiative-create":
+        case "handoff-create":
+        case "capsule-create":
+            return "assign-task";
+        case "task-update":
+            return ledgerMutationAction(input);
+        case "capsule-update":
+            return "claim-task";
+        case "artifact-create":
+        case "review-create":
+            return "create-artifact";
+        case "decision-create":
+            return "create-decision";
+        case "workflow-create":
+            return workflowCreateAction(input);
+        case "workflow-update":
+            return workflowUpdateAction(input);
+        case "submit-run":
+        case "cancel-run":
+        case "update-run":
+        case "compact-ledger":
+            return "manage-queue";
+        case "execute-run":
+            return "deploy-release";
+        case "export":
+            return "create-artifact";
+        default:
+            return null;
+    }
+}
+export function resolveActorRole(request, env = process.env) {
+    return cleanString(request.actorRole) ?? cleanString(env.KING_AI_TEAM_ROLE);
+}
+export function resolveTeamSpec(deps = {}) {
+    const provided = deps.teamSpec?.();
+    if (provided)
+        return provided;
+    const raw = (deps.env ?? process.env).KING_AI_TEAM_SPEC;
+    if (raw && raw.trim()) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (isTeamSpec(parsed))
+                return parsed;
+        }
+        catch {
+            // fall through to the built-in default team spec
+        }
+    }
+    return defaultTeamSpec();
+}
+/**
+ * Evaluate whether `request.actorRole` may run `command` under the team governance policy.
+ * Governance is opt-in: when no role is resolved (request field or KING_AI_TEAM_ROLE), trusted local
+ * automation proceeds exactly as before. This is not the host security boundary.
+ */
+export function evaluateHostCommandPermission(command, input, request, deps = {}) {
+    const role = resolveActorRole(request, deps.env ?? process.env);
+    if (!role)
+        return { enforced: false, action: null };
+    const action = hostCommandPermissionAction(command, input);
+    if (!action)
+        return { enforced: false, role, action: null };
+    const team = resolveTeamSpec(deps);
+    const normalizedRole = normalizeTeamRoleId(role);
+    const result = checkTeamPermission(team, normalizedRole, action);
+    return { enforced: true, role: normalizedRole, action, decision: result.decision, rule: result.rule };
+}
+/**
+ * Evaluate a human-decision marker supplied on a re-issued command. The marker is only valid when
+ * `approvedBy` is present AND differs from the requesting role, so a role cannot clear its own
+ * governance gate by simply setting `humanApproved=true`. This is still an automation-friendly
+ * governance/audit control, not a cryptographic identity check.
+ */
+export function resolveHumanApproval(input, requesterRole) {
+    if (!input || typeof input !== "object")
+        return { approved: false, reason: "no approval provided" };
+    const record = input;
+    const flagged = record.humanApproved === true || record.humanDecision === "approved";
+    if (!flagged)
+        return { approved: false, reason: "set humanApproved=true to grant approval" };
+    const approver = cleanString(record.approvedBy);
+    if (!approver)
+        return { approved: false, reason: "approvedBy is required (the human or role granting approval)" };
+    if (requesterRole && approver === requesterRole) {
+        return { approved: false, approver, reason: "approver must differ from the requesting role" };
+    }
+    return { approved: true, approver };
+}
+function explicitPermissionAction(input) {
+    if (!input || typeof input !== "object")
+        return null;
+    const value = input.permissionAction;
+    return typeof value === "string" && PERMISSION_ACTIONS.includes(value)
+        ? value
+        : null;
+}
+function ledgerMutationAction(input) {
+    const status = stringField(input, "status");
+    if (status === "done" || status === "cancelled")
+        return "close-task";
+    if (hasField(input, "acceptance") || hasField(input, "dependsOn"))
+        return "change-scope";
+    return "claim-task";
+}
+function workflowCreateAction(input) {
+    switch (stringField(input, "kind")) {
+        case "decision":
+            return "create-decision";
+        case "artifact":
+        case "review":
+            return "create-artifact";
+        default:
+            return "assign-task";
+    }
+}
+function workflowUpdateAction(input) {
+    const id = stringField(input, "id") ?? "";
+    const kind = stringField(input, "kind");
+    if (kind === "decision" || id.startsWith("decision-") || id.startsWith("decision:"))
+        return "approve-decision";
+    if (hasField(input, "acceptance") || hasField(input, "dependsOn"))
+        return "change-scope";
+    const status = stringField(input, "status");
+    if (status === "done" || status === "cancelled")
+        return "close-task";
+    return "claim-task";
+}
+function isTeamSpec(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return typeof record.id === "string"
+        && Array.isArray(record.roles)
+        && Boolean(record.permissionPolicy)
+        && Array.isArray(record.permissionPolicy.rules);
+}
+function stringField(input, key) {
+    if (!input || typeof input !== "object")
+        return undefined;
+    return cleanString(input[key]);
+}
+function hasField(input, key) {
+    return Boolean(input && typeof input === "object" && input[key] !== undefined);
+}
+function cleanString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/dist/src/host-policy.d.ts

@@ -0,0 +1,15 @@
+export type HostPolicyDecision = "allow" | "confirm_required";
+export interface HostPolicyCheck {
+    command: string;
+    destructive: boolean;
+    decision: HostPolicyDecision;
+    reason: string;
+    requiredConfirmation?: string;
+}
+export interface HostPolicyInput {
+    confirmed?: unknown;
+    confirmation?: unknown;
+}
+export declare function requiredHostConfirmation(command: string): string;
+export declare function checkHostCommandPolicy(command: string, destructive: boolean, input?: HostPolicyInput): HostPolicyCheck;
+export declare function formatHostPolicyCheck(check: HostPolicyCheck): string;

package/dist/src/host-policy.js

@@ -0,0 +1,36 @@
+export function requiredHostConfirmation(command) {
+    return `allow:${command}`;
+}
+export function checkHostCommandPolicy(command, destructive, input) {
+    if (!destructive) {
+        return {
+            command,
+            destructive,
+            decision: "allow",
+            reason: "read-only host command"
+        };
+    }
+    const requiredConfirmation = requiredHostConfirmation(command);
+    if (input?.confirmed === true || input?.confirmation === requiredConfirmation) {
+        return {
+            command,
+            destructive,
+            decision: "allow",
+            reason: "destructive host command explicitly confirmed",
+            requiredConfirmation
+        };
+    }
+    return {
+        command,
+        destructive,
+        decision: "confirm_required",
+        reason: "destructive host command requires explicit confirmation",
+        requiredConfirmation
+    };
+}
+export function formatHostPolicyCheck(check) {
+    if (check.decision === "allow") {
+        return `${check.command}: allowed (${check.reason})`;
+    }
+    return `${check.command}: confirmation required (${check.reason}; confirmation=${check.requiredConfirmation})`;
+}

package/dist/src/host-run-executor.d.ts

@@ -0,0 +1,13 @@
+import type { HostRunRequest } from "./host-runs.js";
+import type { HostCommandResult, HostCommandRunnerDeps } from "./host-control.js";
+export interface HostRunExecuteInput {
+    id?: string;
+}
+export interface HostRunExecuteResult {
+    request?: HostRunRequest;
+    commandResult?: HostCommandResult;
+    summary: string;
+}
+export declare function listSafeHostExecutorCommands(): string[];
+export declare function executeNextHostRunRequest(input?: HostRunExecuteInput, deps?: HostCommandRunnerDeps): Promise<HostRunExecuteResult>;
+export declare function formatHostRunExecuteResult(result: HostRunExecuteResult): string;