@suwujs/king-ai 0.2.0

package/dist/src/host-run-executor.js

@@ -0,0 +1,221 @@
+import { appendHostLoopEvent } from "./host-loop-events.js";
+import { hostRunHeartbeatPathForOutputDir, writeHostRunHeartbeat } from "./host-run-heartbeat.js";
+import { hostRunMetaPathForOutputDir, updateHostRunMeta } from "./host-run-meta.js";
+import { formatHostRunRequestSummary, listHostRunRequests, updateHostRunRequest } from "./host-runs.js";
+import { runHostCommand } from "./host-control.js";
+const EXECUTOR_SAFE_COMMANDS = new Set([
+    "status",
+    "usage",
+    "expenses",
+    "events",
+    "timeline",
+    "policy",
+    "doctor",
+    "plan-run",
+    "preflight",
+    "plan-export"
+]);
+export function listSafeHostExecutorCommands() {
+    return [...EXECUTOR_SAFE_COMMANDS];
+}
+export async function executeNextHostRunRequest(input = {}, deps = {}) {
+    const request = await selectExecutableRequest(input, deps);
+    if (!request) {
+        return { summary: "no executable host run requests" };
+    }
+    if (!request.executor) {
+        return { request, summary: `host run request ${request.id} has no executor` };
+    }
+    const command = request.executor.command.trim().toLowerCase();
+    if (!EXECUTOR_SAFE_COMMANDS.has(command)) {
+        const failed = await updateHostRunRequest({
+            id: request.id,
+            status: "failed",
+            detail: `executor command is not allowed: ${request.executor.command}`,
+            result: {
+                command: request.executor.command,
+                ok: false,
+                exitCode: 64,
+                error: "executor command is not allowed"
+            }
+        }, {
+            path: deps.runsPath,
+            now: deps.now
+        });
+        await writeRequestHeartbeat(failed.request, "failed", {
+            detail: failed.request.detail,
+            command: request.executor.command,
+            exitCode: 64,
+            loopCount: 0,
+            now: deps.now
+        });
+        await writeRequestMeta(failed.request, "failed", {
+            detail: failed.request.detail,
+            command: request.executor.command,
+            exitCode: 64,
+            actualLoops: 0,
+            now: deps.now
+        });
+        await writeRequestLoopEvent(failed.request, "failed", {
+            detail: failed.request.detail,
+            command: request.executor.command,
+            exitCode: 64,
+            loop: 0,
+            now: deps.now
+        });
+        return {
+            request: failed.request,
+            summary: failed.summary
+        };
+    }
+    await updateHostRunRequest({
+        id: request.id,
+        status: "running",
+        detail: `executing ${command}`
+    }, {
+        path: deps.runsPath,
+        now: deps.now
+    });
+    await writeRequestHeartbeat(request, "running", {
+        detail: `executing ${command}`,
+        command,
+        loopCount: 0,
+        now: deps.now
+    });
+    await writeRequestMeta(request, "running", {
+        detail: `executing ${command}`,
+        command,
+        actualLoops: 0,
+        now: deps.now
+    });
+    await writeRequestLoopEvent(request, "running", {
+        detail: `executing ${command}`,
+        command,
+        loop: 0,
+        now: deps.now
+    });
+    const commandResult = await runHostCommand({
+        command,
+        format: request.executor.format,
+        input: request.executor.input,
+        actorRole: request.executor.actorRole
+    }, {
+        ...deps,
+        recordTimeline: deps.recordTimeline ?? true,
+        enforcePermission: request.executor.trusted === true ? false : deps.enforcePermission
+    });
+    const completed = await updateHostRunRequest({
+        id: request.id,
+        status: commandResult.ok ? "completed" : "failed",
+        detail: commandResult.ok ? `completed ${command}` : `failed ${command}`,
+        result: {
+            command,
+            ok: commandResult.ok,
+            exitCode: commandResult.exitCode,
+            textPreview: compact(commandResult.text),
+            error: commandResult.error
+        }
+    }, {
+        path: deps.runsPath,
+        now: deps.now
+    });
+    await writeRequestHeartbeat(completed.request, commandResult.ok ? "completed" : "failed", {
+        detail: completed.request.detail,
+        command,
+        exitCode: commandResult.exitCode,
+        loopCount: 1,
+        now: deps.now
+    });
+    await writeRequestMeta(completed.request, commandResult.ok ? "completed" : "failed", {
+        detail: completed.request.detail,
+        command,
+        exitCode: commandResult.exitCode,
+        actualLoops: 1,
+        now: deps.now
+    });
+    await writeRequestLoopEvent(completed.request, commandResult.ok ? "completed" : "failed", {
+        detail: completed.request.detail,
+        command,
+        exitCode: commandResult.exitCode,
+        loop: 1,
+        now: deps.now
+    });
+    return {
+        request: completed.request,
+        commandResult,
+        summary: completed.summary
+    };
+}
+async function writeRequestMeta(request, status, input) {
+    const outputDir = request.spec.options?.outputDir;
+    if (!outputDir)
+        return;
+    await updateHostRunMeta({
+        file: hostRunMetaPathForOutputDir(outputDir),
+        runId: request.id,
+        status,
+        actualLoops: input.actualLoops,
+        detail: input.detail,
+        command: input.command,
+        exitCode: input.exitCode,
+        now: input.now
+    });
+}
+async function writeRequestLoopEvent(request, status, input) {
+    const outputDir = request.spec.options?.outputDir;
+    if (!outputDir)
+        return;
+    await appendHostLoopEvent({
+        outputDir,
+        event: {
+            type: "run.status",
+            runId: request.id,
+            timestamp: (input.now ?? (() => new Date()))().toISOString(),
+            status,
+            detail: input.detail,
+            command: input.command,
+            exitCode: input.exitCode,
+            loop: input.loop,
+            source: "execute-run"
+        }
+    });
+}
+export function formatHostRunExecuteResult(result) {
+    if (!result.request)
+        return result.summary;
+    return [
+        result.summary,
+        result.commandResult ? `command: ${result.commandResult.command} exit=${result.commandResult.exitCode}` : "",
+        formatHostRunRequestSummary(result.request)
+    ].filter(Boolean).join("\n");
+}
+async function selectExecutableRequest(input, deps) {
+    const requests = await listHostRunRequests({ limit: 100, status: "pending" }, deps.runsPath);
+    const oldestFirst = [...requests].reverse();
+    if (input.id)
+        return oldestFirst.find((request) => request.id === input.id);
+    return oldestFirst.find((request) => request.executor?.kind === "host-command");
+}
+function compact(value) {
+    const text = value.replace(/\s+/g, " ").trim();
+    if (!text)
+        return undefined;
+    return text.length > 240 ? `${text.slice(0, 237)}...` : text;
+}
+async function writeRequestHeartbeat(request, status, input) {
+    const outputDir = request.spec.options?.outputDir;
+    if (!outputDir)
+        return;
+    await writeHostRunHeartbeat({
+        path: hostRunHeartbeatPathForOutputDir(outputDir),
+        runId: request.id,
+        status,
+        outputDir,
+        pid: process.pid,
+        detail: input.detail,
+        command: input.command,
+        exitCode: input.exitCode,
+        loopCount: input.loopCount,
+        now: input.now
+    });
+}

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

