@suwujs/king-ai 0.2.0

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

@@ -0,0 +1,387 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { HOST_LOOP_RESULTS_HEADER } from "./host-loop-events.js";
+import { writeHostRunHeartbeat } from "./host-run-heartbeat.js";
+import { defaultTeamSpec } from "./team-workflow.js";
+import { createHostLaunchPlan, formatHostLaunchPlanSummary, toJsonSafeHostLaunchPlan } from "./host-run-spec.js";
+import { commandText, planAgentWorktrees } from "./worktree.js";
+export async function prepareHostRunLayout(input, options = {}) {
+    const launchPlan = createHostLaunchPlan(input, options.env ?? process.env, options.availableEngines);
+    if (!launchPlan.ready) {
+        throw new Error("host run layout is not ready; run preflight and resolve errors first");
+    }
+    if (launchPlan.layout.exists && !input.force) {
+        throw new Error(`host run layout already exists: ${launchPlan.layout.baseDir}`);
+    }
+    if (launchPlan.layout.exists && input.force) {
+        await rm(launchPlan.layout.baseDir, { recursive: true, force: true });
+    }
+    const writtenFiles = [];
+    const copiedDirectories = [];
+    await mkdir(launchPlan.layout.baseDir, { recursive: true });
+    await mkdir(dirname(launchPlan.layout.configPath), { recursive: true });
+    await mkdir(launchPlan.layout.workspaceRoot, { recursive: true });
+    await mkdir(launchPlan.layout.sharedSkillsDir, { recursive: true });
+    await mkdir(launchPlan.layout.outputDir, { recursive: true });
+    await writeFile(launchPlan.layout.configPath, await buildLocalizedAgentConfig(launchPlan), "utf8");
+    writtenFiles.push(launchPlan.layout.configPath);
+    await writeFile(launchPlan.layout.collaborationPath, await buildCollaborationManifest(launchPlan), "utf8");
+    writtenFiles.push(launchPlan.layout.collaborationPath);
+    if (launchPlan.spec.projectDir) {
+        const projectAgents = join(launchPlan.spec.projectDir, "agents");
+        if (existsSync(projectAgents)) {
+            await copyDirectoryContents(projectAgents, launchPlan.layout.workspaceRoot);
+            copiedDirectories.push(projectAgents);
+        }
+        const projectSkills = join(launchPlan.spec.projectDir, "skills");
+        if (existsSync(projectSkills)) {
+            await copyDirectoryContents(projectSkills, launchPlan.layout.sharedSkillsDir);
+            copiedDirectories.push(projectSkills);
+        }
+    }
+    for (const file of await writeMissingAgentGuides(launchPlan))
+        writtenFiles.push(file);
+    for (const file of await writeRunObservationFiles(launchPlan, input.force === true))
+        writtenFiles.push(file);
+    return {
+        launchPlan: toJsonSafeHostLaunchPlan({
+            ...launchPlan,
+            layout: {
+                ...launchPlan.layout,
+                exists: true
+            },
+            launchSummary: formatHostLaunchPlanSummary({
+                ...launchPlan,
+                layout: {
+                    ...launchPlan.layout,
+                    exists: true
+                }
+            })
+        }),
+        writtenFiles,
+        copiedDirectories,
+        summary: formatHostRunLayoutResult(launchPlan, writtenFiles, copiedDirectories)
+    };
+}
+export function formatHostRunLayoutResult(plan, writtenFiles, copiedDirectories) {
+    return [
+        `prepared host run layout: ${plan.runId}`,
+        `base: ${plan.layout.baseDir}`,
+        `config: ${plan.layout.configPath}`,
+        `workspace: ${plan.layout.workspaceRoot}`,
+        `shared skills: ${plan.layout.sharedSkillsDir}`,
+        `collaboration: ${plan.layout.collaborationPath}`,
+        `git root: ${plan.layout.gitRoot}`,
+        `written files: ${writtenFiles.length ? writtenFiles.join(", ") : "(none)"}`,
+        copiedDirectories.length ? `copied directories: ${copiedDirectories.join(", ")}` : "copied directories: (none)"
+    ].join("\n");
+}
+async function buildLocalizedAgentConfig(plan) {
+    const raw = plan.config.path && plan.config.exists
+        ? await readFile(plan.config.path, "utf8")
+        : createDefaultHostRunConfigText(plan);
+    let config;
+    try {
+        config = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`host run config must be valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    config.workspaceRoot = plan.layout.workspaceRoot;
+    config.gitRoot = plan.layout.gitRoot;
+    config.outputDir = plan.layout.outputDir;
+    config.layoutSchema = "king-ai.host-run-layout.v1";
+    redactConfigSecrets(config);
+    return `${JSON.stringify(config, null, 2)}\n`;
+}
+async function writeRunObservationFiles(plan, force) {
+    const written = [];
+    if (force || !existsSync(plan.layout.loopEventsPath)) {
+        await writeFile(plan.layout.loopEventsPath, "", "utf8");
+        written.push(plan.layout.loopEventsPath);
+    }
+    if (force || !existsSync(plan.layout.resultsPath)) {
+        await writeFile(plan.layout.resultsPath, HOST_LOOP_RESULTS_HEADER, "utf8");
+        written.push(plan.layout.resultsPath);
+    }
+    if (force || !existsSync(plan.layout.heartbeatPath)) {
+        await writeHostRunHeartbeat({
+            path: plan.layout.heartbeatPath,
+            runId: plan.runId,
+            status: "prepared",
+            outputDir: plan.layout.outputDir
+        });
+        written.push(plan.layout.heartbeatPath);
+    }
+    if (force || !existsSync(plan.layout.metaPath)) {
+        await writeFile(plan.layout.metaPath, `${JSON.stringify(createPreparedRunMeta(plan), null, 2)}\n`, "utf8");
+        written.push(plan.layout.metaPath);
+    }
+    if (force || !existsSync(plan.layout.tasksPath)) {
+        await writeFile(plan.layout.tasksPath, "", "utf8");
+        written.push(plan.layout.tasksPath);
+    }
+    if (force || !existsSync(plan.layout.capsulesPath)) {
+        await writeFile(plan.layout.capsulesPath, "", "utf8");
+        written.push(plan.layout.capsulesPath);
+    }
+    if (force || !existsSync(plan.layout.workflowPath)) {
+        await writeFile(plan.layout.workflowPath, "", "utf8");
+        written.push(plan.layout.workflowPath);
+    }
+    if (force || !existsSync(plan.layout.feedbackPath)) {
+        await writeFile(plan.layout.feedbackPath, "", "utf8");
+        written.push(plan.layout.feedbackPath);
+    }
+    return written;
+}
+function createPreparedRunMeta(plan) {
+    return {
+        schema: "king-ai.host-run-meta.v1",
+        status: "prepared",
+        runId: plan.runId,
+        goal: plan.spec.goal,
+        preparedAt: new Date().toISOString(),
+        maxLoops: plan.options.loopMode === "infinite" ? "infinite" : plan.options.loops,
+        actualLoops: 0,
+        session: plan.session,
+        paths: {
+            baseDir: plan.layout.baseDir,
+            configPath: plan.layout.configPath,
+            workspaceRoot: plan.layout.workspaceRoot,
+            sharedSkillsDir: plan.layout.sharedSkillsDir,
+            gitRoot: plan.layout.gitRoot,
+            outputDir: plan.layout.outputDir,
+            loopEventsPath: plan.layout.loopEventsPath,
+            resultsPath: plan.layout.resultsPath,
+            heartbeatPath: plan.layout.heartbeatPath,
+            metaPath: plan.layout.metaPath,
+            collaborationPath: plan.layout.collaborationPath,
+            tasksPath: plan.layout.tasksPath,
+            capsulesPath: plan.layout.capsulesPath,
+            workflowPath: plan.layout.workflowPath,
+            feedbackPath: plan.layout.feedbackPath
+        },
+        config: {
+            source: plan.config.source,
+            label: plan.config.label
+        }
+    };
+}
+async function buildCollaborationManifest(plan) {
+    const config = JSON.parse(await buildLocalizedAgentConfig(plan));
+    const agents = (config.agents ?? []).map((agent) => ({
+        id: agent.id,
+        name: agent.name,
+        role: agent.role,
+        roleTemplate: agent.roleTemplate,
+        responsibility: agent.responsibility,
+        handoffPolicy: agent.handoffPolicy,
+        lifecycle: agent.lifecycle,
+        tier: agent.tier,
+        engine: agent.engine
+    }));
+    const team = defaultTeamSpec(`${plan.runId}-team`, "Host Run Team");
+    const worktreePlans = agents.map((agent) => ({
+        agentId: agent.id,
+        plans: agent.id
+            ? planAgentWorktrees({
+                agentId: agent.id,
+                workspaces: [plan.layout.gitRoot],
+                baseRoot: join(plan.layout.workspaceRoot, agent.id, "worktrees")
+            }).map((worktree) => ({
+                repoRoot: worktree.repoRoot,
+                repoName: worktree.repoName,
+                repoUrl: worktree.repoUrl,
+                branch: worktree.branch,
+                worktreePath: worktree.worktreePath,
+                command: commandText(worktree.command)
+            }))
+            : []
+    }));
+    return `${JSON.stringify({
+        schema: "king-ai.host-run-collaboration.v1",
+        runId: plan.runId,
+        goal: plan.spec.goal,
+        team,
+        agents,
+        governance: {
+            mode: "opt-in",
+            securityBoundary: false,
+            appliesWhen: "actorRole or KING_AI_TEAM_ROLE is supplied",
+            purpose: "route work, record decisions, audit role intent, and keep trusted local automation moving",
+            securityBoundaryNote: "Use OS account isolation, workspace boundaries, runtime tokens, command allowlists, destructive confirmations, and per-agent homes for security."
+        },
+        taskRules: {
+            dependencyField: "dependsOn",
+            blockedUntil: "all referenced tasks are done",
+            localTaskCommands: ["king-ai host task-create", "king-ai host task-list", "king-ai host task-update", "king-ai host agenda"],
+            handoffCommand: "king-ai send <agent> \"<message>\"",
+            humanDecisionCommand: "king-ai host decision-create",
+            routingModes: ["one-of-us", "each", "review-required", "human-decision"],
+            permissionRules: team.permissionPolicy.rules
+        },
+        capsuleRules: {
+            requiredFields: ["owner", "branchOrWorktree", "allowedPaths", "acceptance", "reviewer", "verificationCommands"],
+            defaultReviewer: "reviewer",
+            localCapsuleCommands: ["king-ai host capsule-create", "king-ai host capsule-list", "king-ai host capsule-update"],
+            repoChangePolicy: "keep repository edits inside the agreed capsule scope and record acceptance evidence before marking work done"
+        },
+        workflowObjects: ["initiative", "task", "handoff", "review", "decision", "artifact"],
+        worktreePlans,
+        paths: {
+            configPath: plan.layout.configPath,
+            workspaceRoot: plan.layout.workspaceRoot,
+            sharedSkillsDir: plan.layout.sharedSkillsDir,
+            gitRoot: plan.layout.gitRoot,
+            outputDir: plan.layout.outputDir,
+            loopEventsPath: plan.layout.loopEventsPath,
+            resultsPath: plan.layout.resultsPath,
+            heartbeatPath: plan.layout.heartbeatPath,
+            metaPath: plan.layout.metaPath,
+            tasksPath: plan.layout.tasksPath,
+            capsulesPath: plan.layout.capsulesPath,
+            workflowPath: plan.layout.workflowPath,
+            feedbackPath: plan.layout.feedbackPath
+        }
+    }, null, 2)}\n`;
+}
+export function createDefaultHostRunConfigText(plan) {
+    const engine = plan.effectiveEngine ?? plan.options.engine;
+    const agents = defaultHostRunAgents(plan).map((agent) => ({
+        ...agent,
+        ...(engine ? { engine } : {}),
+        ...(plan.options.model && agent.id === "ceo" ? { model: plan.options.model } : {}),
+        ...(plan.options.fastModel && agent.id !== "ceo" ? { model: plan.options.fastModel } : {})
+    }));
+    return JSON.stringify({
+        agents,
+        workspaceRoot: plan.layout.workspaceRoot,
+        gitRoot: plan.layout.gitRoot,
+        outputDir: plan.layout.outputDir,
+        layoutSchema: "king-ai.host-run-layout.v1"
+    }, null, 2);
+}
+function defaultHostRunAgents(plan) {
+    const role = (template, responsibility, reviewerRole) => ({
+        roleTemplate: template,
+        responsibility,
+        handoffPolicy: {
+            mode: reviewerRole ? "review-required" : "one-of-us",
+            reviewerRole,
+            escalation: "coordinator",
+            acceptanceRequired: Boolean(reviewerRole)
+        }
+    });
+    const definitions = {
+        ceo: defaultHostRunAgent(plan, "ceo", "Planner", "24/7", "high", "Turn the run goal into a small backlog, assign work, review progress, and produce a concise final deliverable.", role("planner", "Plan the run, route work to the right role, and close the loop with the human.")),
+        cto: defaultHostRunAgent(plan, "cto", "Reviewer", "on-demand", "high", "Review architecture-sensitive changes, enforce capsule acceptance criteria, and decide whether work is ready to merge.", role("reviewer", "Review scope, correctness, acceptance evidence, and merge readiness.")),
+        dev: defaultHostRunAgent(plan, "dev", "Builder", "on-demand", "standard", "Implement assigned code, docs, or analysis tasks end-to-end and report exact files or outputs changed.", role("builder", "Build assigned work inside the agreed scope and hand off for review.", "reviewer")),
+        devops: defaultHostRunAgent(plan, "devops", "Ops", "on-demand", "standard", "Keep build, test, CI, release, and local environment tasks moving with reproducible commands.", role("ops", "Handle environment, queue, release, audit, and operational safety tasks.", "reviewer")),
+        feedback: defaultHostRunAgent(plan, "feedback", "Researcher", "on-demand", "standard", "Review outputs, identify gaps, and convert useful observations into concrete follow-up tasks.", role("researcher", "Collect evidence, find gaps, and turn observations into structured follow-up tasks.")),
+        marketing: defaultHostRunAgent(plan, "marketing", "Doc Writer", "on-demand", "standard", "Keep user-facing docs, release notes, and product narrative aligned with shipped changes.", role("doc-writer", "Write verified user-facing documentation, release notes, and briefs.", "reviewer")),
+        tester: defaultHostRunAgent(plan, "tester", "Tester", "on-demand", "standard", "Design and run verification, regression, and release-readiness checks with reproducible commands.", role("tester", "Verify assigned work and record commands, evidence, and residual risk.", "reviewer"))
+    };
+    if (plan.spec.roleProfile === "small")
+        return [definitions.ceo, definitions.dev, definitions.cto];
+    if (plan.spec.roleProfile === "engineering")
+        return [definitions.ceo, definitions.cto, definitions.dev, definitions.tester, definitions.devops, definitions.feedback];
+    if (plan.spec.roleProfile === "product")
+        return [definitions.ceo, definitions.feedback, definitions.marketing, definitions.cto];
+    return [definitions.ceo, definitions.dev, definitions.cto, definitions.tester, definitions.devops, definitions.feedback, definitions.marketing];
+}
+function defaultHostRunAgent(plan, id, name, lifecycle, tier, role, workflow) {
+    return {
+        id,
+        name,
+        role,
+        ...workflow,
+        lifecycle,
+        tier,
+        systemPrompt: `${role}\n\n${defaultHostRunCliInstructions(plan)}`
+    };
+}
+function defaultHostRunCliInstructions(plan) {
+    return [
+        "Use `king-ai recv` for messages, `king-ai task list` for work state, and `king-ai send <agent> \"<message>\"` to coordinate.",
+        "Use `king-ai host decision-create` or `king-ai send human --type decision \"<question>\"` when a human choice is required.",
+        "For repository changes, prefer a capsule-shaped handoff: owner, branch/worktree, allowed paths, acceptance criteria, reviewer, and verification commands.",
+        `Keep outputs under ${plan.layout.outputDir} unless the task explicitly asks for repository changes.`
+    ].join("\n");
+}
+async function writeMissingAgentGuides(plan) {
+    let agents = [];
+    try {
+        const config = JSON.parse(await readFile(plan.layout.configPath, "utf8"));
+        if (Array.isArray(config.agents))
+            agents = config.agents;
+    }
+    catch {
+        return [];
+    }
+    const written = [];
+    for (const agent of agents) {
+        const id = typeof agent.id === "string" && agent.id.trim()
+            ? agent.id.trim()
+            : typeof agent.name === "string" && agent.name.trim()
+                ? agent.name.trim()
+                : undefined;
+        if (!id)
+            continue;
+        const agentDir = join(plan.layout.workspaceRoot, id);
+        const guidePath = join(agentDir, "AGENT.md");
+        if (existsSync(guidePath))
+            continue;
+        await mkdir(agentDir, { recursive: true });
+        await writeFile(guidePath, defaultAgentGuideText(agent, plan), "utf8");
+        written.push(guidePath);
+    }
+    return written;
+}
+function defaultAgentGuideText(agent, plan) {
+    const name = typeof agent.name === "string" && agent.name.trim()
+        ? agent.name.trim()
+        : typeof agent.id === "string" && agent.id.trim()
+            ? agent.id.trim()
+            : "Agent";
+    const role = typeof agent.systemPrompt === "string" && agent.systemPrompt.trim()
+        ? agent.systemPrompt.trim()
+        : typeof agent.role === "string" && agent.role.trim()
+            ? agent.role.trim()
+            : "Work through assigned local run tasks and report concrete results.";
+    return [
+        `# ${name}`,
+        "",
+        role,
+        "",
+        "## Operating Rules",
+        "",
+        "- Read current messages with `king-ai recv` before starting new work.",
+        "- Check assigned work with `king-ai task list` and update the team through `king-ai send`.",
+        "- For repository edits, work from a private branch or worktree and keep the changed paths inside the agreed capsule scope.",
+        "- Before marking work done, record the acceptance evidence: commands run, files changed, reviewer needed, and any export path.",
+        `- Put files you create under ${plan.layout.outputDir} unless the task explicitly asks for repository changes.`
+    ].join("\n") + "\n";
+}
+async function copyDirectoryContents(sourceDir, targetDir) {
+    await mkdir(targetDir, { recursive: true });
+    for (const entry of await readdir(sourceDir)) {
+        await cp(join(sourceDir, entry), join(targetDir, entry), {
+            recursive: true,
+            force: true,
+            dereference: false
+        });
+    }
+}
+function redactConfigSecrets(value) {
+    if (!value || typeof value !== "object")
+        return;
+    for (const key of Object.keys(value)) {
+        if (/^(apiKey|api_key|token|secret|password)$/i.test(key)) {
+            delete value[key];
+            continue;
+        }
+        redactConfigSecrets(value[key]);
+    }
+}

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

