@abot-ai/runtime 1.0.0

package/dist/src/runtime/steps/planner-decision/parser.js

@@ -0,0 +1,241 @@
+import { normalizeRoleCallWorkingDirectory, } from "../../orchestration/role-calls/index.js";
+import { createWorkerCapabilityScopeDecisionContract, parseWorkerCapabilityScopeDecision, } from "../worker-capability-scope-decision.js";
+import { PLANNER_DECISION_ACTIONS, PLANNER_OBJECTIVE_MAX_LENGTH, PLANNER_RESULT_MAX_LENGTH, } from "./contracts.js";
+import { tracePlannerDecisionAccepted, tracePlannerDecisionRejected, tracePlannerEnvelopeAccepted, tracePlannerEnvelopeRejected, } from "./diagnostics.js";
+import { normalizeAvailableChildRoleIds } from "./format.js";
+import { normalizePlannerDecisionPlanContext, plannerPlanAllowsInvocation, } from "./plan.js";
+import { parsePlannerPlanInvocation } from "./plan-parser.js";
+import { readStructuredDecisionEnvelope } from "../../model/structured-decision-envelope.js";
+export function parsePlannerDecisionOutput(text, options = {}) {
+    const availableChildRoleIds = normalizeAvailableChildRoleIds(options.availableChildRoleIds ?? []);
+    const availableWorkerCapabilityCatalog = options.availableWorkerCapabilityCatalog ?? [];
+    const inheritedWorkingDirectory = options.inheritedWorkingDirectory;
+    if (inheritedWorkingDirectory !== undefined &&
+        normalizeRoleCallWorkingDirectory(inheritedWorkingDirectory) !==
+            inheritedWorkingDirectory) {
+        throw new Error("planner_inherited_working_directory_invalid");
+    }
+    const workerCapabilityScopeContract = createWorkerCapabilityScopeDecisionContract(availableWorkerCapabilityCatalog);
+    const planContext = options.planContext
+        ? normalizePlannerDecisionPlanContext(options.planContext)
+        : undefined;
+    const diagnostic = options.diagnostic;
+    let decoded;
+    try {
+        decoded = JSON.parse(text.trim());
+    }
+    catch {
+        return rejectEnvelope(text.length, [issue("planner_output_not_json", "decision")], diagnostic);
+    }
+    if (!asRecord(decoded)) {
+        return rejectEnvelope(text.length, [issue("planner_output_not_object", "decision")], diagnostic);
+    }
+    const record = readStructuredDecisionEnvelope(decoded);
+    if (!record) {
+        return rejectEnvelope(text.length, [issue("planner_output_envelope_invalid", "decision")], diagnostic);
+    }
+    if (diagnostic) {
+        tracePlannerEnvelopeAccepted({
+            diagnostic,
+            outputLength: text.length,
+            keyCount: Object.keys(record).length,
+        });
+    }
+    const issues = [];
+    let invocation;
+    let workerCapabilityScope;
+    let workingDirectory = inheritedWorkingDirectory;
+    const selectedAction = record.action === "return_result" ||
+        record.action === "return_failure" ||
+        record.action === "invoke_role"
+        ? record.action
+        : undefined;
+    const selectedKind = selectedAction;
+    if (!selectedAction) {
+        issues.push(issue("planner_action_invalid", "decision.action"));
+    }
+    else if (selectedAction === "return_result") {
+        exactKeys(record, ["action", "result"], issues);
+        if (planContext?.mode === "select") {
+            issues.push(issue("planner_plan_incomplete", "decision.action"));
+        }
+        validateBoundedText(record.result, PLANNER_RESULT_MAX_LENGTH, "planner_result_invalid", "decision.result", issues);
+    }
+    else if (selectedAction === "return_failure") {
+        exactKeys(record, ["action", "reason"], issues);
+        validateBoundedText(record.reason, PLANNER_RESULT_MAX_LENGTH, "planner_result_invalid", "decision.reason", issues);
+    }
+    else {
+        exactKeys(record, [
+            "action",
+            "roleId",
+            ...(planContext?.mode === "declare"
+                ? ["plan", "selectedItemIndexes"]
+                : planContext?.mode === "extend"
+                    ? ["extension", "selectedItemIndexes"]
+                    : planContext?.mode === "select"
+                        ? ["planItemIds"]
+                        : ["objective"]),
+            ...(record.roleId === "worker" && workerCapabilityScopeContract.required
+                ? ["workerCapabilityScope"]
+                : []),
+            ...(record.roleId === "worker" &&
+                inheritedWorkingDirectory === undefined
+                ? ["workingDirectory"]
+                : []),
+        ], issues);
+        if (typeof record.roleId !== "string" ||
+            !availableChildRoleIds.includes(record.roleId)) {
+            issues.push(issue("planner_child_role_unavailable", "decision.roleId"));
+        }
+        if (!plannerPlanAllowsInvocation(planContext)) {
+            issues.push(issue("planner_child_invocation_unavailable", "decision.action"));
+        }
+        invocation = parsePlannerInvocation(record, planContext, issues);
+        if (record.roleId === "worker" &&
+            inheritedWorkingDirectory === undefined &&
+            record.workingDirectory !== undefined) {
+            workingDirectory = normalizeRoleCallWorkingDirectory(record.workingDirectory);
+            if (!workingDirectory) {
+                issues.push(issue("planner_working_directory_invalid", "decision.workingDirectory"));
+            }
+        }
+        if (record.roleId === "worker" && workerCapabilityScopeContract.required) {
+            workerCapabilityScope = parsePlannerWorkerCapabilityScope(record.workerCapabilityScope, workerCapabilityScopeContract, issues);
+        }
+    }
+    if (issues.length > 0 ||
+        !selectedKind ||
+        (selectedAction === "invoke_role" &&
+            (!invocation ||
+                (record.roleId === "worker" && !workingDirectory) ||
+                (record.roleId === "worker" &&
+                    workerCapabilityScopeContract.required &&
+                    !workerCapabilityScope)))) {
+        if (diagnostic) {
+            tracePlannerDecisionRejected({
+                diagnostic,
+                issues,
+                ...(selectedKind ? { selectedAction: selectedKind } : {}),
+            });
+        }
+        return {
+            ok: false,
+            stage: "domain_parser",
+            issues: Object.freeze(issues),
+        };
+    }
+    const decision = selectedAction === "return_result"
+        ? {
+            action: "return_result",
+            result: record.result.trim(),
+        }
+        : selectedAction === "return_failure"
+            ? {
+                action: "return_failure",
+                reason: record.reason.trim(),
+            }
+            : record.roleId === "worker"
+                ? {
+                    action: "invoke_role",
+                    roleId: "worker",
+                    objective: invocation.objective,
+                    workingDirectory: workingDirectory,
+                    ...(workerCapabilityScope ? { workerCapabilityScope } : {}),
+                    ...(invocation.plannerPlan
+                        ? { plannerPlan: invocation.plannerPlan }
+                        : {}),
+                }
+                : {
+                    action: "invoke_role",
+                    roleId: record.roleId,
+                    objective: invocation.objective,
+                    ...(invocation.plannerPlan
+                        ? { plannerPlan: invocation.plannerPlan }
+                        : {}),
+                };
+    const accepted = deepFreeze(structuredClone(decision));
+    if (diagnostic) {
+        tracePlannerDecisionAccepted({
+            diagnostic,
+            decision: accepted,
+            ...(accepted.action === "invoke_role" && accepted.roleId === "worker"
+                ? {
+                    workingDirectorySource: inheritedWorkingDirectory === undefined
+                        ? "model"
+                        : "inherited",
+                }
+                : {}),
+        });
+    }
+    return { ok: true, decision: accepted };
+}
+function parsePlannerInvocation(record, planContext, issues) {
+    if (planContext) {
+        return parsePlannerPlanInvocation(record, planContext, issues);
+    }
+    validateBoundedText(record.objective, PLANNER_OBJECTIVE_MAX_LENGTH, "planner_objective_invalid", "decision.objective", issues);
+    return typeof record.objective === "string" &&
+        record.objective.trim().length > 0 &&
+        record.objective.length <= PLANNER_OBJECTIVE_MAX_LENGTH
+        ? { objective: record.objective.trim() }
+        : undefined;
+}
+function parsePlannerWorkerCapabilityScope(value, contract, issues) {
+    const parsed = parseWorkerCapabilityScopeDecision(value, contract);
+    if (!parsed) {
+        issues.push(issue("planner_worker_capability_scope_invalid", "decision.workerCapabilityScope.catalogGroupIds"));
+        return undefined;
+    }
+    return parsed;
+}
+function rejectEnvelope(outputLength, issues, diagnostic) {
+    if (diagnostic) {
+        tracePlannerEnvelopeRejected({ diagnostic, outputLength, issues });
+    }
+    return {
+        ok: false,
+        stage: "json_envelope",
+        issues: Object.freeze([...issues]),
+    };
+}
+function exactKeys(record, expectedKeys, issues, path = "decision") {
+    const expected = new Set(expectedKeys);
+    const actual = Object.keys(record);
+    if (actual.length !== expected.size ||
+        actual.some((key) => !expected.has(key))) {
+        issues.push(issue("planner_decision_shape_invalid", path));
+    }
+}
+function validateBoundedText(value, maximumLength, code, path, issues) {
+    const normalized = typeof value === "string" ? value.trim() : "";
+    if (typeof value !== "string" ||
+        normalized.length === 0 ||
+        value.length > maximumLength) {
+        issues.push(issue(code, path));
+    }
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function issue(code, path) {
+    return {
+        code,
+        path,
+        message: code === "planner_action_invalid"
+            ? `Action must be one of: ${PLANNER_DECISION_ACTIONS.join(", ")}.`
+            : `Planner decision failed ${code}.`,
+    };
+}
+function deepFreeze(value, seen = new WeakSet()) {
+    if (typeof value !== "object" || value === null || seen.has(value)) {
+        return value;
+    }
+    seen.add(value);
+    for (const child of Object.values(value)) {
+        deepFreeze(child, seen);
+    }
+    return Object.freeze(value);
+}

package/dist/src/runtime/steps/planner-decision/plan-parser.d.ts

@@ -0,0 +1,7 @@
+import { type RoleCallPlanBinding } from "../../orchestration/role-calls/index.js";
+import { type PlannerDecisionPlanContext, type PlannerDecisionValidationIssue } from "./contracts.js";
+export type PlannerPlanInvocation = Readonly<{
+    objective: string;
+    plannerPlan: RoleCallPlanBinding;
+}>;
+export declare function parsePlannerPlanInvocation(record: Record<string, unknown>, planContext: PlannerDecisionPlanContext, issues: PlannerDecisionValidationIssue[]): PlannerPlanInvocation | undefined;

package/dist/src/runtime/steps/planner-decision/plan-parser.js

@@ -0,0 +1,178 @@
+import { ROLE_CALL_PLAN_ITEM_TITLE_MAX_LENGTH, composeRoleCallPlanChildObjective, } from "../../orchestration/role-calls/index.js";
+import { PLANNER_OBJECTIVE_MAX_LENGTH, } from "./contracts.js";
+export function parsePlannerPlanInvocation(record, planContext, issues) {
+    if (planContext.mode === "declare") {
+        return parseDeclaration(record, planContext.maxItems, issues);
+    }
+    if (planContext.mode === "extend") {
+        return parseExtension(record, planContext.maxItems, issues);
+    }
+    const selectedItems = parseSelectedPlanItems(record.planItemIds, planContext.pendingItems);
+    const objective = selectedItems
+        ? composeRoleCallPlanChildObjective(selectedItems, PLANNER_OBJECTIVE_MAX_LENGTH)
+        : undefined;
+    if (!selectedItems || !objective) {
+        issues.push(issue("planner_plan_item_unavailable", "decision.planItemIds"));
+        return undefined;
+    }
+    return {
+        objective,
+        plannerPlan: Object.freeze({
+            mode: "select",
+            itemIds: Object.freeze(selectedItems.map((item) => item.itemId)),
+        }),
+    };
+}
+function parseDeclaration(record, maxItems, issues) {
+    const plan = asRecord(record.plan);
+    if (!plan) {
+        issues.push(issue("planner_plan_invalid", "decision.plan"));
+        return undefined;
+    }
+    exactKeys(plan, ["summary", "items"], issues, "decision.plan");
+    validateBoundedText(plan.summary, PLANNER_OBJECTIVE_MAX_LENGTH, "planner_plan_summary_invalid", "decision.plan.summary", issues);
+    const items = parseItems(plan.items, maxItems, "decision.plan.items", issues);
+    const selectedItemIndexes = items
+        ? parseSelectedItemIndexes(record.selectedItemIndexes, items.length)
+        : undefined;
+    const selectedItems = items && selectedItemIndexes
+        ? selectedItemIndexes.map((index) => items[index])
+        : undefined;
+    const objective = selectedItems
+        ? composeRoleCallPlanChildObjective(selectedItems, PLANNER_OBJECTIVE_MAX_LENGTH)
+        : undefined;
+    if (issues.length > 0 ||
+        typeof plan.summary !== "string" ||
+        !items ||
+        !selectedItemIndexes ||
+        !objective) {
+        if (!selectedItemIndexes || !objective) {
+            issues.push(issue("planner_plan_item_unavailable", "decision.selectedItemIndexes"));
+        }
+        return undefined;
+    }
+    return {
+        objective,
+        plannerPlan: Object.freeze({
+            mode: "declare",
+            plan: Object.freeze({
+                summary: plan.summary.trim(),
+                items,
+            }),
+            selectedItemIndexes,
+        }),
+    };
+}
+function parseExtension(record, maxItems, issues) {
+    const extension = asRecord(record.extension);
+    if (!extension) {
+        issues.push(issue("planner_plan_extension_invalid", "decision.extension"));
+        return undefined;
+    }
+    exactKeys(extension, ["items"], issues, "decision.extension");
+    const items = parseItems(extension.items, maxItems, "decision.extension.items", issues);
+    const selectedItemIndexes = items
+        ? parseSelectedItemIndexes(record.selectedItemIndexes, items.length)
+        : undefined;
+    const selectedItems = items && selectedItemIndexes
+        ? selectedItemIndexes.map((index) => items[index])
+        : undefined;
+    const objective = selectedItems
+        ? composeRoleCallPlanChildObjective(selectedItems, PLANNER_OBJECTIVE_MAX_LENGTH)
+        : undefined;
+    if (issues.length > 0 || !items || !selectedItemIndexes || !objective) {
+        if (!selectedItemIndexes || !objective) {
+            issues.push(issue("planner_plan_item_unavailable", "decision.selectedItemIndexes"));
+        }
+        return undefined;
+    }
+    return {
+        objective,
+        plannerPlan: Object.freeze({
+            mode: "extend",
+            extension: Object.freeze({ items }),
+            selectedItemIndexes,
+        }),
+    };
+}
+function parseSelectedItemIndexes(input, itemCount) {
+    if (!Array.isArray(input) ||
+        input.length === 0 ||
+        input.some((value) => !Number.isSafeInteger(value) || value < 0 || value >= itemCount) ||
+        new Set(input).size !== input.length) {
+        return undefined;
+    }
+    const selected = new Set(input);
+    return Object.freeze(Array.from({ length: itemCount }, (_value, index) => index).filter((index) => selected.has(index)));
+}
+function parseSelectedPlanItems(input, items) {
+    if (!Array.isArray(input) ||
+        input.length === 0 ||
+        input.some((value) => typeof value !== "string") ||
+        new Set(input).size !== input.length) {
+        return undefined;
+    }
+    const selected = new Set(input);
+    const result = items.filter((item) => selected.has(item.itemId));
+    return result.length === selected.size ? Object.freeze(result) : undefined;
+}
+function parseItems(value, maxItems, pathPrefix, issues) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > maxItems) {
+        issues.push(issue("planner_plan_items_invalid", pathPrefix));
+        return undefined;
+    }
+    const items = [];
+    for (const [index, valueItem] of value.entries()) {
+        const item = asRecord(valueItem);
+        const path = `${pathPrefix}.${index}`;
+        if (!item) {
+            issues.push(issue("planner_plan_item_invalid", path));
+            continue;
+        }
+        exactKeys(item, ["title", "objective"], issues, path);
+        validateBoundedText(item.title, ROLE_CALL_PLAN_ITEM_TITLE_MAX_LENGTH, "planner_plan_item_title_invalid", `${path}.title`, issues);
+        validateBoundedText(item.objective, PLANNER_OBJECTIVE_MAX_LENGTH, "planner_objective_invalid", `${path}.objective`, issues);
+        if (typeof item.title === "string" &&
+            item.title.trim().length > 0 &&
+            item.title.length <= ROLE_CALL_PLAN_ITEM_TITLE_MAX_LENGTH &&
+            typeof item.objective === "string" &&
+            item.objective.trim().length > 0 &&
+            item.objective.length <= PLANNER_OBJECTIVE_MAX_LENGTH) {
+            items.push({
+                title: item.title.trim(),
+                objective: item.objective.trim(),
+            });
+        }
+    }
+    return items.length === value.length
+        ? Object.freeze(items.map((item) => Object.freeze(item)))
+        : undefined;
+}
+function exactKeys(record, expectedKeys, issues, path) {
+    const expected = new Set(expectedKeys);
+    const actual = Object.keys(record);
+    if (actual.length !== expected.size ||
+        actual.some((key) => !expected.has(key))) {
+        issues.push(issue("planner_decision_shape_invalid", path));
+    }
+}
+function validateBoundedText(value, maximumLength, code, path, issues) {
+    const normalized = typeof value === "string" ? value.trim() : "";
+    if (typeof value !== "string" ||
+        normalized.length === 0 ||
+        value.length > maximumLength) {
+        issues.push(issue(code, path));
+    }
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function issue(code, path) {
+    return {
+        code,
+        path,
+        message: `Planner decision failed ${code}.`,
+    };
+}

package/dist/src/runtime/steps/planner-decision/plan.d.ts

@@ -0,0 +1,8 @@
+import { type RoleCallFrame, type RoleCallLedger } from "../../orchestration/role-calls/index.js";
+import type { PlannerDecisionPlanContext } from "./contracts.js";
+export declare function normalizePlannerDecisionPlanContext(input: PlannerDecisionPlanContext): PlannerDecisionPlanContext;
+export declare function plannerPlanAllowsInvocation(context: PlannerDecisionPlanContext | undefined): boolean;
+export declare function projectPlannerDecisionPlanContext(params: Readonly<{
+    ledger: RoleCallLedger;
+    call: RoleCallFrame;
+}>): PlannerDecisionPlanContext;

package/dist/src/runtime/steps/planner-decision/plan.js

@@ -0,0 +1,125 @@
+import { ROLE_CALL_OBJECTIVE_MAX_LENGTH, ROLE_CALL_PLAN_ITEM_TITLE_MAX_LENGTH, } from "../../orchestration/role-calls/index.js";
+export function normalizePlannerDecisionPlanContext(input) {
+    if (input.mode === "declare" &&
+        Number.isSafeInteger(input.maxItems) &&
+        input.maxItems >= 0) {
+        return Object.freeze({ mode: "declare", maxItems: input.maxItems });
+    }
+    if (input.mode === "extend" &&
+        /^plan-call-[1-9][0-9]*$/u.test(input.planId) &&
+        isBoundedText(input.summary, ROLE_CALL_OBJECTIVE_MAX_LENGTH) &&
+        Number.isSafeInteger(input.existingItemCount) &&
+        input.existingItemCount >= 1 &&
+        Number.isSafeInteger(input.maxItems) &&
+        input.maxItems >= 0) {
+        return Object.freeze({
+            mode: "extend",
+            planId: input.planId,
+            summary: input.summary.trim(),
+            existingItemCount: input.existingItemCount,
+            maxItems: input.maxItems,
+        });
+    }
+    if (input.mode !== "select" ||
+        !/^plan-call-[1-9][0-9]*$/u.test(input.planId) ||
+        !isBoundedText(input.summary, ROLE_CALL_OBJECTIVE_MAX_LENGTH) ||
+        typeof input.childInvocationAvailable !== "boolean" ||
+        !Array.isArray(input.pendingItems)) {
+        throw new Error("planner_plan_context_invalid");
+    }
+    const itemIds = new Set();
+    const pendingItems = input.pendingItems.map((item) => {
+        if (!new RegExp(`^${input.planId}-item-[1-9][0-9]*$`, "u").test(item.itemId) ||
+            itemIds.has(item.itemId) ||
+            !isBoundedText(item.title, ROLE_CALL_PLAN_ITEM_TITLE_MAX_LENGTH) ||
+            !isBoundedText(item.objective, ROLE_CALL_OBJECTIVE_MAX_LENGTH)) {
+            throw new Error("planner_plan_context_invalid");
+        }
+        itemIds.add(item.itemId);
+        return Object.freeze({
+            itemId: item.itemId,
+            title: item.title.trim(),
+            objective: item.objective.trim(),
+        });
+    });
+    return Object.freeze({
+        mode: "select",
+        planId: input.planId,
+        summary: input.summary.trim(),
+        childInvocationAvailable: input.childInvocationAvailable,
+        pendingItems: Object.freeze(pendingItems),
+    });
+}
+export function plannerPlanAllowsInvocation(context) {
+    if (!context)
+        return true;
+    if (context.mode === "declare" || context.mode === "extend") {
+        return context.maxItems > 0;
+    }
+    return context.childInvocationAvailable && context.pendingItems.length > 0;
+}
+export function projectPlannerDecisionPlanContext(params) {
+    const head = params.ledger.current();
+    const canonicalCall = head.state.calls.find((candidate) => candidate.callId === params.call.callId);
+    if (head.state.phase !== "running" ||
+        head.state.activeCallId !== params.call.callId ||
+        canonicalCall !== params.call ||
+        params.call.roleId !== "planner") {
+        throw new Error("planner_plan_context_source_invalid");
+    }
+    const plan = head.state.plans.find((candidate) => candidate.definition.plannerCallId === params.call.callId);
+    if (!plan) {
+        if (params.call.childCallIds.length > 0) {
+            throw new Error("planner_plan_context_missing");
+        }
+        return Object.freeze({
+            mode: "declare",
+            maxItems: Math.max(0, params.call.depth >= head.policy.limits.maxDepth
+                ? 0
+                : head.policy.limits.maxCalls - head.state.calls.length),
+        });
+    }
+    const stateByItemId = new Map(plan.itemStates.map((item) => [item.itemId, item]));
+    const pendingItems = plan.definition.items.flatMap((item) => {
+        const state = stateByItemId.get(item.itemId);
+        if (!state) {
+            throw new Error("planner_plan_context_source_invalid");
+        }
+        return state.status === "pending"
+            ? [
+                Object.freeze({
+                    itemId: item.itemId,
+                    title: item.title,
+                    objective: item.objective,
+                }),
+            ]
+            : [];
+    });
+    if (plan.itemStates.some((item) => item.status === "in_progress")) {
+        throw new Error("planner_plan_context_source_invalid");
+    }
+    const remainingItemCapacity = Math.max(0, params.call.depth >= head.policy.limits.maxDepth
+        ? 0
+        : head.policy.limits.maxCalls - head.state.calls.length);
+    if (pendingItems.length === 0) {
+        return Object.freeze({
+            mode: "extend",
+            planId: plan.definition.planId,
+            summary: plan.definition.summary,
+            existingItemCount: plan.definition.items.length,
+            maxItems: remainingItemCapacity,
+        });
+    }
+    return Object.freeze({
+        mode: "select",
+        planId: plan.definition.planId,
+        summary: plan.definition.summary,
+        childInvocationAvailable: remainingItemCapacity > 0,
+        pendingItems: Object.freeze(pendingItems),
+    });
+}
+function isBoundedText(value, maximumLength) {
+    return (typeof value === "string" &&
+        value.trim().length > 0 &&
+        value.length <= maximumLength);
+}

package/dist/src/runtime/steps/planner-decision/prompt.d.ts

@@ -0,0 +1,10 @@
+import { type PlannerDecisionPlanContext } from "./contracts.js";
+export declare function buildPlannerDecisionInstructions(options?: Readonly<{
+    childRolesAvailable?: boolean;
+    hasCompletedChildResults?: boolean;
+    hasDependencyResults?: boolean;
+    workerRoleAvailable?: boolean;
+    workerWorkingDirectoryInherited?: boolean;
+    workerCapabilityCatalogAvailable?: boolean;
+    planContext?: PlannerDecisionPlanContext;
+}>): string;