@@ -0,0 +1,40 @@
+export type HostRunHeartbeatStatus = "prepared" | "running" | "completed" | "failed" | "cancelled";
+export interface HostRunHeartbeatData {
+    schema: "king-ai.host-run-heartbeat.v1";
+    status: HostRunHeartbeatStatus;
+    runId: string;
+    lastTick: string;
+    updatedAt: string;
+    loopCount: number;
+    outputDir?: string;
+    pid?: number;
+    detail?: string;
+    command?: string;
+    exitCode?: number;
+}
+export interface HostRunHeartbeatInput {
+    path: string;
+    runId: string;
+    status: HostRunHeartbeatStatus;
+    outputDir?: string;
+    loopCount?: number;
+    pid?: number;
+    detail?: string;
+    command?: string;
+    exitCode?: number;
+    now?: () => Date;
+}
+export interface HostRunHeartbeatReadInput {
+    file?: string;
+    outputDir?: string;
+}
+export interface HostRunHeartbeatReadResult {
+    file: string;
+    heartbeat: HostRunHeartbeatData | null;
+    exists: boolean;
+}
+export declare function hostRunHeartbeatPathForOutputDir(outputDir: string): string;
+export declare function resolveHostRunHeartbeatPath(input?: HostRunHeartbeatReadInput): string;
+export declare function readHostRunHeartbeat(input?: HostRunHeartbeatReadInput): Promise<HostRunHeartbeatReadResult>;
+export declare function formatHostRunHeartbeat(result: HostRunHeartbeatReadResult): string;
+export declare function writeHostRunHeartbeat(input: HostRunHeartbeatInput): Promise<HostRunHeartbeatData>;

package/dist/src/host-run-heartbeat.js

