akemon 0.3.6 → 0.3.7

package/dist/task-registry.js

@@ -0,0 +1,756 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { redactSecrets } from "./redaction.js";
+const DEFAULT_TASK_SOURCE = "unknown";
+export function taskRegistryDir(workdir, agentName) {
+    return join(workdir, ".akemon", "agents", agentName, "tasks");
+}
+export function taskRegistryRecordPath(workdir, agentName, taskId) {
+    return join(taskRegistryDir(workdir, agentName), `${safeTaskFilename(taskId)}.json`);
+}
+export async function upsertTaskRegistryRecord(input) {
+    const now = input.now || new Date().toISOString();
+    const existing = await readTaskRegistryRecord({
+        workdir: input.workdir,
+        agentName: input.agentName,
+        taskId: input.patch.taskId,
+    });
+    const status = input.patch.status || existing?.status || "pending";
+    const stage = normalizeTaskRegistryStage(input.patch.stage)
+        || (input.patch.status ? inferTaskStageFromStatus(status) : existing?.stage)
+        || inferTaskStageFromStatus(status);
+    const completedAt = input.patch.completedAt !== undefined
+        ? input.patch.completedAt
+        : input.patch.status && input.patch.status !== "succeeded" && input.patch.status !== "failed"
+            ? undefined
+            : existing?.completedAt;
+    const mergedData = mergeTaskData(existing?.data, input.patch.data);
+    const draft = {
+        taskId: input.patch.taskId,
+        source: existing?.source && existing.source !== DEFAULT_TASK_SOURCE
+            ? existing.source
+            : input.patch.source || DEFAULT_TASK_SOURCE,
+        status,
+        stage,
+        objective: existing?.objective || input.patch.objective || input.patch.summary || input.patch.taskId,
+        route: input.patch.route ?? existing?.route,
+        summary: input.patch.summary ?? existing?.summary,
+        conversationId: input.patch.conversationId ?? existing?.conversationId,
+        refs: input.patch.refs ?? existing?.refs,
+        data: mergedData,
+        createdAt: existing?.createdAt || now,
+        updatedAt: now,
+        completedAt,
+    };
+    const presentation = deriveTaskPresentation({
+        ...draft,
+        kind: input.patch.kind || existing?.kind,
+        visibility: input.patch.visibility || existing?.visibility,
+        title: input.patch.title,
+        ownerStatus: input.patch.ownerStatus,
+        nextAction: input.patch.nextAction,
+        parentTaskId: input.patch.parentTaskId ?? existing?.parentTaskId,
+    });
+    const next = {
+        schemaVersion: 1,
+        ...draft,
+        kind: input.patch.kind || existing?.kind || presentation.kind,
+        visibility: input.patch.visibility || existing?.visibility || presentation.visibility,
+        title: input.patch.title || existing?.title || presentation.title,
+        ownerStatus: input.patch.ownerStatus || presentation.ownerStatus,
+        nextAction: input.patch.nextAction !== undefined ? input.patch.nextAction : presentation.nextAction,
+        parentTaskId: input.patch.parentTaskId ?? existing?.parentTaskId ?? presentation.parentTaskId,
+    };
+    if (!next.completedAt && (next.status === "succeeded" || next.status === "failed")) {
+        next.completedAt = now;
+    }
+    await mkdir(taskRegistryDir(input.workdir, input.agentName), { recursive: true });
+    await writeFile(taskRegistryRecordPath(input.workdir, input.agentName, next.taskId), `${JSON.stringify(redactSecrets(next), null, 2)}\n`, "utf-8");
+    return next;
+}
+export async function upsertTaskRegistryRecordFromEvent(input) {
+    return upsertTaskRegistryRecord({
+        workdir: input.workdir,
+        agentName: input.agentName,
+        now: input.event.createdAt,
+        patch: {
+            taskId: input.event.taskId,
+            status: input.event.status,
+            stage: input.event.stage || inferTaskStageFromEvent(input.event),
+            objective: taskObjectiveFromEvent(input.event),
+            route: input.event.route,
+            summary: input.event.summary,
+            conversationId: input.event.conversationId,
+            refs: input.event.refs,
+            source: taskSourceFromEvent(input.event),
+            data: input.event.data,
+            completedAt: input.event.phase === "completed" || input.event.phase === "failed"
+                ? input.event.createdAt
+                : undefined,
+        },
+    });
+}
+export async function readTaskRegistryRecord(input) {
+    try {
+        const raw = await readFile(taskRegistryRecordPath(input.workdir, input.agentName, input.taskId), "utf-8");
+        return normalizeTaskRegistryRecord(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+export async function listTaskRegistryRecords(input) {
+    const limit = normalizeLimit(input.limit);
+    try {
+        const dir = taskRegistryDir(input.workdir, input.agentName);
+        const entries = await readdir(dir, { withFileTypes: true });
+        const records = await Promise.all(entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+            .map(async (entry) => {
+            try {
+                const raw = await readFile(join(dir, entry.name), "utf-8");
+                return normalizeTaskRegistryRecord(JSON.parse(raw));
+            }
+            catch {
+                return null;
+            }
+        }));
+        return records
+            .filter((record) => !!record)
+            .filter((record) => !input.status || record.status === input.status)
+            .filter((record) => !input.route || record.route === input.route)
+            .filter((record) => !input.visibility || record.visibility === input.visibility)
+            .filter((record) => !input.parentTaskId || record.parentTaskId === input.parentTaskId)
+            .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) || right.createdAt.localeCompare(left.createdAt))
+            .slice(0, limit);
+    }
+    catch {
+        return [];
+    }
+}
+const TASK_SURFACE_STAGES = [
+    "queued",
+    "framing",
+    "dispatching",
+    "executing",
+    "observing",
+    "reviewing",
+    "done",
+    "blocked",
+];
+export function createTaskSurfaceView(record) {
+    const dispatches = taskSurfaceDispatches(record.data);
+    const reviews = taskSurfaceReviews(record.data);
+    const followUps = taskSurfaceFollowUps(record.data);
+    const memoryProposalRefs = uniqueMemoryProposalRefs([
+        ...reviews.flatMap((review) => review.memoryProposalRefs),
+        ...taskSurfaceMemoryProposalRefs(record.data),
+    ]);
+    const report = taskSurfaceReport(record, reviews);
+    const related = taskSurfaceRelated(record);
+    return {
+        schemaVersion: 1,
+        surface: "task_lifecycle",
+        taskId: record.taskId,
+        title: record.title || record.objective || record.taskId,
+        kind: record.kind,
+        visibility: record.visibility,
+        route: record.route,
+        status: record.status,
+        stage: {
+            key: record.stage,
+            label: ownerStatusFromTaskStage(record.stage),
+            description: taskStageDescription(record.stage, record.summary || record.nextAction),
+            state: record.stage === "blocked" ? "blocked" : record.stage === "done" ? "done" : "active",
+        },
+        ownerStatus: record.ownerStatus,
+        summary: record.summary || report?.text,
+        nextAction: record.nextAction,
+        conversationId: record.conversationId,
+        parentTaskId: record.parentTaskId,
+        timestamps: {
+            createdAt: record.createdAt,
+            updatedAt: record.updatedAt,
+            completedAt: record.completedAt,
+        },
+        lifecycle: taskSurfaceLifecycle(record.stage),
+        counts: {
+            dispatches: dispatches.length,
+            reviews: reviews.length,
+            followUps: followUps.length,
+            memoryProposals: memoryProposalRefs.length,
+        },
+        related,
+        dispatches,
+        reviews,
+        followUps,
+        report,
+        sections: taskSurfaceSections({
+            record,
+            related,
+            dispatches,
+            reviews,
+            followUps,
+            report,
+        }),
+    };
+}
+function taskSurfaceLifecycle(currentStage) {
+    const currentIndex = TASK_SURFACE_STAGES.indexOf(currentStage);
+    return TASK_SURFACE_STAGES.map((stage, index) => {
+        let state = "pending";
+        if (currentStage === "blocked") {
+            state = stage === "blocked" ? "blocked" : index < TASK_SURFACE_STAGES.length - 1 ? "done" : "pending";
+        }
+        else if (currentStage === "done") {
+            state = stage === "blocked" ? "pending" : "done";
+        }
+        else if (index < currentIndex) {
+            state = "done";
+        }
+        else if (index === currentIndex) {
+            state = "active";
+        }
+        return {
+            key: stage,
+            label: ownerStatusFromTaskStage(stage),
+            state,
+        };
+    });
+}
+function taskStageDescription(stage, summary) {
+    const base = (() => {
+        if (stage === "queued")
+            return "Queued and waiting to start.";
+        if (stage === "framing")
+            return "Akemon is framing the owner request.";
+        if (stage === "dispatching")
+            return "Akemon is dispatching work to a capability.";
+        if (stage === "executing")
+            return "Execution is in progress.";
+        if (stage === "observing")
+            return "Akemon is observing the execution result.";
+        if (stage === "reviewing")
+            return "Akemon is reviewing the result for the owner report.";
+        if (stage === "done")
+            return "Finished.";
+        if (stage === "blocked")
+            return "Blocked.";
+        return "Queued.";
+    })();
+    return summary && summary !== base ? `${base} ${summary}` : base;
+}
+function taskSurfaceDispatches(data) {
+    const records = Array.isArray(data?.dispatchRecords) ? data.dispatchRecords : [];
+    return records.flatMap((item) => {
+        if (!item || typeof item !== "object")
+            return [];
+        const record = item;
+        const targetPeripheral = readObjectString(record, "targetPeripheral");
+        const capability = readObjectString(record, "capability");
+        if (!targetPeripheral && !capability)
+            return [];
+        return [{
+                id: readObjectString(record, "id"),
+                targetPeripheral: targetPeripheral || "unknown",
+                capability: capability || "unknown",
+                brief: readObjectString(record, "brief"),
+                expectedDeliverable: readObjectString(record, "expectedDeliverable"),
+                createdAt: readObjectString(record, "createdAt"),
+            }];
+    });
+}
+function taskSurfaceReviews(data) {
+    const records = Array.isArray(data?.reviewRecords) ? data.reviewRecords : [];
+    return records.flatMap((item) => {
+        if (!item || typeof item !== "object")
+            return [];
+        const record = item;
+        const reportText = readObjectString(record, "reportText");
+        const resultQuality = readObjectString(record, "resultQuality");
+        const completionDecision = readObjectString(record, "completionDecision");
+        if (!reportText && !resultQuality && !completionDecision)
+            return [];
+        return [{
+                id: readObjectString(record, "id"),
+                resultQuality,
+                completionDecision,
+                followUpNeeded: record.followUpNeeded === true,
+                summary: readObjectString(record, "summary"),
+                reportText,
+                createdAt: readObjectString(record, "createdAt"),
+                memoryProposalRefs: normalizeSurfaceMemoryProposalRefs(record.memoryProposalRefs),
+            }];
+    });
+}
+function taskSurfaceFollowUps(data) {
+    const records = Array.isArray(data?.followUps) ? data.followUps : [];
+    return records.flatMap((item) => {
+        if (!item || typeof item !== "object")
+            return [];
+        const record = item;
+        const text = readObjectString(record, "text");
+        if (!text)
+            return [];
+        return [{
+                id: readObjectString(record, "id"),
+                kind: readObjectString(record, "kind") || "note",
+                text,
+                createdAt: readObjectString(record, "createdAt"),
+                status: readObjectString(record, "status") || "queued",
+                absorbedAt: readObjectString(record, "absorbedAt"),
+            }];
+    });
+}
+function taskSurfaceMemoryProposalRefs(data) {
+    const refs = normalizeSurfaceMemoryProposalRefs(data?.memoryProposalRefs);
+    const memoryProposalId = readRecordString(data, "memoryProposalId");
+    if (!memoryProposalId)
+        return refs;
+    return uniqueMemoryProposalRefs([
+        ...refs,
+        { memoryProposalId },
+    ]);
+}
+function taskSurfaceReport(record, reviews) {
+    const latestReview = reviews[reviews.length - 1];
+    const text = latestReview?.reportText || readRecordString(record.data, "reportText");
+    if (!text)
+        return undefined;
+    return {
+        text,
+        resultQuality: latestReview?.resultQuality || readRecordString(record.data, "latestReviewQuality"),
+        completionDecision: latestReview?.completionDecision || readRecordString(record.data, "latestCompletionDecision"),
+        followUpNeeded: typeof record.data?.followUpNeeded === "boolean"
+            ? record.data.followUpNeeded
+            : latestReview?.followUpNeeded,
+    };
+}
+function taskSurfaceRelated(record) {
+    const related = [];
+    if (record.conversationId) {
+        related.push({ kind: "conversation", id: record.conversationId, label: `Conversation ${shortTaskId(record.conversationId)}` });
+    }
+    const orderId = readRecordString(record.data, "orderId");
+    const productName = readRecordString(record.data, "productName");
+    const productId = readRecordString(record.data, "productId");
+    if (orderId)
+        related.push({ kind: "order", id: orderId, label: `Order ${shortTaskId(orderId)}` });
+    if (productName || productId) {
+        related.push({
+            kind: "product",
+            id: productId,
+            label: productName || `Product ${shortTaskId(productId || "")}`,
+        });
+    }
+    const sessionId = readRecordString(record.data, "sessionId");
+    if (sessionId)
+        related.push({ kind: "interactive_session", id: sessionId, label: `Interactive session ${shortTaskId(sessionId)}` });
+    const softwareAgentId = readRecordString(record.data, "softwareAgentId");
+    if (softwareAgentId)
+        related.push({ kind: "software_agent", id: softwareAgentId, label: prettifyTaskToken(softwareAgentId) });
+    const taskKey = readRecordString(record.data, "taskKey");
+    if (taskKey)
+        related.push({ kind: "task_key", id: taskKey, label: taskKey });
+    return related;
+}
+function taskSurfaceSections(input) {
+    const sections = [{
+            kind: "state",
+            title: "Current state",
+            text: taskStageDescription(input.record.stage, input.record.summary || input.record.nextAction),
+        }];
+    if (input.related.length) {
+        sections.push({
+            kind: "related",
+            title: "Related",
+            text: input.related.map((item) => item.label).join("\n"),
+        });
+    }
+    if (input.dispatches.length) {
+        sections.push({
+            kind: "dispatch",
+            title: "Dispatch records",
+            text: input.dispatches.slice(-5).map((record) => {
+                const head = [record.targetPeripheral, record.capability].filter(Boolean).join(".");
+                return [head, record.brief, record.expectedDeliverable].filter(Boolean).join("\n");
+            }).join("\n\n"),
+        });
+    }
+    if (input.reviews.length) {
+        sections.push({
+            kind: "review",
+            title: "Review records",
+            text: input.reviews.slice(-5).map((record) => {
+                const decision = [
+                    record.resultQuality,
+                    record.completionDecision,
+                    record.followUpNeeded ? "follow-up needed" : "",
+                ].filter(Boolean).join(" / ");
+                const memoryRefs = record.memoryProposalRefs.length
+                    ? `Memory proposals: ${record.memoryProposalRefs.map((item) => item.memoryProposalId).join(", ")}`
+                    : "";
+                return [decision, record.summary, memoryRefs, record.reportText].filter(Boolean).join("\n");
+            }).join("\n\n"),
+        });
+    }
+    if (input.followUps.length) {
+        sections.push({
+            kind: "follow_up",
+            title: "Follow-ups",
+            text: input.followUps.slice(-5).map((item) => {
+                const status = item.status || "queued";
+                return `${prettifyTaskToken(item.kind)} (${prettifyTaskToken(status)}): ${item.text}`;
+            }).join("\n"),
+        });
+    }
+    if (input.report?.text) {
+        sections.push({
+            kind: "report",
+            title: "Report",
+            text: input.report.text,
+        });
+    }
+    else if (input.record.status === "failed" || input.record.status === "succeeded") {
+        sections.push({
+            kind: "result",
+            title: "Result",
+            text: input.record.summary || input.record.objective,
+        });
+    }
+    return sections;
+}
+function normalizeSurfaceMemoryProposalRefs(value) {
+    if (!Array.isArray(value))
+        return [];
+    return uniqueMemoryProposalRefs(value.flatMap((item) => {
+        if (!item || typeof item !== "object")
+            return [];
+        const record = item;
+        const memoryProposalId = readObjectString(record, "memoryProposalId");
+        if (!memoryProposalId)
+            return [];
+        return [{
+                memoryProposalId,
+                source: readObjectString(record, "source"),
+                summary: readObjectString(record, "summary"),
+            }];
+    }));
+}
+function uniqueMemoryProposalRefs(refs) {
+    const seen = new Set();
+    return refs.filter((ref) => {
+        if (!ref.memoryProposalId || seen.has(ref.memoryProposalId))
+            return false;
+        seen.add(ref.memoryProposalId);
+        return true;
+    });
+}
+function taskObjectiveFromEvent(event) {
+    const data = event.data || {};
+    const goal = data.goal;
+    if (typeof goal === "string" && goal.trim())
+        return goal.trim();
+    const objective = data.objective;
+    if (typeof objective === "string" && objective.trim())
+        return objective.trim();
+    return event.summary || event.taskId;
+}
+function taskSourceFromEvent(event) {
+    const source = event.data?.source;
+    if (typeof source === "string" && source.trim())
+        return source.trim();
+    if (event.route)
+        return event.route;
+    return DEFAULT_TASK_SOURCE;
+}
+function normalizeTaskRegistryRecord(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    if (record.schemaVersion !== 1 || typeof record.taskId !== "string" || !record.taskId)
+        return null;
+    const data = record.data && typeof record.data === "object" && !Array.isArray(record.data)
+        ? record.data
+        : undefined;
+    const normalizedStatus = isTaskRegistryStatus(record.status) ? record.status : "pending";
+    const normalizedStage = isTaskRegistryStage(record.stage) ? record.stage : inferTaskStageFromStatus(normalizedStatus);
+    const normalizedSource = typeof record.source === "string" && record.source ? record.source : DEFAULT_TASK_SOURCE;
+    const normalizedObjective = typeof record.objective === "string" && record.objective ? record.objective : record.taskId;
+    const presentation = deriveTaskPresentation({
+        taskId: record.taskId,
+        source: normalizedSource,
+        status: normalizedStatus,
+        stage: normalizedStage,
+        objective: normalizedObjective,
+        kind: record.kind,
+        visibility: record.visibility,
+        title: record.title,
+        ownerStatus: record.ownerStatus,
+        nextAction: record.nextAction,
+        parentTaskId: record.parentTaskId,
+        route: typeof record.route === "string" ? record.route : undefined,
+        summary: typeof record.summary === "string" ? record.summary : undefined,
+        data,
+    });
+    return {
+        schemaVersion: 1,
+        taskId: record.taskId,
+        source: normalizedSource,
+        status: normalizedStatus,
+        stage: normalizedStage,
+        objective: normalizedObjective,
+        kind: isTaskRegistryKind(record.kind) ? record.kind : presentation.kind,
+        visibility: isTaskRegistryVisibility(record.visibility) ? record.visibility : presentation.visibility,
+        title: typeof record.title === "string" && record.title ? record.title : presentation.title,
+        ownerStatus: typeof record.ownerStatus === "string" && record.ownerStatus ? record.ownerStatus : presentation.ownerStatus,
+        nextAction: typeof record.nextAction === "string" ? record.nextAction : presentation.nextAction,
+        parentTaskId: typeof record.parentTaskId === "string" ? record.parentTaskId : presentation.parentTaskId,
+        route: typeof record.route === "string" ? record.route : undefined,
+        summary: typeof record.summary === "string" ? record.summary : undefined,
+        conversationId: typeof record.conversationId === "string" ? record.conversationId : undefined,
+        refs: Array.isArray(record.refs) ? record.refs : undefined,
+        data,
+        createdAt: typeof record.createdAt === "string" ? record.createdAt : new Date(0).toISOString(),
+        updatedAt: typeof record.updatedAt === "string" ? record.updatedAt : new Date(0).toISOString(),
+        completedAt: typeof record.completedAt === "string" ? record.completedAt : undefined,
+    };
+}
+function deriveTaskPresentation(record) {
+    const kind = isTaskRegistryKind(record.kind) ? record.kind : inferTaskKind(record);
+    const capability = readRecordString(record.data, "capability");
+    const visibility = isTaskRegistryVisibility(record.visibility)
+        ? record.visibility
+        : inferTaskVisibility(record, kind, capability);
+    return {
+        kind,
+        visibility,
+        title: record.title || inferTaskTitle(record, kind, capability),
+        ownerStatus: record.ownerStatus || ownerStatusFromTaskStage(record.stage),
+        nextAction: record.nextAction ?? inferTaskNextAction(record),
+        parentTaskId: record.parentTaskId || inferTaskParentId(record, visibility),
+    };
+}
+function inferTaskKind(record) {
+    const route = record.route || "";
+    const source = record.source || readRecordString(record.data, "source") || "";
+    if (route === "interactive-session" || source === "workbench_http")
+        return "terminal";
+    if (route === "software-agent")
+        return "software_agent";
+    if (route === "relay-order" || source === "relay_order")
+        return "order";
+    if (route === "user-task" || source === "owner_recurring_task")
+        return "scheduled_task";
+    if (route === "relay-task" || source === "relay_platform_task")
+        return "relay_task";
+    if (route === "memory_cm")
+        return "memory";
+    if (route === "core_cm" || source === "local_chat" || source === "local_chat_command")
+        return "chat";
+    return "unknown";
+}
+function inferTaskVisibility(record, kind, capability) {
+    const source = record.source || readRecordString(record.data, "source") || "";
+    if (kind === "terminal" && source === "workbench_http")
+        return "technical";
+    if (kind === "terminal" && capability && ["resize_session", "send_input", "inspect_session", "set_input_mode", "list_sessions"].includes(capability)) {
+        return "technical";
+    }
+    return "primary";
+}
+function inferTaskTitle(record, kind, capability) {
+    if (kind === "terminal" && capability)
+        return terminalCapabilityTitle(capability, record.data);
+    const productName = readRecordString(record.data, "productName");
+    const orderId = readRecordString(record.data, "orderId");
+    if (productName)
+        return orderId ? `Order: ${productName}` : productName;
+    if (orderId)
+        return `Order ${shortTaskId(orderId)}`;
+    const goal = readRecordString(record.data, "goal");
+    if (goal)
+        return goal;
+    return record.objective || record.summary || record.taskId;
+}
+function inferTaskNextAction(record) {
+    if (record.stage === "queued")
+        return "Waiting to start";
+    if (record.stage === "framing")
+        return "Akemon is framing the request";
+    if (record.stage === "dispatching")
+        return "Dispatching to a capability";
+    if (record.stage === "executing")
+        return "Waiting for execution";
+    if (record.stage === "observing")
+        return "Observing execution result";
+    if (record.stage === "reviewing")
+        return "Reviewing result for report";
+    if (record.stage === "blocked")
+        return "Review blocked state";
+    if (record.status === "waiting") {
+        const nextRetryAt = readRecordString(record.data, "nextRetryAt");
+        return nextRetryAt ? `Retry at ${nextRetryAt}` : "Waiting for retry or external progress";
+    }
+    if (record.status === "pending")
+        return "Waiting to start";
+    if (record.status === "running")
+        return "Wait for completion";
+    if (record.status === "failed")
+        return "Review error";
+    return undefined;
+}
+function inferTaskParentId(record, visibility) {
+    if (visibility !== "technical")
+        return undefined;
+    const sessionId = readRecordString(record.data, "sessionId");
+    return sessionId ? `interactive-session:${sessionId}` : undefined;
+}
+function ownerStatusFromTaskStage(stage) {
+    if (stage === "queued")
+        return "Queued";
+    if (stage === "framing")
+        return "Framing";
+    if (stage === "dispatching")
+        return "Dispatching";
+    if (stage === "executing")
+        return "Executing";
+    if (stage === "observing")
+        return "Observing";
+    if (stage === "reviewing")
+        return "Reviewing";
+    if (stage === "done")
+        return "Done";
+    if (stage === "blocked")
+        return "Blocked";
+    return "Queued";
+}
+function terminalCapabilityTitle(capability, data) {
+    const sessionId = readRecordString(data, "sessionId");
+    const suffix = sessionId ? ` ${shortTaskId(sessionId)}` : "";
+    switch (capability) {
+        case "start_session": return `Start terminal${suffix}`;
+        case "send_input": return `Send terminal input${suffix}`;
+        case "resize_session": return `Resize terminal${suffix}`;
+        case "stop_session": return `Stop terminal${suffix}`;
+        case "inspect_session": return `Inspect terminal${suffix}`;
+        case "set_input_mode": return `Change terminal input mode${suffix}`;
+        case "list_sessions": return "List terminal sessions";
+        default: return `Terminal action ${capability}`;
+    }
+}
+function readRecordString(data, key) {
+    const value = data?.[key];
+    if (typeof value === "string" && value.trim())
+        return value.trim();
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return undefined;
+}
+function readObjectString(data, key) {
+    const value = data[key];
+    if (typeof value === "string" && value.trim())
+        return value.trim();
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return undefined;
+}
+function shortTaskId(value) {
+    if (value.length <= 18)
+        return value;
+    return `${value.slice(0, 8)}...${value.slice(-6)}`;
+}
+function prettifyTaskToken(value) {
+    return value
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/\b\w/g, (char) => char.toUpperCase());
+}
+function isTaskRegistryStatus(value) {
+    return value === "pending"
+        || value === "running"
+        || value === "waiting"
+        || value === "succeeded"
+        || value === "failed"
+        || value === "info";
+}
+function isTaskRegistryStage(value) {
+    return value === "queued"
+        || value === "framing"
+        || value === "dispatching"
+        || value === "executing"
+        || value === "observing"
+        || value === "reviewing"
+        || value === "done"
+        || value === "blocked";
+}
+function normalizeTaskRegistryStage(value) {
+    return isTaskRegistryStage(value) ? value : undefined;
+}
+function inferTaskStageFromEvent(event) {
+    if (event.status === "failed" || event.phase === "failed")
+        return "blocked";
+    if (event.status === "waiting")
+        return "blocked";
+    if (event.status === "succeeded" || event.status === "info" || event.phase === "completed")
+        return "done";
+    if (event.phase === "reported")
+        return "reviewing";
+    if (event.phase === "observed")
+        return "observing";
+    if (event.phase === "delegated")
+        return "dispatching";
+    if (event.phase === "routed")
+        return "framing";
+    return inferTaskStageFromStatus(event.status);
+}
+function inferTaskStageFromStatus(status) {
+    if (status === "pending")
+        return "queued";
+    if (status === "waiting" || status === "failed")
+        return "blocked";
+    if (status === "succeeded" || status === "info")
+        return "done";
+    if (status === "running")
+        return "executing";
+    return "queued";
+}
+function isTaskRegistryKind(value) {
+    return value === "chat"
+        || value === "memory"
+        || value === "order"
+        || value === "relay_task"
+        || value === "scheduled_task"
+        || value === "software_agent"
+        || value === "terminal"
+        || value === "unknown";
+}
+function isTaskRegistryVisibility(value) {
+    return value === "primary" || value === "technical";
+}
+function mergeTaskData(existing, patch) {
+    if (!existing && !patch)
+        return undefined;
+    const merged = { ...(existing || {}), ...(patch || {}) };
+    if (typeof existing?.source === "string" && existing.source.trim()) {
+        merged.source = existing.source;
+    }
+    if (typeof existing?.objective === "string" && existing.objective.trim()) {
+        merged.objective = existing.objective;
+    }
+    return merged;
+}
+function normalizeLimit(value) {
+    if (!Number.isInteger(value) || !value || value <= 0)
+        return 50;
+    return Math.min(value, 200);
+}
+function safeTaskFilename(taskId) {
+    const safe = taskId
+        .replace(/[^A-Za-z0-9._:-]+/g, "_")
+        .replace(/^\.+/, "")
+        .replace(/[. ]+$/g, "")
+        .slice(0, 160);
+    return safe || "task";
+}