@@ -0,0 +1,41 @@
+export interface HostRunMetaData {
+    schema: "king-ai.host-run-meta.v1";
+    status: string;
+    runId: string;
+    goal?: string;
+    preparedAt?: string;
+    updatedAt?: string;
+    completedAt?: string;
+    maxLoops?: number | "infinite";
+    actualLoops?: number;
+    detail?: string;
+    command?: string;
+    exitCode?: number;
+    session?: Record<string, unknown>;
+    paths?: Record<string, unknown>;
+    config?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface HostRunMetaReadInput {
+    file?: string;
+    outputDir?: string;
+}
+export interface HostRunMetaReadResult {
+    file: string;
+    meta: HostRunMetaData | null;
+    exists: boolean;
+}
+export interface HostRunMetaUpdateInput extends HostRunMetaReadInput {
+    runId: string;
+    status: string;
+    actualLoops?: number;
+    detail?: string;
+    command?: string;
+    exitCode?: number;
+    now?: () => Date;
+}
+export declare function hostRunMetaPathForOutputDir(outputDir: string): string;
+export declare function resolveHostRunMetaPath(input?: HostRunMetaReadInput): string;
+export declare function readHostRunMeta(input?: HostRunMetaReadInput): Promise<HostRunMetaReadResult>;
+export declare function formatHostRunMeta(result: HostRunMetaReadResult): string;
+export declare function updateHostRunMeta(input: HostRunMetaUpdateInput): Promise<HostRunMetaReadResult>;

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

@@ -0,0 +1,115 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+export function hostRunMetaPathForOutputDir(outputDir) {
+    return join(resolve(outputDir), "meta.json");
+}
+export function resolveHostRunMetaPath(input = {}) {
+    if (input.file && input.file.trim())
+        return resolve(input.file);
+    const outputDir = input.outputDir && input.outputDir.trim() ? input.outputDir : "deliverables";
+    return hostRunMetaPathForOutputDir(outputDir);
+}
+export async function readHostRunMeta(input = {}) {
+    const file = resolveHostRunMetaPath(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,
+            meta: null,
+            exists: false
+        };
+    }
+    return {
+        file,
+        meta: parseHostRunMeta(text),
+        exists: true
+    };
+}
+export function formatHostRunMeta(result) {
+    if (!result.meta)
+        return `host run meta: ${result.file}\nnot found`;
+    return [
+        `host run meta: ${result.file}`,
+        `run: ${result.meta.runId}`,
+        `status: ${result.meta.status}`,
+        result.meta.goal ? `goal: ${result.meta.goal}` : "",
+        result.meta.preparedAt ? `prepared: ${result.meta.preparedAt}` : "",
+        result.meta.maxLoops !== undefined ? `loops: ${result.meta.actualLoops ?? 0}/${result.meta.maxLoops}` : ""
+    ].filter(Boolean).join("\n");
+}
+export async function updateHostRunMeta(input) {
+    const file = resolveHostRunMetaPath(input);
+    const existing = await readHostRunMeta({ file });
+    const now = (input.now ?? (() => new Date()))().toISOString();
+    const base = existing.meta ?? {
+        schema: "king-ai.host-run-meta.v1",
+        status: input.status,
+        runId: input.runId
+    };
+    const next = {
+        ...base,
+        schema: "king-ai.host-run-meta.v1",
+        runId: base.runId || input.runId,
+        status: cleanString(input.status) ?? base.status,
+        updatedAt: now,
+        actualLoops: input.actualLoops !== undefined ? Math.max(0, Math.floor(input.actualLoops)) : base.actualLoops,
+        detail: cleanString(input.detail) ?? base.detail,
+        command: cleanString(input.command) ?? base.command,
+        exitCode: normalizeExitCode(input.exitCode) ?? base.exitCode,
+        completedAt: isTerminalStatus(input.status) ? now : base.completedAt
+    };
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify(dropUndefined({ ...next }), null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    return {
+        file,
+        meta: next,
+        exists: true
+    };
+}
+function parseHostRunMeta(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || parsed.schema !== "king-ai.host-run-meta.v1" || typeof parsed.runId !== "string")
+            return null;
+        return {
+            ...parsed,
+            schema: "king-ai.host-run-meta.v1",
+            status: typeof parsed.status === "string" ? parsed.status : "",
+            runId: parsed.runId,
+            goal: typeof parsed.goal === "string" ? parsed.goal : undefined,
+            preparedAt: typeof parsed.preparedAt === "string" ? parsed.preparedAt : undefined,
+            updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : undefined,
+            completedAt: typeof parsed.completedAt === "string" ? parsed.completedAt : undefined,
+            maxLoops: parsed.maxLoops === "infinite" || typeof parsed.maxLoops === "number" ? parsed.maxLoops : undefined,
+            actualLoops: typeof parsed.actualLoops === "number" ? parsed.actualLoops : 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,
+            session: parsed.session && typeof parsed.session === "object" ? parsed.session : undefined,
+            paths: parsed.paths && typeof parsed.paths === "object" ? parsed.paths : undefined,
+            config: parsed.config && typeof parsed.config === "object" ? parsed.config : undefined
+        };
+    }
+    catch {
+        return null;
+    }
+}
+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 isTerminalStatus(value) {
+    return value === "completed" || value === "failed" || value === "cancelled";
+}
+function dropUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}