@@ -0,0 +1,103 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+export function hostRunHeartbeatPathForOutputDir(outputDir) {
+    return join(resolve(outputDir), ".king-ai", "heartbeat.json");
+}
+export function resolveHostRunHeartbeatPath(input = {}) {
+    if (input.file && input.file.trim())
+        return resolve(input.file);
+    const outputDir = input.outputDir && input.outputDir.trim() ? input.outputDir : "deliverables";
+    return hostRunHeartbeatPathForOutputDir(outputDir);
+}
+export async function readHostRunHeartbeat(input = {}) {
+    const file = resolveHostRunHeartbeatPath(input);
+    const text = await readFile(file, "utf8").catch((err) => {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT")
+            return undefined;
+        throw err;
+    });
+    if (text === undefined) {
+        return {
+            file,
+            heartbeat: null,
+            exists: false
+        };
+    }
+    return {
+        file,
+        heartbeat: parseHostRunHeartbeat(text),
+        exists: true
+    };
+}
+export function formatHostRunHeartbeat(result) {
+    if (!result.heartbeat)
+        return `host run heartbeat: ${result.file}\nnot found`;
+    return [
+        `host run heartbeat: ${result.file}`,
+        `run: ${result.heartbeat.runId}`,
+        `status: ${result.heartbeat.status}`,
+        `last tick: ${result.heartbeat.lastTick}`,
+        `loops: ${result.heartbeat.loopCount}`,
+        result.heartbeat.command ? `command: ${result.heartbeat.command}${result.heartbeat.exitCode !== undefined ? ` exit=${result.heartbeat.exitCode}` : ""}` : "",
+        result.heartbeat.detail ? `detail: ${result.heartbeat.detail}` : ""
+    ].filter(Boolean).join("\n");
+}
+export async function writeHostRunHeartbeat(input) {
+    const now = (input.now ?? (() => new Date()))().toISOString();
+    const data = {
+        schema: "king-ai.host-run-heartbeat.v1",
+        status: input.status,
+        runId: input.runId,
+        lastTick: now,
+        updatedAt: now,
+        loopCount: Math.max(0, Math.floor(input.loopCount ?? 0)),
+        outputDir: input.outputDir,
+        pid: input.pid,
+        detail: cleanString(input.detail),
+        command: cleanString(input.command),
+        exitCode: normalizeExitCode(input.exitCode)
+    };
+    await mkdir(dirname(input.path), { recursive: true });
+    await writeFile(input.path, `${JSON.stringify(dropUndefined({ ...data }), null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    return data;
+}
+function cleanString(value) {
+    return typeof value === "string" && value.trim() ? value.trim().slice(0, 1000) : undefined;
+}
+function normalizeExitCode(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? Math.floor(parsed) : undefined;
+}
+function parseHostRunHeartbeat(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || parsed.schema !== "king-ai.host-run-heartbeat.v1" || typeof parsed.runId !== "string")
+            return null;
+        if (!isHostRunHeartbeatStatus(parsed.status))
+            return null;
+        return {
+            schema: "king-ai.host-run-heartbeat.v1",
+            status: parsed.status,
+            runId: parsed.runId,
+            lastTick: typeof parsed.lastTick === "string" ? parsed.lastTick : "",
+            updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : "",
+            loopCount: typeof parsed.loopCount === "number" ? parsed.loopCount : 0,
+            outputDir: typeof parsed.outputDir === "string" ? parsed.outputDir : undefined,
+            pid: typeof parsed.pid === "number" ? parsed.pid : undefined,
+            detail: typeof parsed.detail === "string" ? parsed.detail : undefined,
+            command: typeof parsed.command === "string" ? parsed.command : undefined,
+            exitCode: typeof parsed.exitCode === "number" ? parsed.exitCode : undefined
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isHostRunHeartbeatStatus(value) {
+    return value === "prepared" || value === "running" || value === "completed" || value === "failed" || value === "cancelled";
+}
+function dropUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}

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

@@ -0,0 +1,17 @@
+import type { HostLaunchPlan, HostRunSpecInput } from "./host-run-spec.js";
+import { toJsonSafeHostLaunchPlan } from "./host-run-spec.js";
+export interface HostRunLayoutInput extends HostRunSpecInput {
+    force?: boolean;
+}
+export interface HostRunLayoutResult {
+    launchPlan: ReturnType<typeof toJsonSafeHostLaunchPlan>;
+    writtenFiles: string[];
+    copiedDirectories: string[];
+    summary: string;
+}
+export declare function prepareHostRunLayout(input: HostRunLayoutInput, options?: {
+    env?: NodeJS.ProcessEnv;
+    availableEngines?: Array<"claude" | "codex">;
+}): Promise<HostRunLayoutResult>;
+export declare function formatHostRunLayoutResult(plan: HostLaunchPlan, writtenFiles: string[], copiedDirectories: string[]): string;
+export declare function createDefaultHostRunConfigText(plan: HostLaunchPlan): string;