@suwujs/king-ai 0.2.0

package/dist/src/usage.js

@@ -0,0 +1,350 @@
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+function envNum(value) {
+    const parsed = typeof value === "string" ? Number(value) : value;
+    return num(parsed);
+}
+export function normalizeEngineUsage(usage) {
+    if (!usage || typeof usage !== "object") {
+        return { inputTokens: 0, cacheReadInputTokens: 0, outputTokens: 0, totalTokens: 0 };
+    }
+    const rec = usage;
+    const inputTokens = num(rec.input_tokens ?? rec.inputTokens);
+    const cacheReadInputTokens = num(rec.cache_read_input_tokens ?? rec.cacheReadInputTokens ?? rec.cachedInputTokens);
+    const outputTokens = num(rec.output_tokens ?? rec.outputTokens);
+    const totalTokens = num(rec.total_tokens ?? rec.totalTokens) || inputTokens + cacheReadInputTokens + outputTokens;
+    return { inputTokens, cacheReadInputTokens, outputTokens, totalTokens };
+}
+export function emptyAgentRunStats() {
+    return {
+        turns: 0,
+        completed: 0,
+        failed: 0,
+        inputTokens: 0,
+        cacheReadInputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0
+    };
+}
+export function recordAgentRunStats(current, args) {
+    const usage = normalizeEngineUsage(args.usage);
+    return {
+        turns: current.turns + 1,
+        completed: current.completed + (args.status === "completed" ? 1 : 0),
+        failed: current.failed + (args.status === "failed" ? 1 : 0),
+        inputTokens: current.inputTokens + usage.inputTokens,
+        cacheReadInputTokens: current.cacheReadInputTokens + usage.cacheReadInputTokens,
+        outputTokens: current.outputTokens + usage.outputTokens,
+        totalTokens: current.totalTokens + usage.totalTokens,
+        lastRunAt: args.at ?? new Date().toISOString(),
+        lastDurationMs: Math.max(0, Math.floor(args.durationMs)),
+        lastStatus: args.status,
+        lastModel: args.model ?? null
+    };
+}
+export function formatAgentRunStats(stats) {
+    if (!stats || stats.turns === 0)
+        return "";
+    const tokens = stats.totalTokens
+        ? `${stats.totalTokens} tokens (in=${stats.inputTokens}, cache=${stats.cacheReadInputTokens}, out=${stats.outputTokens})`
+        : "tokens unavailable";
+    const last = stats.lastRunAt
+        ? ` last=${stats.lastStatus ?? "unknown"} ${stats.lastDurationMs ?? 0}ms @ ${stats.lastRunAt}${stats.lastModel ? ` model=${stats.lastModel}` : ""}`
+        : "";
+    return `runs=${stats.turns} completed=${stats.completed} failed=${stats.failed} ${tokens}${last}`;
+}
+export function tokenBudgetFromEnv(env = process.env) {
+    const budget = envNum(env.KING_AI_TOKEN_BUDGET);
+    return budget > 0 ? budget : null;
+}
+export function usagePricingFromEnv(env = process.env) {
+    const raw = env.KING_AI_USAGE_PRICING;
+    if (!raw)
+        return [];
+    try {
+        return normalizeUsagePricing(JSON.parse(raw));
+    }
+    catch {
+        return [];
+    }
+}
+export function normalizeUsagePricing(value) {
+    if (Array.isArray(value))
+        return value.flatMap((entry) => normalizeUsagePricingRule(entry));
+    if (!value || typeof value !== "object")
+        return [];
+    return Object.entries(value).flatMap(([key, entry]) => normalizeUsagePricingRule({
+        ...(entry && typeof entry === "object" ? entry : {}),
+        key
+    }));
+}
+export function estimateUsageCost(totals, pricing) {
+    if (!pricing)
+        return undefined;
+    const inputRate = pricing.inputPerMillionTokens ?? 0;
+    const cacheRate = pricing.cacheReadInputPerMillionTokens ?? inputRate;
+    const outputRate = pricing.outputPerMillionTokens ?? 0;
+    const inputCost = costForTokens(totals.inputTokens, inputRate);
+    const cacheReadInputCost = costForTokens(totals.cacheReadInputTokens, cacheRate);
+    const outputCost = costForTokens(totals.outputTokens, outputRate);
+    const pricedTokens = (inputRate > 0 ? totals.inputTokens : 0) +
+        (cacheRate > 0 ? totals.cacheReadInputTokens : 0) +
+        (outputRate > 0 ? totals.outputTokens : 0);
+    return {
+        amount: roundCost(inputCost + cacheReadInputCost + outputCost),
+        currency: pricing.currency,
+        inputCost,
+        cacheReadInputCost,
+        outputCost,
+        pricedTokens,
+        unpricedTokens: Math.max(0, totals.totalTokens - pricedTokens),
+        pricingKeys: [pricing.key]
+    };
+}
+export function checkTokenBudget(stats, budget) {
+    if (!stats || !budget)
+        return undefined;
+    const used = stats.totalTokens;
+    const remaining = budget - used;
+    const exceeded = remaining < 0;
+    const warning = !exceeded && remaining < budget * 0.2;
+    return {
+        budget,
+        used,
+        remaining,
+        warning,
+        exceeded,
+        state: exceeded ? "exceeded" : warning ? "warning" : "ok"
+    };
+}
+export function formatTokenBudgetCheck(check) {
+    if (!check)
+        return "";
+    return `budget=${check.budget} used=${check.used} remaining=${check.remaining} state=${check.state}`;
+}
+export function summarizeAgentUsage(agents = [], budget = null, pricingRules = []) {
+    const summary = {
+        agents: [],
+        byEngine: [],
+        byModel: [],
+        turns: 0,
+        completed: 0,
+        failed: 0,
+        inputTokens: 0,
+        cacheReadInputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0
+    };
+    const byEngine = new Map();
+    const byModel = new Map();
+    const pricing = pricingRules.map((rule) => ({ ...rule, key: rule.key.toLowerCase() }));
+    for (const agent of agents) {
+        const stats = agent.runStats ?? emptyAgentRunStats();
+        const model = agent.model ?? stats.lastModel ?? null;
+        const cost = estimateUsageCost(stats, selectUsagePricingRule(pricing, agent.engine, model));
+        const agentSummary = {
+            key: agent.id,
+            id: agent.id,
+            name: agent.name,
+            engine: agent.engine,
+            model,
+            turns: stats.turns,
+            completed: stats.completed,
+            failed: stats.failed,
+            agents: 1,
+            inputTokens: stats.inputTokens,
+            cacheReadInputTokens: stats.cacheReadInputTokens,
+            outputTokens: stats.outputTokens,
+            totalTokens: stats.totalTokens,
+            lastRunAt: stats.lastRunAt,
+            lastStatus: stats.lastStatus,
+            tokenBudget: agent.tokenBudget,
+            cost
+        };
+        summary.agents.push(agentSummary);
+        addUsageTotals(summary, stats);
+        addUsageCost(summary, cost);
+        summary.turns += stats.turns;
+        summary.completed += stats.completed;
+        summary.failed += stats.failed;
+        addGroup(byEngine, agent.engine || "unknown", stats, cost);
+        addGroup(byModel, agentSummary.model || "default", stats, cost);
+    }
+    summary.agents.sort((left, right) => right.totalTokens - left.totalTokens || left.id.localeCompare(right.id));
+    summary.byEngine = [...byEngine.values()].sort((left, right) => right.totalTokens - left.totalTokens || left.key.localeCompare(right.key));
+    summary.byModel = [...byModel.values()].sort((left, right) => right.totalTokens - left.totalTokens || left.key.localeCompare(right.key));
+    summary.budget = checkTokenBudget(summary, budget);
+    return summary;
+}
+export function formatUsageSummary(summary) {
+    const lines = [
+        "usage summary:",
+        `  runs=${summary.turns} completed=${summary.completed} failed=${summary.failed}`,
+        `  tokens=${summary.totalTokens} input=${summary.inputTokens} cache=${summary.cacheReadInputTokens} output=${summary.outputTokens}`
+    ];
+    const budget = formatTokenBudgetCheck(summary.budget);
+    if (budget)
+        lines.push(`  token budget: ${budget}`);
+    if (summary.cost)
+        lines.push(`  estimated cost: ${formatUsageCost(summary.cost)}`);
+    if (summary.byEngine.length) {
+        lines.push("by engine:");
+        for (const group of summary.byEngine)
+            lines.push(`  - ${formatUsageGroup(group)}`);
+    }
+    if (summary.byModel.length) {
+        lines.push("by model:");
+        for (const group of summary.byModel)
+            lines.push(`  - ${formatUsageGroup(group)}`);
+    }
+    if (summary.agents.length) {
+        lines.push("by agent:");
+        for (const agent of summary.agents) {
+            const label = agent.name ? `${agent.id} (${agent.name})` : agent.id;
+            const budgetText = formatTokenBudgetCheck(agent.tokenBudget);
+            const costText = agent.cost ? ` cost=${formatUsageCost(agent.cost)}` : "";
+            lines.push(`  - ${label}: engine=${agent.engine} model=${agent.model || "default"} ${formatUsageGroup(agent)}${agent.lastRunAt ? ` last=${agent.lastStatus ?? "unknown"}@${agent.lastRunAt}` : ""}${budgetText ? ` ${budgetText}` : ""}${costText}`);
+        }
+    }
+    else {
+        lines.push("by agent: none");
+    }
+    return lines.join("\n");
+}
+export function listUsageExpenses(summary) {
+    return summary.agents
+        .filter((agent) => agent.cost || agent.totalTokens > 0 || agent.turns > 0)
+        .map((agent) => {
+        const cost = agent.cost;
+        return {
+            agentId: agent.id,
+            agentName: agent.name,
+            engine: agent.engine,
+            model: agent.model || "default",
+            turns: agent.turns,
+            completed: agent.completed,
+            failed: agent.failed,
+            inputTokens: agent.inputTokens,
+            cacheReadInputTokens: agent.cacheReadInputTokens,
+            outputTokens: agent.outputTokens,
+            totalTokens: agent.totalTokens,
+            currency: cost?.currency ?? "",
+            amount: cost?.amount ?? 0,
+            inputCost: cost?.inputCost ?? 0,
+            cacheReadInputCost: cost?.cacheReadInputCost ?? 0,
+            outputCost: cost?.outputCost ?? 0,
+            pricedTokens: cost?.pricedTokens ?? 0,
+            unpricedTokens: cost?.unpricedTokens ?? agent.totalTokens,
+            pricingKeys: cost?.pricingKeys ?? [],
+            lastRunAt: agent.lastRunAt,
+            lastStatus: agent.lastStatus
+        };
+    })
+        .sort((left, right) => right.amount - left.amount || right.totalTokens - left.totalTokens || left.agentId.localeCompare(right.agentId));
+}
+export function formatUsageExpenses(rows) {
+    if (rows.length === 0)
+        return "usage expenses: none";
+    const lines = ["usage expenses:"];
+    for (const row of rows) {
+        const label = row.agentName ? `${row.agentId} (${row.agentName})` : row.agentId;
+        const cost = row.currency ? `${row.currency} ${row.amount.toFixed(6)}` : "unpriced";
+        const unpriced = row.unpricedTokens ? ` unpricedTokens=${row.unpricedTokens}` : "";
+        const keys = row.pricingKeys.length ? ` pricing=${row.pricingKeys.join(",")}` : "";
+        const last = row.lastRunAt ? ` last=${row.lastStatus ?? "unknown"}@${row.lastRunAt}` : "";
+        lines.push(`  - ${label}: ${cost} engine=${row.engine} model=${row.model} runs=${row.turns} completed=${row.completed} failed=${row.failed} tokens=${row.totalTokens} input=${row.inputTokens} cache=${row.cacheReadInputTokens} output=${row.outputTokens} inputCost=${row.inputCost.toFixed(6)} cacheCost=${row.cacheReadInputCost.toFixed(6)} outputCost=${row.outputCost.toFixed(6)}${unpriced}${keys}${last}`);
+    }
+    return lines.join("\n");
+}
+function addGroup(groups, key, stats, cost) {
+    const group = groups.get(key) ?? {
+        key,
+        agents: 0,
+        turns: 0,
+        completed: 0,
+        failed: 0,
+        inputTokens: 0,
+        cacheReadInputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0
+    };
+    group.agents += 1;
+    group.turns += stats.turns;
+    group.completed += stats.completed;
+    group.failed += stats.failed;
+    addUsageTotals(group, stats);
+    addUsageCost(group, cost);
+    groups.set(key, group);
+}
+function addUsageTotals(target, source) {
+    target.inputTokens += source.inputTokens;
+    target.cacheReadInputTokens += source.cacheReadInputTokens;
+    target.outputTokens += source.outputTokens;
+    target.totalTokens += source.totalTokens;
+}
+function addUsageCost(target, source) {
+    if (!source)
+        return;
+    if (!target.cost) {
+        target.cost = { ...source, pricingKeys: [...source.pricingKeys] };
+        return;
+    }
+    if (target.cost.currency !== source.currency) {
+        target.cost.unpricedTokens += source.pricedTokens + source.unpricedTokens;
+        return;
+    }
+    target.cost.amount = roundCost(target.cost.amount + source.amount);
+    target.cost.inputCost = roundCost(target.cost.inputCost + source.inputCost);
+    target.cost.cacheReadInputCost = roundCost(target.cost.cacheReadInputCost + source.cacheReadInputCost);
+    target.cost.outputCost = roundCost(target.cost.outputCost + source.outputCost);
+    target.cost.pricedTokens += source.pricedTokens;
+    target.cost.unpricedTokens += source.unpricedTokens;
+    target.cost.pricingKeys = [...new Set([...target.cost.pricingKeys, ...source.pricingKeys])];
+}
+function normalizeUsagePricingRule(value) {
+    if (!value || typeof value !== "object")
+        return [];
+    const entry = value;
+    const key = typeof entry.key === "string" ? entry.key.trim().toLowerCase() : "";
+    if (!key)
+        return [];
+    const rule = {
+        key,
+        currency: typeof entry.currency === "string" && entry.currency.trim() ? entry.currency.trim().toUpperCase() : "USD",
+        inputPerMillionTokens: optionalRate(entry.inputPerMillionTokens ?? entry.inputPerMillion ?? entry.input_tokens_per_million),
+        cacheReadInputPerMillionTokens: optionalRate(entry.cacheReadInputPerMillionTokens ?? entry.cacheReadInputPerMillion ?? entry.cachedInputPerMillion ?? entry.cache_read_input_tokens_per_million),
+        outputPerMillionTokens: optionalRate(entry.outputPerMillionTokens ?? entry.outputPerMillion ?? entry.output_tokens_per_million),
+        source: typeof entry.source === "string" ? entry.source : undefined
+    };
+    return rule.inputPerMillionTokens || rule.cacheReadInputPerMillionTokens || rule.outputPerMillionTokens ? [rule] : [];
+}
+function selectUsagePricingRule(pricing, engine, model) {
+    const engineKey = engine.trim().toLowerCase();
+    const modelKey = model?.trim().toLowerCase();
+    const candidates = [
+        modelKey ? `${engineKey}:${modelKey}` : "",
+        modelKey ?? "",
+        `${engineKey}:*`,
+        engineKey,
+        "*"
+    ].filter(Boolean);
+    return candidates.map((key) => pricing.find((rule) => rule.key === key)).find((rule) => Boolean(rule));
+}
+function optionalRate(value) {
+    const parsed = typeof value === "string" ? Number(value) : value;
+    return typeof parsed === "number" && Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+}
+function costForTokens(tokens, perMillionTokens) {
+    return roundCost(tokens / 1_000_000 * perMillionTokens);
+}
+function roundCost(value) {
+    return Math.round(value * 1_000_000) / 1_000_000;
+}
+function formatUsageCost(cost) {
+    const unpriced = cost.unpricedTokens ? ` unpricedTokens=${cost.unpricedTokens}` : "";
+    return `${cost.currency} ${cost.amount.toFixed(6)}${unpriced}`;
+}
+function formatUsageGroup(group) {
+    return `${group.key}: runs=${group.turns} completed=${group.completed} failed=${group.failed} tokens=${group.totalTokens} input=${group.inputTokens} cache=${group.cacheReadInputTokens} output=${group.outputTokens}`;
+}

