@praxis-ai/praxis 0.1.0 → 0.1.2

package/dist/executionEngine/coreLogic/mainLoop.d.ts

@@ -0,0 +1,1015 @@
+import { type AgentExecutionStateGate, type AgentExecutionStateSnapshot, type AgentExecutionStateTrace } from "./stateEngine.js";
+import type { ModelDecision } from "./modelDecision.js";
+import { type PromptPackCachePlan, type PromptPackCacheTelemetry, type StandardPromptPack } from "../promptPack/promptAssembler.js";
+import { type PromptPackMaterialDraft } from "../promptPack/promptDefiner.js";
+export type AgentMainLoopNextHop = "prompt-pack" | "model-adapter" | "tool-layer" | "event-exposure" | "none";
+export type MainLoopTickKind = "model-only" | "tool-call" | "ephemeral-procedure" | "approval-wait" | "resume" | "interrupt" | "failure";
+export type MainLoopTimelineRefKind = "run" | "userTurn" | "loopTick" | "step" | "checkpoint";
+export type MainLoopTimelineRef = {
+    kind: MainLoopTimelineRefKind;
+    sessionId: string;
+    userTurnIndex?: number;
+    loopTickIndex?: number;
+    stepIndex?: number;
+    checkpointId?: string;
+    ref: string;
+};
+export type MainLoopCheckpointKind = "sessionStart" | "approvalWait" | "failedStep" | "observationIntegrated" | "manual" | "finalized";
+export type MainLoopCheckpoint = {
+    checkpointId: string;
+    kind: MainLoopCheckpointKind;
+    sessionId: string;
+    userTurnIndex: number;
+    loopTickIndex: number;
+    stepIndex?: number;
+    stateRef?: string;
+    promptPackRef?: string;
+    loweredPromptRef?: string;
+    observationRefs: readonly string[];
+    createdAt: string;
+    timelineRef: MainLoopTimelineRef;
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type MainLoopStep = {
+    timelineRef: MainLoopTimelineRef;
+    record: MainLoopStepRecord;
+};
+export type LoopTickStatus = "planned" | "running" | "waitingApproval" | "completed" | "failed" | "interrupted";
+export type LoopTick = {
+    tickId: string;
+    sessionId: string;
+    userTurnIndex: number;
+    loopTickIndex: number;
+    kind: MainLoopTickKind;
+    status: LoopTickStatus;
+    steps: readonly MainLoopStep[];
+    checkpoints: readonly MainLoopCheckpoint[];
+    promptPackRef?: string;
+    loweredPromptRef?: string;
+    selectedModel?: string;
+    cacheHealth?: Readonly<Record<string, unknown>>;
+    budgetSnapshot?: Readonly<Record<string, unknown>>;
+    stateRefs: readonly string[];
+    observationRefs: readonly string[];
+    timelineRef: MainLoopTimelineRef;
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type UserTurnStatus = "open" | "running" | "waitingApproval" | "completed" | "failed" | "interrupted";
+export type UserTurn = {
+    userTurnId: string;
+    sessionId: string;
+    userTurnIndex: number;
+    status: UserTurnStatus;
+    inputRefs: readonly string[];
+    outputRefs: readonly string[];
+    ticks: readonly LoopTick[];
+    checkpoints: readonly MainLoopCheckpoint[];
+    startedAt: string;
+    completedAt?: string;
+    timelineRef: MainLoopTimelineRef;
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type MainLoopRunStatus = "created" | "running" | "waitingApproval" | "completed" | "failed" | "interrupted";
+export type MainLoopRun = {
+    runId: string;
+    sessionId: string;
+    status: MainLoopRunStatus;
+    userTurns: readonly UserTurn[];
+    checkpoints: readonly MainLoopCheckpoint[];
+    createdAt: string;
+    updatedAt: string;
+    timelineRef: MainLoopTimelineRef;
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type MainLoopSessionTimeline = {
+    sessionId: string;
+    run: MainLoopRun;
+    timelineRefs: readonly MainLoopTimelineRef[];
+    checkpoints: readonly MainLoopCheckpoint[];
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type MainLoopRuntimeSurfaceRef = {
+    surfaceId: string;
+    kind: "modelAdapter" | "baseToolExecutor" | "stateEventStore" | "promptPack" | "interfaceAdapter" | "sandbox" | "storage" | "governance" | "inspection" | (string & {});
+    ready: boolean;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type MainLoopRuntimeContext = {
+    runtimeId: string;
+    sessionId: string;
+    manifestRef?: string;
+    callerRef?: string;
+    surfaces: readonly MainLoopRuntimeSurfaceRef[];
+    now?: () => string;
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type RunMainLoopRequest = {
+    runtime: MainLoopRuntimeContext;
+    input: unknown;
+    userTurnIndex?: number;
+    loopTickIndex?: number;
+    startStepIndex?: number;
+    inputRefs?: readonly string[];
+    targetModel?: string;
+    loweringHint?: string;
+    promptPackId?: string;
+    materials?: readonly PromptPackMaterialDraft[];
+    maxLoopTicks?: number;
+    trace?: AgentExecutionStateTrace;
+    contract?: AgentExecutionStateGate;
+    governance?: AgentExecutionStateGate;
+};
+export type RunMainLoopResult = {
+    ok: true;
+    run: MainLoopRun;
+    timeline: MainLoopSessionTimeline;
+    userTurn: UserTurn;
+    loopTicks: readonly LoopTick[];
+    stepRecords: readonly MainLoopStepRecord[];
+    turnPreparation?: Extract<MainLoopTurnPreparationResult, {
+        ok: true;
+    }>;
+    events: readonly string[];
+    dryRun: true;
+    unsafeSideEffects: false;
+} | {
+    ok: false;
+    error: AgentMainLoopError;
+    events: readonly string[];
+    dryRun: true;
+    unsafeSideEffects: false;
+};
+export type MainLoopRunnerBoundary = "prompt" | "model" | "model-decision" | "approval" | "tool" | "procedure" | "output";
+export type MainLoopRunnerError = {
+    code: string;
+    message: string;
+    boundary: MainLoopRunnerBoundary;
+    publicSafe: true;
+};
+export type MainLoopRunnerTurnPackage<TPrompt> = {
+    prompt: TPrompt;
+    events: readonly string[];
+};
+export type MainLoopRunnerUsageReport = {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    estimatedCostUsd?: number;
+    providerRaw?: unknown;
+};
+export type MainLoopRunnerModelResult<TRaw> = {
+    ok: true;
+    modelCallId: string;
+    raw: TRaw | null;
+    usage?: MainLoopRunnerUsageReport;
+    events: readonly string[];
+} | {
+    ok: false;
+    modelCallId: string;
+    error: MainLoopRunnerError;
+    events: readonly string[];
+};
+export type MainLoopRunnerDecisionResult = {
+    ok: true;
+    decisions: readonly ModelDecision[];
+    events: readonly string[];
+} | {
+    ok: false;
+    error: MainLoopRunnerError;
+    events: readonly string[];
+};
+export type MainLoopRunnerActionResult = {
+    ok: true;
+    continueLoop: boolean;
+    events: readonly string[];
+} | {
+    ok: false;
+    error: MainLoopRunnerError;
+    events: readonly string[];
+};
+export type MainLoopRunnerFinalResult = {
+    ok: true;
+    finalOutput: string;
+    events: readonly string[];
+} | {
+    ok: false;
+    error: MainLoopRunnerError;
+    events: readonly string[];
+};
+export type MainLoopRunnerNoFinalReason = "model_turn_limit" | "tool_call_limit" | "no_continuation";
+export type MainLoopRunnerNoFinalContext = {
+    reason: MainLoopRunnerNoFinalReason;
+    modelTurns: number;
+    toolCalls: number;
+    turnToolCalls: number;
+    maxModelTurns: number;
+    maxToolCalls: number;
+};
+export type MainLoopRunnerRequest<TPrompt, TRaw> = {
+    maxModelTurns: number;
+    /** Maximum tool calls accepted inside one model turn. */
+    maxToolCalls: number;
+    prepareTurn: (turnIndex: number) => Promise<MainLoopRunnerTurnPackage<TPrompt> | {
+        ok: false;
+        error: MainLoopRunnerError;
+        events: readonly string[];
+    }>;
+    invokeModel: (turnIndex: number, prompt: TPrompt) => Promise<MainLoopRunnerModelResult<TRaw>>;
+    interpretDecision: (turnIndex: number, model: Extract<MainLoopRunnerModelResult<TRaw>, {
+        ok: true;
+    }>, prompt: TPrompt) => Promise<MainLoopRunnerDecisionResult>;
+    acceptFinalOutput: (input: {
+        turnIndex: number;
+        decisionIndex: number;
+        decision: ModelDecision;
+        prompt: TPrompt;
+    }) => Promise<MainLoopRunnerFinalResult>;
+    handleContinue: (input: {
+        turnIndex: number;
+        decisionIndex: number;
+        decision: ModelDecision;
+        prompt: TPrompt;
+    }) => Promise<MainLoopRunnerActionResult>;
+    handleFailure: (input: {
+        turnIndex: number;
+        decisionIndex: number;
+        decision: ModelDecision;
+        prompt: TPrompt;
+    }) => Promise<MainLoopRunnerActionResult>;
+    handleApproval: (input: {
+        turnIndex: number;
+        decisionIndex: number;
+        decision: ModelDecision;
+        prompt: TPrompt;
+    }) => Promise<MainLoopRunnerActionResult>;
+    handleToolCall: (input: {
+        turnIndex: number;
+        decisionIndex: number;
+        decision: ModelDecision;
+        prompt: TPrompt;
+    }) => Promise<MainLoopRunnerActionResult>;
+    handleEphemeralProcedure: (input: {
+        turnIndex: number;
+        decisionIndex: number;
+        decision: ModelDecision;
+        prompt: TPrompt;
+    }) => Promise<MainLoopRunnerActionResult>;
+    onModelDryRun?: (input: {
+        turnIndex: number;
+        prompt: TPrompt;
+        model: Extract<MainLoopRunnerModelResult<TRaw>, {
+            ok: true;
+        }>;
+    }) => Promise<MainLoopRunnerFinalResult>;
+    onNoFinalOutput?: (input: MainLoopRunnerNoFinalContext) => Promise<MainLoopRunnerFinalResult>;
+};
+export type MainLoopRunnerResult = {
+    ok: true;
+    finalOutput: string;
+    modelTurns: number;
+    toolCalls: number;
+    events: readonly string[];
+} | {
+    ok: false;
+    error: MainLoopRunnerError;
+    modelTurns: number;
+    toolCalls: number;
+    events: readonly string[];
+};
+export type MainLoopActionPrimitive = "receiveInput" | "prepareTurn" | "sandboxPrepare" | "advanceState" | "planMainLoopTick" | "assemblePromptPack" | "buildCachePlan" | "handoffPromptPack" | "lowerPrompt" | "handoffModelInvocation" | "invokeModel" | "interpretModelDecision" | "adjudicateDecision" | "handoffModelDecision" | "handoffToolCall" | "invokeBaseTool" | "handoffEphemeralProcedure" | "executeEphemeralProcedure" | "integrateObservation" | "requestApproval" | "waitApproval" | "resume" | "interrupt" | "retry" | "timeout" | "emitEvent" | "recordSessionEvent" | "updateSummaryStateEvent" | "decideContinueBreak" | "requestTapCapability" | "exposeOutput" | "fail";
+export declare const MAIN_LOOP_ACTION_PRIMITIVES: readonly ["receiveInput", "prepareTurn", "sandboxPrepare", "advanceState", "planMainLoopTick", "assemblePromptPack", "buildCachePlan", "handoffPromptPack", "lowerPrompt", "handoffModelInvocation", "invokeModel", "interpretModelDecision", "adjudicateDecision", "handoffModelDecision", "handoffToolCall", "invokeBaseTool", "handoffEphemeralProcedure", "executeEphemeralProcedure", "integrateObservation", "requestApproval", "waitApproval", "resume", "interrupt", "retry", "timeout", "emitEvent", "recordSessionEvent", "updateSummaryStateEvent", "decideContinueBreak", "requestTapCapability", "exposeOutput", "fail"];
+export type MainLoopStepStatus = "planned" | "running" | "completed" | "failed" | "interrupted" | "waitingApproval";
+export type MainLoopStepGateResult = {
+    accepted: boolean;
+    reason?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type MainLoopPublicSafeFailure = {
+    code: string;
+    message: string;
+    boundary: "input" | "runtime-state" | "contract" | "governance" | "prompt" | "model" | "tool" | "procedure" | "output";
+    publicSafe: true;
+};
+export type MainLoopStepTrace = AgentExecutionStateTrace & {
+    traceId?: string;
+};
+export type MainLoopStepRecord = {
+    stepId: string;
+    sessionId: string;
+    turnIndex: number;
+    stepIndex: number;
+    actionPrimitive: MainLoopActionPrimitive;
+    status: MainLoopStepStatus;
+    inputRefs: readonly string[];
+    outputRefs: readonly string[];
+    modelCallId?: string;
+    toolCallId?: string;
+    procedureId?: string;
+    stateBeforeRef?: string;
+    stateAfterRef?: string;
+    promptPackRef?: string;
+    loweredPromptRef?: string;
+    observationRefs: readonly string[];
+    governance: MainLoopStepGateResult;
+    contract: MainLoopStepGateResult;
+    error?: MainLoopPublicSafeFailure;
+    timestamps: {
+        plannedAt: string;
+        startedAt?: string;
+        completedAt?: string;
+        failedAt?: string;
+        interruptedAt?: string;
+        waitingApprovalAt?: string;
+    };
+    trace: MainLoopStepTrace;
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type AgentMainLoopBoundary = "input" | "runtime-state" | "contract" | "governance";
+export type AgentMainLoopRequest = {
+    sessionId?: string;
+    input?: unknown;
+    now?: string;
+    currentState?: AgentExecutionStateSnapshot;
+    requestedNextHop?: AgentMainLoopNextHop;
+    maxSteps?: number;
+    trace?: AgentExecutionStateTrace;
+    contract?: AgentExecutionStateGate;
+    governance?: AgentExecutionStateGate;
+};
+export type AgentMainLoopErrorCode = "MISSING_SESSION_ID" | "MISSING_INPUT" | "LOOP_LIMIT_EXCEEDED" | "STATE_REJECTED" | "CONTRACT_REJECTED" | "GOVERNANCE_REJECTED";
+export type AgentMainLoopError = {
+    code: AgentMainLoopErrorCode;
+    message: string;
+    boundary: AgentMainLoopBoundary;
+    stateSafe: true;
+};
+export type AgentMainLoopTick = {
+    sessionId: string;
+    input: unknown;
+    state: AgentExecutionStateSnapshot;
+    nextHop: AgentMainLoopNextHop;
+    plannedSteps: readonly string[];
+    stepRecords: readonly MainLoopStepRecord[];
+    dryRun: true;
+    unsafeSideEffects: false;
+};
+export type AgentMainLoopResult = {
+    ok: true;
+    tick: AgentMainLoopTick;
+    events: readonly string[];
+} | {
+    ok: false;
+    error: AgentMainLoopError;
+    events: readonly string[];
+};
+export type FrameworkMainLoopHandoffRequest = {
+    sessionId?: string;
+    turnIndex?: number;
+    startStepIndex?: number;
+    now?: string;
+    tickKind: MainLoopTickKind;
+    promptPackRef?: string;
+    loweredPromptRef?: string;
+    modelCallId?: string;
+    toolCallId?: string;
+    procedureId?: string;
+    observationRefs?: readonly string[];
+    stateBeforeRef?: string;
+    stateAfterRef?: string;
+    inputRefs?: readonly string[];
+    outputRefs?: readonly string[];
+    error?: MainLoopPublicSafeFailure;
+    trace?: MainLoopStepTrace;
+    governance?: MainLoopStepGateResult;
+    contract?: MainLoopStepGateResult;
+};
+export type FrameworkMainLoopHandoffPlan = {
+    kind: "praxis.mainLoopHandoffPlan";
+    sessionId: string;
+    tickKind: MainLoopTickKind;
+    stepRecords: readonly MainLoopStepRecord[];
+    nextAction?: MainLoopActionPrimitive;
+    eventRefs: readonly string[];
+    dryRun: true;
+    unsafeSideEffects: false;
+};
+export type FrameworkMainLoopHandoffResult = {
+    ok: true;
+    plan: FrameworkMainLoopHandoffPlan;
+    events: readonly string[];
+} | {
+    ok: false;
+    error: AgentMainLoopError;
+    events: readonly string[];
+};
+export type RuntimeAdjudicationKind = "allowed" | "requiresApproval" | "blockedByPolicy" | "blockedBySandbox" | "resourceExceeded" | "invalidDecision" | "finalAllowed" | "continueAllowed";
+export type RuntimeAdjudication = {
+    kind: RuntimeAdjudicationKind;
+    accepted: boolean;
+    decisionId?: string;
+    reason: string;
+    requestedScopes: readonly string[];
+    riskLevel?: "safe" | "risky" | "dangerous" | (string & {});
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopContinuationDecisionKind = "continue" | "break" | "waitApproval" | "interrupt" | "fail";
+export type MainLoopContinuationDecision = {
+    kind: MainLoopContinuationDecisionKind;
+    accepted: boolean;
+    reason: string;
+    source: "model" | "developerStrategy" | "runtimeFallback";
+    nextAction?: MainLoopActionPrimitive;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopBreakDecisionKind = "finalAccepted" | "pendingApproval" | "unresolvedProcedure" | "fatalFailure" | "stateBlocked" | "budgetBlocked" | "runtimeRejected";
+export type MainLoopBreakDecision = {
+    kind: MainLoopBreakDecisionKind;
+    canBreak: boolean;
+    reason: string;
+    finalOutput?: string;
+    blockingRefs: readonly string[];
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopBehaviorRefDecision = {
+    behaviorRef: string;
+    priority: number;
+    decision: MainLoopContinuationDecision;
+    conflicts: readonly string[];
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type MainLoopFinalAcceptanceRequest = {
+    finalOutput?: string;
+    pendingApprovalRefs?: readonly string[];
+    unresolvedProcedureRefs?: readonly string[];
+    fatalFailureRefs?: readonly string[];
+    unrecordedEventRefs?: readonly string[];
+    budget?: MainLoopStepGateResult;
+    statePlane?: MainLoopStepGateResult;
+    runtime?: MainLoopStepGateResult;
+};
+export type MainLoopBudgetSpec = {
+    maxToolCallsPerLoopTick: number;
+    maxToolCallsPerEphemeralProcedure: number;
+    maxModelTurns: number;
+    maxWallTimeMs: number;
+    maxTokens?: number;
+    maxCost?: number;
+    maxShellSeconds: number;
+    maxFileWrites?: number;
+    maxNetworkCalls?: number;
+};
+export type RuntimeBudgetSpec = MainLoopBudgetSpec & {
+    budgetId: string;
+    source: "default" | "developer" | "runtime";
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type MainLoopBudgetExhaustionAction = "fail" | "partialFinal" | "requestApproval" | "summarizeCurrentState" | "writeResumeCheckpoint";
+export type MainLoopBudgetExhaustionDecision = {
+    action: MainLoopBudgetExhaustionAction;
+    reason: string;
+    checkpoint?: MainLoopCheckpoint;
+    approval?: MainLoopApprovalEnvelope;
+    nextAction: MainLoopActionPrimitive;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopRetryPolicy = {
+    maxAttempts: number;
+    retryTarget: "model" | "sameTool" | "procedure";
+    retryableBoundaries: readonly MainLoopPublicSafeFailure["boundary"][];
+};
+export type MainLoopFallbackPolicy = {
+    enabled: boolean;
+    fallbackTargets: readonly ("alternateTool" | "alternateProcedure" | "modelReplan" | "userIntervention")[];
+};
+export type MainLoopFailureRecoveryPolicy = {
+    retry: MainLoopRetryPolicy;
+    fallback: MainLoopFallbackPolicy;
+    finalActions: readonly ("fail" | "interruptUser" | "runtimeFallback" | "modelAnalyze")[];
+};
+export type MainLoopFailureRecoveryDecision = {
+    kind: "retry" | "fallback" | "fail" | "interruptUser";
+    attempt: number;
+    reason: string;
+    nextAction?: MainLoopActionPrimitive;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopModelCapabilityRole = "reasoning" | "image-generation" | "background" | "batch" | "realtime" | "text" | (string & {});
+export type MainLoopModelCandidate = {
+    modelRef: string;
+    capabilityRoles: readonly MainLoopModelCapabilityRole[];
+    available: boolean;
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type MainLoopModelSelectionRequest = {
+    defaultModelRef?: string;
+    userModelRef?: string;
+    chooseModelRef?: string;
+    requiredCapability?: MainLoopModelCapabilityRole;
+    candidates?: readonly MainLoopModelCandidate[];
+};
+export type MainLoopModelSelectionDecision = {
+    selectedModelRef: string;
+    source: "user" | "chooseModelRef" | "capabilityFallback" | "default";
+    requiredCapability?: MainLoopModelCapabilityRole;
+    reason: string;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopStateExposure = {
+    phase: MainLoopRunStatus | UserTurnStatus | LoopTickStatus;
+    currentTurn?: number;
+    currentTick?: number;
+    currentStep?: number;
+    pendingApprovals: readonly string[];
+    activeToolCalls: readonly string[];
+    lastObservation?: string;
+    lastError?: string;
+    budgets?: RuntimeBudgetSpec;
+    cacheHealth?: Readonly<Record<string, unknown>>;
+    selectedModel?: string;
+    sandboxStatus?: string;
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type MainLoopControlPrimitive = "pause" | "resume" | "interrupt" | "approve" | "deny" | "retry" | "rollback" | "inspect" | "repair" | "configure" | "rotateSecretRef" | "updatePolicy" | "updateBudget";
+export declare const MAIN_LOOP_CONTROL_PRIMITIVES: readonly ["pause", "resume", "interrupt", "approve", "deny", "retry", "rollback", "inspect", "repair", "configure", "rotateSecretRef", "updatePolicy", "updateBudget"];
+export type MainLoopApprovalStatus = "pending" | "approved" | "denied";
+export type MainLoopApprovalEnvelope = {
+    approvalId: string;
+    sessionId: string;
+    status: "pending";
+    reason: string;
+    requestedScopes: readonly string[];
+    riskLevel?: RuntimeAdjudication["riskLevel"];
+    decisionRef?: string;
+    proposedActionRef?: string;
+    surfaceRef?: string;
+    cancelToken?: string;
+    createdAt: string;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopApprovalResolution = {
+    approvalId: string;
+    sessionId: string;
+    status: Exclude<MainLoopApprovalStatus, "pending">;
+    responderRef: string;
+    resolvedAt: string;
+    resumeAction: "resume";
+    nextAction: MainLoopActionPrimitive;
+    noteForModel?: string;
+    canMutateToolInput: false;
+    ignoredParameterPatch?: Readonly<Record<string, unknown>>;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopControlActionRecord = {
+    actionId: string;
+    sessionId: string;
+    primitive: Extract<MainLoopControlPrimitive, "pause" | "resume" | "interrupt">;
+    mainLoopStatus: MainLoopRunStatus | UserTurnStatus | LoopTickStatus;
+    runtimeStatus: "running" | "paused" | "resuming" | "interrupted";
+    reason: string;
+    cancelToken?: string;
+    trace: MainLoopStepTrace;
+    createdAt: string;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopRollbackPoint = {
+    rollbackPointId: string;
+    sessionId: string;
+    checkpoint: MainLoopCheckpoint;
+    timelineRef: MainLoopTimelineRef;
+    executor: "runtime-control-surface";
+    executableByMainLoop: false;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopReplayPlanKind = "step" | "loopTick" | "userTurn";
+export type MainLoopReplayPlan = {
+    replayId: string;
+    kind: MainLoopReplayPlanKind;
+    sessionId: string;
+    sourceTimelineRefs: readonly MainLoopTimelineRef[];
+    stepRecords: readonly MainLoopStepRecord[];
+    promptPackRefs: readonly string[];
+    loweredPromptRefs: readonly string[];
+    observationRefs: readonly string[];
+    providerRawRefs: readonly string[];
+    dryRun: true;
+    unsafeSideEffects: false;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopBehaviorRefSource = "application" | "raxProject" | "signedPackage" | "futureDsl" | "runtimeBuiltin";
+export type MainLoopBehaviorRef = {
+    behaviorRef: string;
+    primitive: MainLoopActionPrimitive;
+    source: MainLoopBehaviorRefSource;
+    handlerRef: string;
+    priority: number;
+    timeoutMs: number;
+    sandboxRef?: string;
+    resourceRef?: string;
+    conflictsWith: readonly string[];
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type MainLoopBehaviorRegistry = {
+    registryId: string;
+    behaviors: readonly MainLoopBehaviorRef[];
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type MainLoopBehaviorResolution = {
+    ok: true;
+    behavior: MainLoopBehaviorRef;
+    executable: true;
+    executionContract: {
+        handlerRef: string;
+        timeoutMs: number;
+        sandboxRef?: string;
+        resourceRef?: string;
+    };
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+} | {
+    ok: false;
+    behaviorRef: string;
+    code: "UNREGISTERED_BEHAVIOR" | "BEHAVIOR_CONFLICT" | "BEHAVIOR_GOVERNANCE_REJECTED";
+    message: string;
+    conflicts: readonly string[];
+    publicSafe: true;
+};
+export type MainLoopCacheHealth = {
+    stablePrefixHash: string;
+    capabilityHash?: string;
+    sessionSummaryHash?: string;
+    observationHash?: string;
+    providerTelemetry?: PromptPackCacheTelemetry;
+    cacheMissWarnings: readonly string[];
+    dynamicSegmentKinds: readonly string[];
+    capabilityRebuildRequired: boolean;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopToolChoiceMode = "auto" | "none" | "required" | "forceTool" | "forceGroup" | "forceProcedure";
+export type MainLoopToolChoicePolicy = {
+    mode: MainLoopToolChoiceMode;
+    toolId?: string;
+    groupId?: string;
+    procedureId?: string;
+    evidenceRuleRefs: readonly string[];
+    promptPackRuleOnly: boolean;
+    reason: string;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopInputMaterialKind = "text" | "image" | "audio" | "video";
+export type MainLoopInputMaterial = {
+    inputId: string;
+    kind: MainLoopInputMaterialKind;
+    promptMaterial: PromptPackMaterialDraft;
+    observationRef?: string;
+    providerPayloadCreated: false;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopOutputEnvelopeKind = "text" | "structured" | "artifactRef" | "multimodal" | "streamChunk" | "traceSummary";
+export type MainLoopOutputEnvelope = {
+    outputId: string;
+    kind: MainLoopOutputEnvelopeKind;
+    sessionId: string;
+    payload: unknown;
+    recordPolicy: "afterChunkCompleted" | "immediate";
+    traceSummary?: string;
+    artifactRefs: readonly string[];
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopAgentInterfacePrimitive = {
+    primitiveId: string;
+    sessionId: string;
+    kind: "agentInterfaceHandoff";
+    targetAgentRef?: string;
+    interfaceRef: string;
+    directInvokeAgent: false;
+    multiagentManaged: false;
+    payloadRef?: string;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopStateProgressionAction = "receiveInput" | "modelInvoked" | "toolRunning" | "approvalPending" | "observationIntegrated" | "finalOutput" | "failure" | "interrupt" | "resume";
+export type MainLoopStateProgressionRecord = {
+    action: MainLoopStateProgressionAction;
+    stateBeforeRef?: string;
+    stateAfterRef: string;
+    stepRef?: string;
+    eventRef: string;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export type MainLoopPromptPackRebuildTrigger = "newUserInput" | "observationMaterialChange" | "memoryContextChange" | "capabilitySetChange" | "modelFamilySwitch" | "compressionSummaryCompletion" | "behaviorRefRequest";
+export type MainLoopPromptPackRebuildDecision = {
+    rebuild: boolean;
+    triggers: readonly MainLoopPromptPackRebuildTrigger[];
+    reason: string;
+    cacheFriendly: boolean;
+    metadata: Readonly<Record<string, unknown>>;
+    publicSafe: true;
+};
+export declare const DEFAULT_MAIN_LOOP_BUDGET: MainLoopBudgetSpec;
+export declare const DEFAULT_MAIN_LOOP_FAILURE_RECOVERY_POLICY: MainLoopFailureRecoveryPolicy;
+export type RuntimeAdjudicationRequest = {
+    decision?: ModelDecision;
+    policy?: MainLoopStepGateResult;
+    sandbox?: MainLoopStepGateResult;
+    resource?: MainLoopStepGateResult;
+    pendingApprovalRefs?: readonly string[];
+    unresolvedProcedureRefs?: readonly string[];
+};
+export type MainLoopTurnPreparationRequest = {
+    runtimeId?: string;
+    sessionId?: string;
+    turnIndex?: number;
+    startStepIndex?: number;
+    promptPackId?: string;
+    targetModel?: string;
+    loweringHint?: string;
+    materials?: readonly PromptPackMaterialDraft[];
+    now?: string;
+};
+export type MainLoopTurnRecord = {
+    turnId: string;
+    sessionId: string;
+    turnIndex: number;
+    lifecycle: "prepared";
+    promptPackRef: string;
+    cachePlanRef: string;
+    segmentKinds: readonly string[];
+    stepRecords: readonly MainLoopStepRecord[];
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type MainLoopTurnPreparationResult = {
+    ok: true;
+    promptPackId: string;
+    promptPack: StandardPromptPack;
+    cachePlan: PromptPackCachePlan;
+    turnRecord: MainLoopTurnRecord;
+    events: readonly string[];
+} | {
+    ok: false;
+    error: MainLoopPublicSafeFailure;
+    events: readonly string[];
+};
+export declare function createMainLoopTimelineRef(input: {
+    kind: MainLoopTimelineRefKind;
+    sessionId: string;
+    userTurnIndex?: number;
+    loopTickIndex?: number;
+    stepIndex?: number;
+    checkpointId?: string;
+}): MainLoopTimelineRef;
+export declare function createMainLoopCheckpoint(input: {
+    kind: MainLoopCheckpointKind;
+    sessionId: string;
+    userTurnIndex?: number;
+    loopTickIndex?: number;
+    stepIndex?: number;
+    stateRef?: string;
+    promptPackRef?: string;
+    loweredPromptRef?: string;
+    observationRefs?: readonly string[];
+    now?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopCheckpoint;
+export declare function createLoopTick(input: {
+    sessionId: string;
+    userTurnIndex?: number;
+    loopTickIndex?: number;
+    kind: MainLoopTickKind;
+    status?: LoopTickStatus;
+    stepRecords?: readonly MainLoopStepRecord[];
+    checkpoints?: readonly MainLoopCheckpoint[];
+    promptPackRef?: string;
+    loweredPromptRef?: string;
+    selectedModel?: string;
+    cacheHealth?: Readonly<Record<string, unknown>>;
+    budgetSnapshot?: Readonly<Record<string, unknown>>;
+    stateRefs?: readonly string[];
+    observationRefs?: readonly string[];
+    metadata?: Readonly<Record<string, unknown>>;
+}): LoopTick;
+export declare function createUserTurn(input: {
+    sessionId: string;
+    userTurnIndex?: number;
+    status?: UserTurnStatus;
+    inputRefs?: readonly string[];
+    outputRefs?: readonly string[];
+    ticks?: readonly LoopTick[];
+    checkpoints?: readonly MainLoopCheckpoint[];
+    startedAt?: string;
+    completedAt?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}): UserTurn;
+export declare function createMainLoopRun(input: {
+    sessionId: string;
+    runId?: string;
+    status?: MainLoopRunStatus;
+    userTurns?: readonly UserTurn[];
+    checkpoints?: readonly MainLoopCheckpoint[];
+    now?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopRun;
+export declare function createMainLoopSessionTimeline(input: {
+    sessionId: string;
+    run?: MainLoopRun;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopSessionTimeline;
+export declare function runMainLoop(request: RunMainLoopRequest): RunMainLoopResult;
+export declare function runMainLoopRunner<TPrompt, TRaw>(request: MainLoopRunnerRequest<TPrompt, TRaw>): Promise<MainLoopRunnerResult>;
+export declare function adjudicateRuntimeDecision(request: RuntimeAdjudicationRequest): RuntimeAdjudication;
+export declare function decideMainLoopFinalAcceptance(request: MainLoopFinalAcceptanceRequest): MainLoopBreakDecision;
+export declare function resolveMainLoopContinuation(input: {
+    modelSuggestion: "continue" | "break";
+    finalAcceptance?: MainLoopBreakDecision;
+    behaviorDecision?: MainLoopBehaviorRefDecision;
+    runtimeFallbackReason?: string;
+}): MainLoopContinuationDecision;
+export declare function resolveMainLoopBudget(input?: {
+    sessionId?: string;
+    budget?: Partial<MainLoopBudgetSpec>;
+    source?: RuntimeBudgetSpec["source"];
+    metadata?: Readonly<Record<string, unknown>>;
+}): RuntimeBudgetSpec;
+export declare function resolveMainLoopBudgetExhaustion(input: {
+    sessionId: string;
+    action?: MainLoopBudgetExhaustionAction;
+    reason?: string;
+    userTurnIndex?: number;
+    loopTickIndex?: number;
+    stepIndex?: number;
+    now?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopBudgetExhaustionDecision;
+export declare function resolveMainLoopFailureRecovery(input: {
+    policy?: Partial<MainLoopFailureRecoveryPolicy>;
+    failure: MainLoopPublicSafeFailure;
+    attempt?: number;
+    fallbackAttempted?: boolean;
+}): MainLoopFailureRecoveryDecision;
+export declare function selectMainLoopModel(request: MainLoopModelSelectionRequest): MainLoopModelSelectionDecision;
+export declare function exposeMainLoopState(input: {
+    run?: MainLoopRun;
+    userTurn?: UserTurn;
+    loopTick?: LoopTick;
+    pendingApprovals?: readonly string[];
+    activeToolCalls?: readonly string[];
+    lastObservation?: string;
+    lastError?: string;
+    budgets?: RuntimeBudgetSpec;
+    cacheHealth?: Readonly<Record<string, unknown>>;
+    selectedModel?: string;
+    sandboxStatus?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopStateExposure;
+export declare function createMainLoopCancelToken(input: {
+    sessionId: string;
+    scope: "approval" | "tool" | "procedure" | "model" | "runtime";
+    targetRef?: string;
+    issuedAt?: string;
+}): string;
+export declare function createMainLoopApprovalEnvelope(input: {
+    sessionId: string;
+    reason: string;
+    requestedScopes?: readonly string[];
+    riskLevel?: RuntimeAdjudication["riskLevel"];
+    decisionRef?: string;
+    proposedActionRef?: string;
+    surfaceRef?: string;
+    cancelToken?: string;
+    now?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopApprovalEnvelope;
+export declare function resolveMainLoopApproval(input: {
+    envelope: MainLoopApprovalEnvelope;
+    decision: "approve" | "deny";
+    responderRef: string;
+    noteForModel?: string;
+    parameterPatch?: Readonly<Record<string, unknown>>;
+    now?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopApprovalResolution;
+export declare function createMainLoopControlAction(input: {
+    sessionId: string;
+    primitive: Extract<MainLoopControlPrimitive, "pause" | "resume" | "interrupt">;
+    reason?: string;
+    cancelToken?: string;
+    trace?: MainLoopStepTrace;
+    now?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopControlActionRecord;
+export declare function createMainLoopRollbackPoint(input: {
+    checkpoint: MainLoopCheckpoint;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopRollbackPoint;
+export declare function analyzeMainLoopCacheHealth(input: {
+    cachePlan: PromptPackCachePlan;
+    previousCapabilityHash?: string;
+    providerTelemetry?: PromptPackCacheTelemetry;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopCacheHealth;
+export declare function resolveMainLoopToolChoice(input?: {
+    mode?: MainLoopToolChoiceMode;
+    toolId?: string;
+    groupId?: string;
+    procedureId?: string;
+    evidenceRuleRefs?: readonly string[];
+    reason?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopToolChoicePolicy;
+export declare function createMainLoopInputMaterial(input: {
+    sessionId: string;
+    inputId: string;
+    kind: MainLoopInputMaterialKind;
+    text?: string;
+    uri?: string;
+    mimeType?: string;
+    observationRef?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopInputMaterial;
+export declare function createMainLoopOutputEnvelope(input: {
+    sessionId: string;
+    outputId?: string;
+    kind: MainLoopOutputEnvelopeKind;
+    payload: unknown;
+    artifactRefs?: readonly string[];
+    traceSummary?: string;
+    streamChunkCompleted?: boolean;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopOutputEnvelope;
+export declare function createMainLoopAgentInterfacePrimitive(input: {
+    sessionId: string;
+    interfaceRef: string;
+    targetAgentRef?: string;
+    payloadRef?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopAgentInterfacePrimitive;
+export declare function createMainLoopStateProgressionRecord(input: {
+    sessionId: string;
+    action: MainLoopStateProgressionAction;
+    stateBeforeRef?: string;
+    stateAfterRef?: string;
+    stepRef?: string;
+    eventRef?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopStateProgressionRecord;
+export declare function decideMainLoopPromptPackRebuild(input?: {
+    triggers?: readonly MainLoopPromptPackRebuildTrigger[];
+    previousPromptPackRef?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopPromptPackRebuildDecision;
+export declare function replayMainLoopStep(step: MainLoopStep): MainLoopReplayPlan;
+export declare function replayMainLoopTick(tick: LoopTick): MainLoopReplayPlan;
+export declare function replayUserTurn(turn: UserTurn): MainLoopReplayPlan;
+export declare function createMainLoopBehaviorRegistry(input?: {
+    registryId?: string;
+    behaviors?: readonly MainLoopBehaviorRef[];
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopBehaviorRegistry;
+export declare function resolveMainLoopBehaviorRef(input: {
+    registry: MainLoopBehaviorRegistry;
+    behaviorRef: string;
+    activeBehaviorRefs?: readonly string[];
+    settingConflictRefs?: readonly string[];
+    governance?: MainLoopStepGateResult;
+}): MainLoopBehaviorResolution;
+export declare function createMainLoopStepRecord(input: {
+    sessionId: string;
+    turnIndex: number;
+    stepIndex: number;
+    actionPrimitive: MainLoopActionPrimitive;
+    status?: MainLoopStepStatus;
+    inputRefs?: readonly string[];
+    outputRefs?: readonly string[];
+    modelCallId?: string;
+    toolCallId?: string;
+    procedureId?: string;
+    stateBeforeRef?: string;
+    stateAfterRef?: string;
+    promptPackRef?: string;
+    loweredPromptRef?: string;
+    observationRefs?: readonly string[];
+    governance?: MainLoopStepGateResult;
+    contract?: MainLoopStepGateResult;
+    error?: MainLoopPublicSafeFailure;
+    now?: string;
+    trace?: MainLoopStepTrace;
+    metadata?: Readonly<Record<string, unknown>>;
+}): MainLoopStepRecord;
+export declare function prepareMainLoopTurn(request: MainLoopTurnPreparationRequest): MainLoopTurnPreparationResult;
+export declare function planFrameworkMainLoopHandoff(request: FrameworkMainLoopHandoffRequest): FrameworkMainLoopHandoffResult;
+export declare function planAgentMainLoopTick(request: AgentMainLoopRequest): AgentMainLoopResult;