@suwujs/king-ai 0.2.0

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

@@ -0,0 +1,50 @@
+import type { HostCapsule } from "./host-ledger.js";
+export interface HostExportInput {
+    workspaceRoot?: string;
+    repoRoot?: string;
+    outputDir?: string;
+    runId?: string;
+    includeWorkspace?: boolean;
+    includeRepoPatch?: boolean;
+    capsuleId?: string;
+    capsulesFile?: string;
+}
+export interface HostExportPlan {
+    runId: string;
+    outputDir: string;
+    exportDir: string;
+    workspaceRoot?: string;
+    repoRoot?: string;
+    includeWorkspace: boolean;
+    includeRepoPatch: boolean;
+    capsuleId?: string;
+    capsule?: HostCapsule;
+    workspaceFileCount: number;
+    repoDirty: boolean;
+    files: string[];
+    summary: string;
+}
+export interface HostExportResult extends HostExportPlan {
+    writtenFiles: string[];
+}
+export interface HostExportMeta {
+    schema: "king-ai.host-export.v1";
+    runId: string;
+    exportedAt: string;
+    outputDir: string;
+    exportDir: string;
+    workspaceRoot?: string;
+    repoRoot?: string;
+    includeWorkspace: boolean;
+    includeRepoPatch: boolean;
+    capsuleId?: string;
+    capsule?: HostCapsule;
+    workspaceFileCount: number;
+    repoDirty: boolean;
+    files: string[];
+    writtenFiles: string[];
+}
+export declare function planHostExport(input?: HostExportInput): Promise<HostExportPlan>;
+export declare function exportHostArtifacts(input?: HostExportInput): Promise<HostExportResult>;
+export declare function formatHostExportPlan(plan: HostExportPlan): string;
+export declare function createHostExportMeta(plan: HostExportPlan, writtenFiles: string[], now?: Date): HostExportMeta;

package/dist/src/host-export.js

