@voybio/ace-swarm 0.1.0

package/dist/ace-autonomy.js

@@ -0,0 +1,472 @@
+import { safeRead, wsPath } from "./helpers.js";
+import { readRunLedger } from "./run-ledger.js";
+import { isReadError } from "./shared.js";
+import { readStatusEvents } from "./status-events.js";
+export const ACE_TASK_CONTRACT_FILES = [
+    "agent-state/TASK.md",
+    "agent-state/SCOPE.md",
+    "agent-state/QUALITY_GATES.md",
+    "agent-state/HANDOFF.json",
+];
+export const ACE_DEFAULT_STATE_SOURCES = [
+    "agent-state/TASK.md",
+    "agent-state/SCOPE.md",
+    "agent-state/QUALITY_GATES.md",
+    "agent-state/STATUS.md",
+    "agent-state/HANDOFF.json",
+    "agent-state/EVIDENCE_LOG.md",
+];
+export const ACE_DEFAULT_CONTINUITY_SOURCES = [
+    "agent-state/TASK.md",
+    "agent-state/SCOPE.md",
+    "agent-state/QUALITY_GATES.md",
+    "agent-state/HANDOFF.json",
+    "agent-state/STATUS.md",
+    "agent-state/DECISIONS.md",
+    "agent-state/RISKS.md",
+    "agent-state/EVIDENCE_LOG.md",
+];
+export const DEFAULT_AUTONOMY_POLICY = {
+    orchestrator_preflight: true,
+    recall_context: true,
+    state_sources: [...ACE_DEFAULT_STATE_SOURCES],
+    before_run_checks: [],
+    stop_checks: [],
+    review_mode: null,
+};
+export const DEFAULT_CONTINUITY_POLICY = {
+    enabled: true,
+    source_paths: [...ACE_DEFAULT_CONTINUITY_SOURCES],
+    max_sources: 6,
+    max_excerpt_chars: 450,
+    max_total_chars: 2600,
+    max_status_events: 6,
+    max_run_ledger_entries: 4,
+    include_snapshot: true,
+};
+function uniqueTrimmed(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values ?? []) {
+        const trimmed = value.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        result.push(trimmed);
+    }
+    return result;
+}
+function normalizePositiveInt(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? Math.floor(value)
+        : fallback;
+}
+function clipText(input, max = 700) {
+    const normalized = input.trim();
+    if (normalized.length <= max)
+        return normalized;
+    return `${normalized.slice(0, Math.max(0, max - 3)).trimEnd()}...`;
+}
+function extractEvidenceExcerpt(raw, max = 900) {
+    const lines = raw
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .filter((line) => line.trim().length > 0);
+    return clipText(lines.slice(-18).join("\n"), max);
+}
+function extractStateExcerpt(path, raw, max = 900) {
+    if (path.endsWith("EVIDENCE_LOG.md")) {
+        return extractEvidenceExcerpt(raw, max);
+    }
+    if (path.endsWith("HANDOFF.json")) {
+        try {
+            return clipText(JSON.stringify(JSON.parse(raw), null, 2), max);
+        }
+        catch {
+            return clipText(raw, max);
+        }
+    }
+    return clipText(raw, max);
+}
+function coerceObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function readString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function readStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+}
+function loadSnapshotIndex() {
+    const raw = safeRead("agent-state/context-snapshots/index.json");
+    if (isReadError(raw))
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        const asObject = coerceObject(parsed);
+        const snapshots = Array.isArray(asObject?.snapshots) ? asObject.snapshots : [];
+        return {
+            snapshots: snapshots
+                .map((entry) => {
+                const item = coerceObject(entry);
+                const name = readString(item?.name);
+                const file = readString(item?.file);
+                const timestamp = readString(item?.timestamp);
+                const summary = readString(item?.summary);
+                if (!name || !file || !timestamp || !summary)
+                    return undefined;
+                return { name, file, timestamp, summary };
+            })
+                .filter((entry) => Boolean(entry)),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function normalizeAutonomyPolicy(input) {
+    const stateSources = uniqueTrimmed(input?.state_sources);
+    return {
+        orchestrator_preflight: Boolean(input?.orchestrator_preflight),
+        recall_context: Boolean(input?.recall_context),
+        state_sources: stateSources.length > 0 ? stateSources : [...ACE_DEFAULT_STATE_SOURCES],
+        before_run_checks: uniqueTrimmed(input?.before_run_checks),
+        stop_checks: uniqueTrimmed(input?.stop_checks),
+        review_mode: readString(input?.review_mode) ?? null,
+    };
+}
+export function normalizeContinuityPolicy(input) {
+    const sourcePaths = uniqueTrimmed(input?.source_paths);
+    return {
+        enabled: input?.enabled == null ? true : Boolean(input.enabled),
+        source_paths: sourcePaths.length > 0 ? sourcePaths : [...ACE_DEFAULT_CONTINUITY_SOURCES],
+        max_sources: normalizePositiveInt(input?.max_sources, DEFAULT_CONTINUITY_POLICY.max_sources),
+        max_excerpt_chars: normalizePositiveInt(input?.max_excerpt_chars, DEFAULT_CONTINUITY_POLICY.max_excerpt_chars),
+        max_total_chars: normalizePositiveInt(input?.max_total_chars, DEFAULT_CONTINUITY_POLICY.max_total_chars),
+        max_status_events: normalizePositiveInt(input?.max_status_events, DEFAULT_CONTINUITY_POLICY.max_status_events),
+        max_run_ledger_entries: normalizePositiveInt(input?.max_run_ledger_entries, DEFAULT_CONTINUITY_POLICY.max_run_ledger_entries),
+        include_snapshot: input?.include_snapshot == null ? true : Boolean(input.include_snapshot),
+    };
+}
+export function readAceTaskContractAssessment() {
+    const missing = [];
+    const invalid = [];
+    const blockers = [];
+    const files = [];
+    let handoffStatus;
+    let handoffReason;
+    for (const path of ACE_TASK_CONTRACT_FILES) {
+        const raw = safeRead(path);
+        if (isReadError(raw)) {
+            missing.push(path);
+            files.push({
+                path,
+                present: false,
+                valid: false,
+                note: "missing",
+            });
+            continue;
+        }
+        if (path.endsWith(".json")) {
+            try {
+                const parsed = JSON.parse(raw);
+                const asObject = coerceObject(parsed);
+                const transition = coerceObject(asObject?.transition);
+                const payload = coerceObject(asObject?.payload);
+                handoffStatus = readString(transition?.status) ?? readString(asObject?.status);
+                handoffReason = readString(transition?.reason) ?? readString(asObject?.reason);
+                const knownIssues = readStringArray(payload?.known_issues);
+                const normalizedState = `${handoffStatus ?? ""} ${handoffReason ?? ""}`.toLowerCase();
+                if (/\b(blocked|failed|rejected|invalid)\b/.test(normalizedState)) {
+                    blockers.push(`Handoff indicates non-ready state (${handoffStatus ?? "unknown"}).`);
+                }
+                if (knownIssues.length > 0) {
+                    blockers.push(`Handoff carries known issues (${knownIssues.length}).`);
+                }
+                files.push({
+                    path,
+                    present: true,
+                    valid: true,
+                    note: handoffStatus ? `status=${handoffStatus}` : "valid JSON",
+                });
+            }
+            catch {
+                invalid.push(path);
+                files.push({
+                    path,
+                    present: true,
+                    valid: false,
+                    note: "invalid JSON",
+                });
+            }
+            continue;
+        }
+        const trimmed = raw.trim();
+        const valid = trimmed.length > 0;
+        if (!valid)
+            invalid.push(path);
+        files.push({
+            path,
+            present: true,
+            valid,
+            note: valid ? "present" : "empty",
+        });
+    }
+    const ok = missing.length === 0 && invalid.length === 0 && blockers.length === 0;
+    const issues = [...missing.map((path) => `missing ${path}`), ...invalid.map((path) => `invalid ${path}`), ...blockers];
+    return {
+        ok,
+        summary: ok
+            ? "ACE quartet is aligned for non-trivial work."
+            : `ACE quartet requires attention: ${issues.join("; ")}`,
+        missing,
+        invalid,
+        blockers,
+        files,
+        handoff_status: handoffStatus,
+        handoff_reason: handoffReason,
+    };
+}
+export function readAceContextSnapshot(name) {
+    const index = loadSnapshotIndex();
+    if (!index || index.snapshots.length === 0)
+        return undefined;
+    const selected = name
+        ? index.snapshots.find((entry) => entry.name.toLowerCase() === name.toLowerCase())
+        : index.snapshots[0];
+    if (!selected)
+        return undefined;
+    const relPath = wsPath("agent-state", "context-snapshots", selected.file);
+    const content = safeRead(relPath);
+    if (isReadError(content))
+        return undefined;
+    return {
+        name: selected.name,
+        timestamp: selected.timestamp,
+        summary: selected.summary,
+        path: relPath,
+        content: clipText(content, 1200),
+    };
+}
+export function buildAceRecallContext(input) {
+    const stateSources = uniqueTrimmed(input?.state_sources ?? ACE_DEFAULT_STATE_SOURCES);
+    const excerptChars = normalizePositiveInt(input?.excerpt_chars, 900);
+    return {
+        task_contract: readAceTaskContractAssessment(),
+        state_slices: stateSources.map((path) => {
+            const raw = safeRead(path);
+            if (isReadError(raw)) {
+                return {
+                    path,
+                    present: false,
+                    excerpt: raw,
+                };
+            }
+            return {
+                path,
+                present: true,
+                excerpt: extractStateExcerpt(path, raw, excerptChars),
+            };
+        }),
+        snapshot: readAceContextSnapshot(input?.snapshot_name),
+    };
+}
+export function buildAceContinuityPacket(input) {
+    const policy = normalizeContinuityPolicy(input?.policy);
+    if (!policy.enabled) {
+        return {
+            generated_at: new Date().toISOString(),
+            summary: "ACE continuity packet disabled by runtime policy.",
+            highlights: ["Continuity packet disabled."],
+            task_contract_ok: true,
+            blockers: [],
+            included_sources: [],
+            missing_sources: [],
+            dropped_sources: [],
+            recent_status_events: [],
+            recent_run_ledger: [],
+            budget_report: {
+                max_status_events: policy.max_status_events,
+                max_run_ledger_entries: policy.max_run_ledger_entries,
+                max_sources: policy.max_sources,
+                max_excerpt_chars: policy.max_excerpt_chars,
+                max_total_chars: policy.max_total_chars,
+                used_chars: 0,
+            },
+        };
+    }
+    const recall = buildAceRecallContext({
+        state_sources: input?.state_sources ?? policy.source_paths,
+        snapshot_name: policy.include_snapshot ? input?.snapshot_name : undefined,
+        excerpt_chars: policy.max_excerpt_chars,
+    });
+    const includedSources = [];
+    const missingSources = recall.state_slices
+        .filter((entry) => !entry.present)
+        .map((entry) => entry.path);
+    const droppedSources = [];
+    let usedChars = 0;
+    for (const entry of recall.state_slices.filter((item) => item.present)) {
+        if (includedSources.length >= policy.max_sources) {
+            droppedSources.push(entry.path);
+            continue;
+        }
+        const remainingBudget = policy.max_total_chars - usedChars;
+        if (remainingBudget <= 0) {
+            droppedSources.push(entry.path);
+            continue;
+        }
+        const excerpt = clipText(entry.excerpt, Math.min(policy.max_excerpt_chars, remainingBudget));
+        if (!excerpt) {
+            droppedSources.push(entry.path);
+            continue;
+        }
+        includedSources.push({
+            path: entry.path,
+            excerpt,
+            chars: excerpt.length,
+        });
+        usedChars += excerpt.length;
+    }
+    const highlights = [
+        recall.task_contract.summary,
+        ...(recall.task_contract.blockers.length > 0
+            ? recall.task_contract.blockers
+            : []),
+        `Included ${includedSources.length} state sources within a ${policy.max_total_chars}-character budget.`,
+        ...(droppedSources.length > 0
+            ? [`Dropped ${droppedSources.length} lower-priority sources by budget.`]
+            : []),
+        ...(missingSources.length > 0
+            ? [`Missing ${missingSources.length} configured state sources.`]
+            : []),
+    ];
+    const recentStatusEvents = readStatusEvents(policy.max_status_events).map((event) => ({
+        timestamp: event.timestamp,
+        source_module: event.source_module,
+        event_type: event.event_type,
+        status: event.status,
+        summary: readString(coerceObject(event.payload)?.summary) ?? event.event_type,
+    }));
+    const ledger = readRunLedger();
+    const recentRunLedger = ledger.entries
+        .slice(Math.max(0, ledger.entries.length - policy.max_run_ledger_entries))
+        .map((entry) => ({
+        timestamp: entry.timestamp_utc,
+        tool: entry.tool,
+        category: entry.category,
+        message: entry.message,
+        artifacts: entry.artifacts.slice(0, 4),
+    }));
+    if (recentStatusEvents.length > 0) {
+        highlights.push(`Recent status events: ${recentStatusEvents.length} within the configured visibility window.`);
+    }
+    if (recentRunLedger.length > 0) {
+        highlights.push(`Recent run-ledger entries: ${recentRunLedger.length} within the configured visibility window.`);
+    }
+    if (policy.include_snapshot && recall.snapshot) {
+        highlights.push(`Context snapshot ${recall.snapshot.name} (${recall.snapshot.timestamp}) is available.`);
+    }
+    return {
+        generated_at: new Date().toISOString(),
+        summary: `ACE continuity packet includes ${includedSources.length}/${recall.state_slices.length} configured state sources.`,
+        highlights,
+        task_contract_ok: recall.task_contract.ok,
+        blockers: [...recall.task_contract.blockers],
+        included_sources: includedSources,
+        missing_sources: missingSources,
+        dropped_sources: droppedSources,
+        recent_status_events: recentStatusEvents,
+        recent_run_ledger: recentRunLedger,
+        snapshot: policy.include_snapshot && recall.snapshot
+            ? {
+                name: recall.snapshot.name,
+                timestamp: recall.snapshot.timestamp,
+                summary: recall.snapshot.summary,
+                path: recall.snapshot.path,
+            }
+            : undefined,
+        budget_report: {
+            max_sources: policy.max_sources,
+            max_excerpt_chars: policy.max_excerpt_chars,
+            max_total_chars: policy.max_total_chars,
+            max_status_events: policy.max_status_events,
+            max_run_ledger_entries: policy.max_run_ledger_entries,
+            used_chars: usedChars,
+        },
+    };
+}
+export function formatAceRecallMarkdown(recall) {
+    const lines = [
+        `- Task contract: ${recall.task_contract.ok ? "aligned" : "attention required"}`,
+        ...recall.task_contract.files.map((file) => `- ${file.path}: ${file.valid ? "ok" : file.note}`),
+    ];
+    if (recall.task_contract.blockers.length > 0) {
+        lines.push(...recall.task_contract.blockers.map((entry) => `- blocker: ${entry}`));
+    }
+    if (recall.snapshot) {
+        lines.push(`- Context snapshot: ${recall.snapshot.name} (${recall.snapshot.timestamp}) — ${recall.snapshot.summary}`);
+    }
+    return lines.join("\n");
+}
+export function formatAceContinuityPacketMarkdown(packet) {
+    const lines = [
+        `- Summary: ${packet.summary}`,
+        `- Task contract: ${packet.task_contract_ok ? "aligned" : "attention required"}`,
+        `- Budget: ${packet.budget_report.used_chars}/${packet.budget_report.max_total_chars} chars across ${packet.included_sources.length}/${packet.budget_report.max_sources} sources`,
+        `- Status events: ${packet.recent_status_events.length}/${packet.budget_report.max_status_events}`,
+        `- Run ledger entries: ${packet.recent_run_ledger.length}/${packet.budget_report.max_run_ledger_entries}`,
+        ...packet.highlights.map((entry) => `- ${entry}`),
+    ];
+    if (packet.snapshot) {
+        lines.push(`- Context snapshot: ${packet.snapshot.name} (${packet.snapshot.timestamp}) — ${packet.snapshot.summary}`);
+    }
+    if (packet.dropped_sources.length > 0) {
+        lines.push(`- Dropped sources: ${packet.dropped_sources.join(", ")}`);
+    }
+    if (packet.missing_sources.length > 0) {
+        lines.push(`- Missing sources: ${packet.missing_sources.join(", ")}`);
+    }
+    if (packet.recent_status_events.length > 0) {
+        lines.push("", "## Recent Status Events");
+        lines.push(...packet.recent_status_events.map((entry) => `- ${entry.timestamp} | ${entry.source_module} | ${entry.event_type} | ${entry.status} — ${entry.summary}`));
+    }
+    if (packet.recent_run_ledger.length > 0) {
+        lines.push("", "## Recent Run Ledger");
+        lines.push(...packet.recent_run_ledger.map((entry) => `- ${entry.timestamp} | ${entry.tool} | ${entry.category} — ${entry.message}`));
+    }
+    const sourceBlocks = packet.included_sources.flatMap((entry) => [
+        "",
+        `### ${entry.path}`,
+        "```text",
+        entry.excerpt,
+        "```",
+    ]);
+    return [...lines, ...sourceBlocks].join("\n");
+}
+export function buildAutonomyHookEnv(policy, continuity = DEFAULT_CONTINUITY_POLICY) {
+    return {
+        ACE_AUTONOMY_POLICY_JSON: JSON.stringify(policy),
+        ACE_AUTONOMY_ORCHESTRATOR_PREFLIGHT: String(policy.orchestrator_preflight),
+        ACE_AUTONOMY_RECALL_CONTEXT: String(policy.recall_context),
+        ACE_AUTONOMY_STATE_SOURCES: policy.state_sources.join(","),
+        ACE_AUTONOMY_BEFORE_RUN_CHECKS: policy.before_run_checks.join(","),
+        ACE_AUTONOMY_STOP_CHECKS: policy.stop_checks.join(","),
+        ACE_AUTONOMY_REVIEW_MODE: policy.review_mode ?? "",
+        ACE_TASK_CONTRACT_FILES: [...ACE_TASK_CONTRACT_FILES].join(","),
+        ACE_CONTINUITY_POLICY_JSON: JSON.stringify(continuity),
+        ACE_CONTINUITY_ENABLED: String(continuity.enabled),
+        ACE_CONTINUITY_SOURCE_PATHS: continuity.source_paths.join(","),
+        ACE_CONTINUITY_MAX_SOURCES: String(continuity.max_sources),
+        ACE_CONTINUITY_MAX_EXCERPT_CHARS: String(continuity.max_excerpt_chars),
+        ACE_CONTINUITY_MAX_TOTAL_CHARS: String(continuity.max_total_chars),
+        ACE_CONTINUITY_MAX_STATUS_EVENTS: String(continuity.max_status_events),
+        ACE_CONTINUITY_MAX_RUN_LEDGER_ENTRIES: String(continuity.max_run_ledger_entries),
+        ACE_CONTINUITY_INCLUDE_SNAPSHOT: String(continuity.include_snapshot),
+    };
+}
+//# sourceMappingURL=ace-autonomy.js.map

package/dist/ace-context.d.ts

@@ -0,0 +1,29 @@
+import { buildAceContinuityPacket, buildAceRecallContext } from "./ace-autonomy.js";
+import { type AceInternalToolCatalogEntry } from "./ace-internal-tools.js";
+export type AceContextTier = "full" | "compressed" | "brief";
+export interface RenderAceContextOptions {
+    task: string;
+    role: string;
+    workspace: string;
+    tier?: AceContextTier;
+    tools?: string[];
+}
+export interface RenderAceContextResult {
+    systemPrompt: string;
+    tools: AceInternalToolCatalogEntry[];
+    stateDigest: string;
+    tokenEstimate: number;
+    tier: AceContextTier;
+}
+export interface ToolPlanResult {
+    prompt: string;
+    catalog: AceInternalToolCatalogEntry[];
+    recommended_tools: string[];
+    selection_limit: number;
+}
+export declare function renderAceRecallPromptBlock(recall?: ReturnType<typeof buildAceRecallContext>, includeSlices?: boolean): string;
+export declare function renderAceSnapshotPromptBlock(recall?: ReturnType<typeof buildAceRecallContext>): string;
+export declare function renderAceContinuityPromptBlock(packet?: ReturnType<typeof buildAceContinuityPacket>): string;
+export declare function buildToolPlan(options: RenderAceContextOptions): ToolPlanResult;
+export declare function renderAceContext(options: RenderAceContextOptions): RenderAceContextResult;
+//# sourceMappingURL=ace-context.d.ts.map