package/dist/src/workspace.d.ts

@@ -0,0 +1,9 @@
+export interface LocalCapabilities {
+    workspaces: string[];
+    agentWorkspaceRoot?: string;
+}
+export declare function resolveWorkspaceAllowlist(env?: NodeJS.ProcessEnv): string[];
+export declare function detectLocalCapabilities(env?: NodeJS.ProcessEnv): LocalCapabilities;
+export declare function resolveAgentWorkspaceBase(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function agentWorkspaceRoot(agentId: string, agentHome: string, env?: NodeJS.ProcessEnv): string;
+export declare function formatWorkspacePolicy(workspaces: string[], agentRoot?: string): string;

package/dist/src/workspace.js

@@ -0,0 +1,56 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join, resolve } from "node:path";
+function splitList(value) {
+    if (!value)
+        return [];
+    return value
+        .split(delimiter)
+        .flatMap((part) => part.split(","))
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
+export function resolveWorkspaceAllowlist(env = process.env) {
+    const explicit = splitList(env.KING_AI_WORKSPACES);
+    const candidates = explicit.length > 0 ? explicit : [resolve(homedir(), "workspace")];
+    const seen = new Set();
+    const result = [];
+    for (const candidate of candidates) {
+        const resolved = resolve(candidate.replace(/^~(?=$|\/|\\)/, homedir()));
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        if (explicit.length > 0 || existsSync(resolved))
+            result.push(resolved);
+    }
+    return result;
+}
+export function detectLocalCapabilities(env = process.env) {
+    return {
+        workspaces: resolveWorkspaceAllowlist(env),
+        agentWorkspaceRoot: resolveAgentWorkspaceBase(env)
+    };
+}
+export function resolveAgentWorkspaceBase(env = process.env) {
+    const raw = env.KING_AI_AGENT_WORKSPACE_ROOT;
+    return raw ? resolve(raw.replace(/^~(?=$|\/|\\)/, homedir())) : undefined;
+}
+export function agentWorkspaceRoot(agentId, agentHome, env = process.env) {
+    const base = resolveAgentWorkspaceBase(env);
+    return base ? join(base, agentId) : join(agentHome, "workspace");
+}
+export function formatWorkspacePolicy(workspaces, agentRoot) {
+    const rootLine = agentRoot ? `Agent workspace root: ${agentRoot}. Use this as your default project workspace for clones, builds, downloads, and scratch files.` : "";
+    if (workspaces.length === 0) {
+        return [
+            rootLine,
+            "Workspace access: no external workspace directories are explicitly allowed. Stay in your agent workspace root unless the operator configures KING_AI_WORKSPACES."
+        ].filter(Boolean).join("\n");
+    }
+    return [
+        rootLine,
+        "Workspace access: the operator has allowed these external workspace directories for this agent:",
+        ...workspaces.map((path) => `- ${path}`),
+        "You may read or work in those directories only when the runtime task asks for it. For unrelated scratch work, use your agent workspace root."
+    ].filter(Boolean).join("\n");
+}

package/dist/src/worktree.d.ts

@@ -0,0 +1,47 @@
+export interface WorktreePlan {
+    repoRoot: string;
+    repoName: string;
+    repoUrl?: string;
+    branch: string;
+    worktreePath: string;
+    command: string[];
+}
+export type WorktreePreparationStatus = "planned" | "created" | "exists" | "failed";
+export type WorktreeCleanupStatus = "missing" | "present" | "removed" | "failed";
+export interface WorktreePreparationResult {
+    plan: WorktreePlan;
+    status: WorktreePreparationStatus;
+    commandText: string;
+    detail?: string;
+}
+export interface WorktreeCleanupResult {
+    plan: WorktreePlan;
+    status: WorktreeCleanupStatus;
+    commandText: string;
+    detail?: string;
+}
+export type WorktreeExecutor = (file: string, args: string[]) => Promise<unknown>;
+export declare function safeBranchSegment(value: string): string;
+export declare function isGitRepo(path: string): boolean;
+export declare function isGitHubRepoUrl(repoUrl: string): boolean;
+export declare function gitOriginUrl(repoRoot: string): string | undefined;
+export declare function githubRepoUrl(repoRoot: string): string | undefined;
+export declare function planAgentWorktrees(args: {
+    agentId: string;
+    workspaces: string[];
+    baseRoot?: string;
+}): WorktreePlan[];
+export declare function formatWorktreePlanForPrompt(plans: WorktreePlan[]): string;
+export declare function shellQuote(value: string): string;
+export declare function commandText(command: string[]): string;
+export declare function prepareWorktreePlans(plans: WorktreePlan[], options?: {
+    execute?: boolean;
+    executor?: WorktreeExecutor;
+}): Promise<WorktreePreparationResult[]>;
+export declare function formatWorktreePreparationResults(results: WorktreePreparationResult[], execute?: boolean): string;
+export declare function cleanupCommand(plan: WorktreePlan): string[];
+export declare function cleanupWorktreePlans(plans: WorktreePlan[], options?: {
+    execute?: boolean;
+    executor?: WorktreeExecutor;
+}): Promise<WorktreeCleanupResult[]>;
+export declare function formatWorktreeCleanupResults(results: WorktreeCleanupResult[], execute?: boolean): string;

package/dist/src/worktree.js

@@ -0,0 +1,201 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { execFile } from "node:child_process";
+const execFileP = promisify(execFile);
+export function safeBranchSegment(value) {
+    return value
+        .trim()
+        .replace(/[^A-Za-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80) || "agent";
+}
+export function isGitRepo(path) {
+    return existsSync(join(path, ".git"));
+}
+const SSH_GITHUB_REPO_RE = /^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i;
+function hasValidRepoPathname(pathname) {
+    const segments = pathname.split("/").filter(Boolean);
+    if (segments.length !== 2)
+        return false;
+    return segments.every((segment, index) => {
+        const normalized = index === 1 ? segment.replace(/\.git$/i, "") : segment;
+        return normalized.length > 0 && !normalized.startsWith(".");
+    });
+}
+export function isGitHubRepoUrl(repoUrl) {
+    const trimmed = repoUrl.trim();
+    if (!trimmed)
+        return false;
+    if (SSH_GITHUB_REPO_RE.test(trimmed))
+        return true;
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return false;
+    }
+    if (!["https:", "http:", "ssh:"].includes(parsed.protocol))
+        return false;
+    if (parsed.hostname.toLowerCase() !== "github.com")
+        return false;
+    if (parsed.username && parsed.username !== "git")
+        return false;
+    if (parsed.password || parsed.search || parsed.hash)
+        return false;
+    return hasValidRepoPathname(parsed.pathname);
+}
+export function gitOriginUrl(repoRoot) {
+    const configPath = join(repoRoot, ".git", "config");
+    if (!existsSync(configPath))
+        return undefined;
+    const config = readFileSync(configPath, "utf8");
+    const lines = config.split(/\r?\n/);
+    let inOrigin = false;
+    for (const line of lines) {
+        const section = line.match(/^\s*\[remote\s+"([^"]+)"\]\s*$/);
+        if (section) {
+            inOrigin = section[1] === "origin";
+            continue;
+        }
+        if (!inOrigin)
+            continue;
+        const url = line.match(/^\s*url\s*=\s*(.+?)\s*$/);
+        if (url?.[1])
+            return url[1];
+    }
+    return undefined;
+}
+export function githubRepoUrl(repoRoot) {
+    const origin = gitOriginUrl(repoRoot);
+    return origin && isGitHubRepoUrl(origin) ? origin : undefined;
+}
+export function planAgentWorktrees(args) {
+    const agentSegment = safeBranchSegment(args.agentId);
+    return args.workspaces
+        .filter((workspace) => isGitRepo(workspace))
+        .map((repoRoot) => {
+        const repoName = basename(repoRoot) || "repo";
+        const branch = `agent/${agentSegment}`;
+        const worktreePath = args.baseRoot ? join(args.baseRoot, repoName) : join(repoRoot, ".worktrees", agentSegment);
+        return {
+            repoRoot,
+            repoName,
+            repoUrl: githubRepoUrl(repoRoot),
+            branch,
+            worktreePath,
+            command: ["git", "-C", repoRoot, "worktree", "add", "-B", branch, worktreePath]
+        };
+    });
+}
+export function formatWorktreePlanForPrompt(plans) {
+    if (plans.length === 0)
+        return "";
+    return [
+        "Planned git worktree isolation (not auto-created by the daemon):",
+        ...plans.map((plan) => `- ${plan.repoName}: ${plan.worktreePath} on ${plan.branch}${plan.repoUrl ? ` from ${plan.repoUrl}` : ""}`)
+    ].join("\n");
+}
+export function shellQuote(value) {
+    return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
+}
+export function commandText(command) {
+    return command.map(shellQuote).join(" ");
+}
+export async function prepareWorktreePlans(plans, options = {}) {
+    const executor = options.executor ?? ((file, args) => execFileP(file, args));
+    const results = [];
+    for (const plan of plans) {
+        const command = commandText(plan.command);
+        if (existsSync(plan.worktreePath)) {
+            results.push({ plan, status: "exists", commandText: command, detail: "worktree path already exists" });
+            continue;
+        }
+        if (!options.execute) {
+            results.push({ plan, status: "planned", commandText: command });
+            continue;
+        }
+        try {
+            await mkdir(dirname(plan.worktreePath), { recursive: true });
+            const [file, ...args] = plan.command;
+            if (!file)
+                throw new Error("empty worktree command");
+            await executor(file, args);
+            results.push({ plan, status: "created", commandText: command });
+        }
+        catch (err) {
+            results.push({ plan, status: "failed", commandText: command, detail: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return results;
+}
+export function formatWorktreePreparationResults(results, execute = false) {
+    if (results.length === 0)
+        return "no worktree plans found";
+    const lines = [`worktree preparation${execute ? "" : " (dry run)"}`];
+    for (const result of results) {
+        lines.push(`- ${result.plan.repoName}: ${result.status}`);
+        lines.push(`  repo: ${result.plan.repoRoot}`);
+        if (result.plan.repoUrl)
+            lines.push(`  origin: ${result.plan.repoUrl}`);
+        lines.push(`  path: ${result.plan.worktreePath}`);
+        lines.push(`  branch: ${result.plan.branch}`);
+        lines.push(`  command: ${result.commandText}`);
+        if (result.detail)
+            lines.push(`  detail: ${result.detail}`);
+    }
+    if (!execute)
+        lines.push("rerun with --yes to create these worktrees");
+    return lines.join("\n");
+}
+export function cleanupCommand(plan) {
+    return ["git", "-C", plan.repoRoot, "worktree", "remove", "--force", plan.worktreePath];
+}
+export async function cleanupWorktreePlans(plans, options = {}) {
+    const executor = options.executor ?? ((file, args) => execFileP(file, args));
+    const results = [];
+    for (const plan of plans) {
+        const removeCommand = cleanupCommand(plan);
+        const command = commandText(removeCommand);
+        if (!existsSync(plan.worktreePath)) {
+            results.push({ plan, status: "missing", commandText: command, detail: "worktree path does not exist" });
+            continue;
+        }
+        if (!options.execute) {
+            results.push({ plan, status: "present", commandText: command });
+            continue;
+        }
+        try {
+            const [file, ...args] = removeCommand;
+            if (!file)
+                throw new Error("empty cleanup command");
+            await executor(file, args);
+            results.push({ plan, status: "removed", commandText: command });
+        }
+        catch (err) {
+            results.push({ plan, status: "failed", commandText: command, detail: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return results;
+}
+export function formatWorktreeCleanupResults(results, execute = false) {
+    if (results.length === 0)
+        return "no worktree plans found";
+    const lines = [`worktree cleanup${execute ? "" : " (dry run)"}`];
+    for (const result of results) {
+        lines.push(`- ${result.plan.repoName}: ${result.status}`);
+        lines.push(`  repo: ${result.plan.repoRoot}`);
+        if (result.plan.repoUrl)
+            lines.push(`  origin: ${result.plan.repoUrl}`);
+        lines.push(`  path: ${result.plan.worktreePath}`);
+        lines.push(`  branch: ${result.plan.branch}`);
+        lines.push(`  command: ${result.commandText}`);
+        if (result.detail)
+            lines.push(`  detail: ${result.detail}`);
+    }
+    if (!execute)
+        lines.push("rerun with --yes to remove present worktrees");
+    return lines.join("\n");
+}