@@ -0,0 +1,187 @@
+import { execFileSync } from "node:child_process";
+import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { getHostCapsule } from "./host-ledger.js";
+import { isGitRepo } from "./worktree.js";
+export async function planHostExport(input = {}) {
+    const explicitRunId = cleanString(input.runId);
+    const runId = explicitRunId ? safeFilenameSegment(explicitRunId, "runId") : buildExportRunId();
+    const outputDir = resolve(cleanString(input.outputDir) || "deliverables");
+    const exportDir = join(outputDir, runId);
+    const workspaceRoot = resolveOptionalExistingDir(input.workspaceRoot, "workspaceRoot");
+    const repoRoot = resolveOptionalExistingDir(input.repoRoot, "repoRoot");
+    const includeWorkspace = input.includeWorkspace ?? Boolean(workspaceRoot);
+    const includeRepoPatch = input.includeRepoPatch ?? Boolean(repoRoot);
+    const capsuleId = cleanString(input.capsuleId);
+    const capsule = capsuleId ? await getHostCapsule({ outputDir, capsulesFile: input.capsulesFile, id: capsuleId }) ?? undefined : undefined;
+    if (capsuleId && !capsule)
+        throw new Error(`host capsule not found: ${capsuleId}`);
+    const workspaceFileCount = includeWorkspace && workspaceRoot ? countFiles(workspaceRoot) : 0;
+    const repoDirty = includeRepoPatch && repoRoot ? gitStatus(repoRoot).trim().length > 0 : false;
+    const files = [];
+    if (includeWorkspace && workspaceRoot && workspaceFileCount > 0)
+        files.push(`${basename(workspaceRoot) || "workspace"}/`);
+    if (includeRepoPatch && repoRoot && repoDirty) {
+        files.push("repo-status.txt");
+        if (gitDiff(repoRoot, false).trim())
+            files.push("repo.patch");
+        if (gitDiff(repoRoot, true).trim())
+            files.push("repo-staged.patch");
+    }
+    if (capsule)
+        files.push("capsule.json");
+    files.push("meta.json");
+    const plan = {
+        runId,
+        outputDir,
+        exportDir,
+        workspaceRoot,
+        repoRoot,
+        includeWorkspace,
+        includeRepoPatch,
+        capsuleId,
+        capsule,
+        workspaceFileCount,
+        repoDirty,
+        files,
+        summary: ""
+    };
+    plan.summary = formatHostExportPlan(plan);
+    return plan;
+}
+export async function exportHostArtifacts(input = {}) {
+    const plan = await planHostExport(input);
+    const writtenFiles = [];
+    await rm(plan.exportDir, { recursive: true, force: true });
+    await mkdir(plan.exportDir, { recursive: true });
+    if (plan.includeWorkspace && plan.workspaceRoot && plan.workspaceFileCount > 0) {
+        const target = join(plan.exportDir, basename(plan.workspaceRoot) || "workspace");
+        await cp(plan.workspaceRoot, target, {
+            recursive: true,
+            force: true,
+            dereference: false,
+            filter: (source) => !shouldSkipExportPath(source)
+        });
+        writtenFiles.push(target);
+    }
+    if (plan.includeRepoPatch && plan.repoRoot && plan.repoDirty) {
+        const status = gitStatus(plan.repoRoot);
+        await writeFile(join(plan.exportDir, "repo-status.txt"), status, "utf8");
+        writtenFiles.push(join(plan.exportDir, "repo-status.txt"));
+        const diff = gitDiff(plan.repoRoot, false);
+        if (diff.trim()) {
+            await writeFile(join(plan.exportDir, "repo.patch"), diff, "utf8");
+            writtenFiles.push(join(plan.exportDir, "repo.patch"));
+        }
+        const staged = gitDiff(plan.repoRoot, true);
+        if (staged.trim()) {
+            await writeFile(join(plan.exportDir, "repo-staged.patch"), staged, "utf8");
+            writtenFiles.push(join(plan.exportDir, "repo-staged.patch"));
+        }
+    }
+    if (plan.capsule) {
+        const capsulePath = join(plan.exportDir, "capsule.json");
+        await writeFile(capsulePath, `${JSON.stringify(plan.capsule, null, 2)}\n`, "utf8");
+        writtenFiles.push(capsulePath);
+    }
+    const metaPath = join(plan.exportDir, "meta.json");
+    writtenFiles.push(metaPath);
+    const meta = createHostExportMeta(plan, writtenFiles);
+    await writeFile(metaPath, `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+    return {
+        ...plan,
+        writtenFiles
+    };
+}
+export function formatHostExportPlan(plan) {
+    const lines = [
+        `host export: ${plan.runId}`,
+        `output: ${plan.exportDir}`,
+        `workspace: ${plan.workspaceRoot ?? "(none)"} files=${plan.workspaceFileCount}`,
+        `repo: ${plan.repoRoot ?? "(none)"} dirty=${plan.repoDirty ? "yes" : "no"}`,
+        `capsule: ${plan.capsule?.id ?? "(none)"}`
+    ];
+    if (plan.files.length) {
+        lines.push("planned files:");
+        for (const file of plan.files)
+            lines.push(`  - ${file}`);
+    }
+    else {
+        lines.push("planned files: (none)");
+    }
+    return lines.join("\n");
+}
+export function createHostExportMeta(plan, writtenFiles, now = new Date()) {
+    return {
+        schema: "king-ai.host-export.v1",
+        runId: plan.runId,
+        exportedAt: now.toISOString(),
+        outputDir: plan.outputDir,
+        exportDir: plan.exportDir,
+        workspaceRoot: plan.workspaceRoot,
+        repoRoot: plan.repoRoot,
+        includeWorkspace: plan.includeWorkspace,
+        includeRepoPatch: plan.includeRepoPatch,
+        capsuleId: plan.capsuleId,
+        capsule: plan.capsule,
+        workspaceFileCount: plan.workspaceFileCount,
+        repoDirty: plan.repoDirty,
+        files: plan.files,
+        writtenFiles
+    };
+}
+function cleanString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function safeFilenameSegment(value, label) {
+    if (value === "." || value === ".." || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value)) {
+        throw new Error(`${label} must be a safe filename segment`);
+    }
+    return value;
+}
+function buildExportRunId() {
+    return `export-${new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19)}`;
+}
+function resolveOptionalExistingDir(value, label) {
+    const cleaned = cleanString(value);
+    if (!cleaned)
+        return undefined;
+    const resolved = resolve(cleaned);
+    if (!existsSync(resolved))
+        throw new Error(`${label} does not exist: ${resolved}`);
+    if (!statSync(resolved).isDirectory())
+        throw new Error(`${label} is not a directory: ${resolved}`);
+    if (label === "repoRoot" && !isGitRepo(resolved))
+        throw new Error(`${label} is not a git repository: ${resolved}`);
+    return resolved;
+}
+function shouldSkipExportPath(path) {
+    const normalized = path.replace(/\\/g, "/");
+    return /(^|\/)(\.git|node_modules|\.DS_Store)$/.test(normalized);
+}
+function countFiles(dir) {
+    let count = 0;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === ".git" || entry.name === "node_modules" || entry.name === ".DS_Store")
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            count += countFiles(full);
+        else if (entry.isFile())
+            count += 1;
+    }
+    return count;
+}
+function gitStatus(repoRoot) {
+    return execFileSync("git", ["-C", repoRoot, "status", "--short"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+}
+function gitDiff(repoRoot, staged) {
+    return execFileSync("git", ["-C", repoRoot, "diff", "--binary", ...(staged ? ["--cached"] : [])], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+}

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

@@ -0,0 +1,78 @@
+export interface HostFeedbackPathInput {
+    outputDir?: string;
+    feedbackFile?: string;
+}
+export interface HostFeedbackRecordInput extends HostFeedbackPathInput {
+    runId?: string;
+    agent?: string;
+    taskId?: string;
+    capsuleId?: string;
+    status?: "completed" | "failed" | "partial" | "cancelled";
+    rating?: number;
+    durationMs?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    skill?: string;
+    taskCompleted?: boolean;
+    errored?: boolean;
+    humanIntervention?: boolean;
+    note?: string;
+}
+export interface HostFeedbackListInput extends HostFeedbackPathInput {
+    runId?: string;
+    agent?: string;
+    skill?: string;
+    limit?: number;
+}
+export interface HostFeedbackRecord {
+    schema: "king-ai.host-feedback.v1";
+    createdAt: string;
+    runId?: string;
+    agent?: string;
+    taskId?: string;
+    capsuleId?: string;
+    status: "completed" | "failed" | "partial" | "cancelled";
+    rating?: number;
+    durationMs?: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    skill?: string;
+    taskCompleted: boolean;
+    errored: boolean;
+    humanIntervention: boolean;
+    note?: string;
+}
+export interface HostFeedbackSummary {
+    records: number;
+    completed: number;
+    failed: number;
+    partial: number;
+    cancelled: number;
+    taskCompleted: number;
+    errored: number;
+    humanIntervention: number;
+    totalDurationMs: number;
+    totalTokens: number;
+    byAgent: Array<{
+        agent: string;
+        records: number;
+        completed: number;
+        failed: number;
+        totalTokens: number;
+    }>;
+    bySkill: Array<{
+        skill: string;
+        records: number;
+        completed: number;
+        failed: number;
+        totalTokens: number;
+    }>;
+}
+export declare function hostFeedbackPathForOutputDir(outputDir?: string): string;
+export declare function recordHostFeedback(input: HostFeedbackRecordInput, now?: () => Date): Promise<HostFeedbackRecord>;
+export declare function listHostFeedback(input?: HostFeedbackListInput): Promise<HostFeedbackRecord[]>;
+export declare function summarizeHostFeedback(input?: HostFeedbackListInput): Promise<HostFeedbackSummary>;
+export declare function formatHostFeedback(records: HostFeedbackRecord[]): string;
+export declare function formatHostFeedbackSummary(summary: HostFeedbackSummary): string;

package/dist/src/host-feedback.js

@@ -0,0 +1,178 @@
+import { join, resolve } from "node:path";
+import { appendJsonl, readJsonl } from "./jsonl.js";
+export function hostFeedbackPathForOutputDir(outputDir = "deliverables") {
+    return join(resolve(outputDir), "run-feedback.jsonl");
+}
+export async function recordHostFeedback(input, now = () => new Date()) {
+    const inputTokens = nonNegativeInteger(input.inputTokens, "inputTokens") ?? 0;
+    const outputTokens = nonNegativeInteger(input.outputTokens, "outputTokens") ?? 0;
+    const totalTokens = nonNegativeInteger(input.totalTokens, "totalTokens") ?? inputTokens + outputTokens;
+    const status = normalizeStatus(input.status ?? (input.errored ? "failed" : "completed"));
+    const record = {
+        schema: "king-ai.host-feedback.v1",
+        createdAt: now().toISOString(),
+        runId: cleanString(input.runId),
+        agent: cleanString(input.agent),
+        taskId: cleanString(input.taskId),
+        capsuleId: cleanString(input.capsuleId),
+        status,
+        rating: normalizeRating(input.rating),
+        durationMs: nonNegativeInteger(input.durationMs, "durationMs"),
+        inputTokens,
+        outputTokens,
+        totalTokens,
+        skill: cleanString(input.skill),
+        taskCompleted: input.taskCompleted ?? status === "completed",
+        errored: input.errored ?? status === "failed",
+        humanIntervention: input.humanIntervention ?? false,
+        note: cleanString(input.note)
+    };
+    const cleaned = dropUndefined(record);
+    await appendJsonl(feedbackPath(input), cleaned);
+    return cleaned;
+}
+export async function listHostFeedback(input = {}) {
+    const runId = cleanString(input.runId);
+    const agent = cleanString(input.agent);
+    const skill = cleanString(input.skill);
+    const records = (await readJsonl(feedbackPath(input))).filter(isFeedbackRecord).filter((record) => {
+        if (runId && record.runId !== runId)
+            return false;
+        if (agent && record.agent !== agent)
+            return false;
+        if (skill && record.skill !== skill)
+            return false;
+        return true;
+    });
+    const limit = normalizeLimit(input.limit);
+    return limit ? records.slice(-limit).reverse() : records;
+}
+export async function summarizeHostFeedback(input = {}) {
+    return summarizeFeedback(await listHostFeedback(input));
+}
+export function formatHostFeedback(records) {
+    if (records.length === 0)
+        return "no host feedback";
+    return records.map((record) => {
+        const subject = [record.runId, record.taskId, record.capsuleId].filter(Boolean).join(" ") || "(no subject)";
+        return `${record.createdAt} ${record.status}${record.agent ? ` @${record.agent}` : ""} ${subject} tokens=${record.totalTokens}${record.note ? ` ${record.note}` : ""}`;
+    }).join("\n");
+}
+export function formatHostFeedbackSummary(summary) {
+    const lines = [
+        `feedback: records=${summary.records} completed=${summary.completed} failed=${summary.failed} partial=${summary.partial} cancelled=${summary.cancelled}`,
+        `tasks: completed=${summary.taskCompleted} errored=${summary.errored} humanIntervention=${summary.humanIntervention}`,
+        `usage: durationMs=${summary.totalDurationMs} tokens=${summary.totalTokens}`
+    ];
+    if (summary.byAgent.length) {
+        lines.push("by agent:");
+        for (const entry of summary.byAgent)
+            lines.push(`  - ${entry.agent}: records=${entry.records} completed=${entry.completed} failed=${entry.failed} tokens=${entry.totalTokens}`);
+    }
+    if (summary.bySkill.length) {
+        lines.push("by skill:");
+        for (const entry of summary.bySkill)
+            lines.push(`  - ${entry.skill}: records=${entry.records} completed=${entry.completed} failed=${entry.failed} tokens=${entry.totalTokens}`);
+    }
+    return lines.join("\n");
+}
+function summarizeFeedback(records) {
+    const byAgent = new Map();
+    const bySkill = new Map();
+    const summary = {
+        records: records.length,
+        completed: 0,
+        failed: 0,
+        partial: 0,
+        cancelled: 0,
+        taskCompleted: 0,
+        errored: 0,
+        humanIntervention: 0,
+        totalDurationMs: 0,
+        totalTokens: 0,
+        byAgent: [],
+        bySkill: []
+    };
+    for (const record of records) {
+        summary[record.status] += 1;
+        if (record.taskCompleted)
+            summary.taskCompleted += 1;
+        if (record.errored)
+            summary.errored += 1;
+        if (record.humanIntervention)
+            summary.humanIntervention += 1;
+        summary.totalDurationMs += record.durationMs ?? 0;
+        summary.totalTokens += record.totalTokens;
+        if (record.agent)
+            addGroup(byAgent, record.agent, record);
+        if (record.skill)
+            addSkillGroup(bySkill, record.skill, record);
+    }
+    summary.byAgent = [...byAgent.values()];
+    summary.bySkill = [...bySkill.values()];
+    return summary;
+}
+function addGroup(groups, agent, record) {
+    const entry = groups.get(agent) ?? { agent, records: 0, completed: 0, failed: 0, totalTokens: 0 };
+    entry.records += 1;
+    if (record.status === "completed")
+        entry.completed += 1;
+    if (record.status === "failed")
+        entry.failed += 1;
+    entry.totalTokens += record.totalTokens;
+    groups.set(agent, entry);
+}
+function addSkillGroup(groups, skill, record) {
+    const entry = groups.get(skill) ?? { skill, records: 0, completed: 0, failed: 0, totalTokens: 0 };
+    entry.records += 1;
+    if (record.status === "completed")
+        entry.completed += 1;
+    if (record.status === "failed")
+        entry.failed += 1;
+    entry.totalTokens += record.totalTokens;
+    groups.set(skill, entry);
+}
+function feedbackPath(input) {
+    return input.feedbackFile ? resolve(input.feedbackFile) : hostFeedbackPathForOutputDir(input.outputDir);
+}
+function isFeedbackRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return record.schema === "king-ai.host-feedback.v1" && typeof record.createdAt === "string" && typeof record.totalTokens === "number";
+}
+function normalizeStatus(value) {
+    if (value === "completed" || value === "failed" || value === "partial" || value === "cancelled")
+        return value;
+    throw new Error(`invalid feedback status: ${String(value)}`);
+}
+function normalizeRating(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(parsed) || parsed < 1 || parsed > 5)
+        throw new Error("rating must be between 1 and 5");
+    return parsed;
+}
+function nonNegativeInteger(value, label) {
+    if (value === undefined)
+        return undefined;
+    const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        throw new Error(`${label} must be a non-negative integer`);
+    return Math.floor(parsed);
+}
+function normalizeLimit(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+    if (!Number.isFinite(parsed) || parsed < 1)
+        throw new Error("limit must be a positive integer");
+    return Math.floor(parsed);
+}
+function cleanString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function dropUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}

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

@@ -0,0 +1,13 @@
+export interface HostHomeEntry {
+    name: string;
+    source: string;
+    target: string;
+    linked: boolean;
+    reason?: string;
+}
+export declare function resolveHostHomeEntryNames(env?: NodeJS.ProcessEnv): string[];
+export declare function resolveHostHomeEntry(entry: string, home?: string): {
+    name: string;
+    source: string;
+} | null;
+export declare function linkHostHomeEntries(agentHome: string, env?: NodeJS.ProcessEnv, home?: string): Promise<HostHomeEntry[]>;

package/dist/src/host-home.js

@@ -0,0 +1,54 @@
+import { existsSync, lstatSync } from "node:fs";
+import { mkdir, rm, symlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, delimiter, isAbsolute, join, relative, resolve } from "node:path";
+function splitEntries(value) {
+    if (!value)
+        return [];
+    return value
+        .split(delimiter)
+        .flatMap((part) => part.split(","))
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .filter((entry, idx, all) => all.indexOf(entry) === idx);
+}
+export function resolveHostHomeEntryNames(env = process.env) {
+    return splitEntries(env.KING_AI_HOST_HOME_ENTRIES);
+}
+export function resolveHostHomeEntry(entry, home = homedir()) {
+    if (entry.includes(".."))
+        return null;
+    const expanded = entry.replace(/^~(?=$|\/|\\)/, home);
+    const source = isAbsolute(expanded) ? resolve(expanded) : resolve(home, expanded);
+    const rel = relative(home, source);
+    if (!rel || rel.startsWith("..") || isAbsolute(rel))
+        return null;
+    const parts = rel.split(/[\\/]/);
+    if (parts.length !== 1)
+        return null;
+    const name = basename(source);
+    if (!name.startsWith("."))
+        return null;
+    return { name, source };
+}
+export async function linkHostHomeEntries(agentHome, env = process.env, home = homedir()) {
+    const entries = [];
+    await mkdir(agentHome, { recursive: true });
+    for (const raw of resolveHostHomeEntryNames(env)) {
+        const resolved = resolveHostHomeEntry(raw, home);
+        if (!resolved) {
+            entries.push({ name: raw, source: raw, target: "", linked: false, reason: "entry must be a single host-home dotfile or dot directory" });
+            continue;
+        }
+        const target = join(agentHome, resolved.name);
+        if (!existsSync(resolved.source)) {
+            entries.push({ ...resolved, target, linked: false, reason: "source does not exist" });
+            continue;
+        }
+        const stat = lstatSync(resolved.source);
+        await rm(target, { recursive: true, force: true });
+        await symlink(resolved.source, target, stat.isDirectory() ? "dir" : "file");
+        entries.push({ ...resolved, target, linked: true });
+    }
+    return entries;
+}