@hunterzhu/pulse-runtime 0.1.0

package/dist/scheduler/runtime.d.ts

@@ -0,0 +1,486 @@
+import { MutationLog } from '../storage/mutation-log.js';
+import { PriorityInheritance, ReadyQueue, type RuntimeClock } from './index.js';
+import type { EffectRecord, EffectSubmission, EffectState, JsonValue, LaneRecord, LaneStepOutput, Outcome, ResumeInput, RuntimeState, RuntimeError, ForkAffinityMode, PrivacyLabel, PrivacyTaint, ProvenanceRef, ResumePoint, ResultRecord } from '../core/types.js';
+import { QuarantineScope } from '../lifecycle/scopes.js';
+import { PulseSession } from '../dsl/session.js';
+import type { ProgramRef } from '../dsl/templates.js';
+import { FactInbox, ObservationInbox, type FactInboxDedupeArchive, type FactInboxDedupeArchiveBatch } from '../core/inbox.js';
+import { EffectOutbox } from '../storage/outbox.js';
+import { type RuntimePersistenceBackend, type RuntimePersistenceSnapshot } from '../storage/persistence.js';
+import { type RuntimeLogSink, type RuntimeSessionStore, type SessionLogExport, type SessionLogExportOptions } from '../storage/session.js';
+import { ResourceLockManager } from './locks.js';
+import { type Mutation } from '../core/mutations.js';
+import { type MergePlan } from '../context/merger.js';
+import { ModelRouter, type ModelHostPolicy, type ModelRegistry } from '../models/router.js';
+import { SessionStoragePolicy, type StoragePolicyConfig } from '../storage/policy.js';
+import { type RuntimeTelemetryExporter, type RuntimeTelemetrySnapshot } from './telemetry.js';
+import { type ArtifactPublication } from '../storage/artifacts.js';
+import { type FindingPublication } from '../storage/findings.js';
+import { RuntimeToolRegistry } from '../tools/registry.js';
+import { type SchedulerDecisionConfig } from './decision.js';
+export interface LaneStepContext {
+    lane: Readonly<LaneRecord>;
+    state: Readonly<RuntimeState>;
+    resumeInput?: ResumeInput;
+    now: number;
+    observe?: (event: {
+        type: 'progress' | 'chunk' | 'trace' | 'warning' | 'diagnostic';
+        data: JsonValue;
+    }) => void;
+}
+export interface LaneProgram {
+    id: string;
+    version: string;
+    entry?: string;
+    step: (context: LaneStepContext) => LaneStepOutput;
+    errorBoundary?: (error: RuntimeError, context: LaneStepContext) => LaneStepOutput;
+    seriesMember?: ResumePoint;
+    seriesMemberProgram?: LaneProgram;
+    seriesKeys?: string[];
+    seriesOnMemberFailure?: 'continue' | 'abort';
+}
+export interface EffectObservation {
+    type: 'progress' | 'chunk' | 'trace' | 'warning' | 'diagnostic';
+    data: JsonValue;
+}
+export type EffectObservationEmitter = (observation: EffectObservation) => void;
+export interface EffectArtifactOutput {
+    mediaType: string;
+    content: Uint8Array | string;
+    privacy?: 'public' | 'cloud_allowed' | 'local_only';
+    privacyTaints?: PrivacyTaint[];
+    derivedFrom?: ProvenanceRef[];
+}
+export interface EffectExecution {
+    value: JsonValue;
+    normalized?: JsonValue;
+    artifact?: EffectArtifactOutput;
+    summary?: JsonValue;
+    privacy?: 'public' | 'cloud_allowed' | 'local_only';
+    privacyTaints?: PrivacyTaint[];
+    sideEffectState?: 'none' | 'applied' | 'known' | 'unknown';
+    executionRef?: JsonValue;
+    executionState?: 'succeeded' | 'failed' | 'remote_unknown';
+    status?: 'succeeded' | 'failed' | 'cancelled';
+    error?: RuntimeError;
+    rejectedOutput?: {
+        value: JsonValue;
+        privacy?: 'public' | 'cloud_allowed' | 'local_only';
+        privacyTaints?: PrivacyTaint[];
+        derivedFrom?: ProvenanceRef[];
+    };
+    metadata?: JsonValue;
+    observations?: EffectObservation[];
+}
+export type EffectExecutor = (effect: Readonly<EffectRecord>, signal: AbortSignal, emitObservation?: EffectObservationEmitter) => Promise<EffectExecution>;
+export interface EffectHandle {
+    id: string;
+    status(): EffectState;
+    requestCancel(reason: string): void;
+}
+export type HostCommand = {
+    type: 'reply';
+    agentId: string;
+    effectId: string;
+    value: JsonValue;
+} | {
+    type: 'cancel';
+    agentId: string;
+    reason: string;
+} | {
+    type: 'cancel_effect';
+    agentId: string;
+    effectId: string;
+    reason: string;
+} | {
+    type: 'set_lane_priority';
+    laneId: string;
+    priority: number;
+};
+interface EffectCompletionFact {
+    [key: string]: JsonValue;
+    type: 'effect_completion';
+    effectId: string;
+    attemptId: string;
+    execution: JsonValue;
+    status: 'succeeded' | 'failed' | 'cancelled';
+    error?: JsonValue;
+    dispatchError?: JsonValue;
+}
+interface LLMPreparationFact {
+    [key: string]: JsonValue;
+    type: 'llm_preparation';
+    effectId: string;
+    generation: number;
+    status: 'prepared' | 'stale';
+    projectionRef?: string;
+}
+interface EffectReconcileFact {
+    [key: string]: JsonValue;
+    type: 'effect_reconcile';
+    effectId: string;
+    attemptId: string;
+    value: JsonValue;
+    status: 'succeeded' | 'failed' | 'cancelled';
+    error?: JsonValue;
+}
+interface SchedulerDecisionFact {
+    [key: string]: JsonValue;
+    type: 'scheduler_decision';
+    decisionId: string;
+    candidateEpoch: number;
+    orderedLaneIds: string[];
+    modelId: string;
+}
+type RuntimeFact = HostCommand | EffectCompletionFact | LLMPreparationFact | EffectReconcileFact | SchedulerDecisionFact;
+export interface RuntimeConfig {
+    maxLaneStepsPerTick?: number;
+    maxTickMs?: number;
+    agingIntervalMs?: number;
+    agingCap?: number;
+    maxTotalLanes?: number;
+    maxQueuedEffects?: number;
+    maxRunning?: Partial<Record<'llm' | 'tool' | 'agent' | 'none', number>>;
+    forkAffinity?: ForkAffinityMode;
+    historySoftTokens?: number;
+    historyHardTokens?: number;
+    maxResultSummaryBytes?: number;
+    maxConsecutiveControlErrors?: number;
+    maxRuntimeMs?: number;
+    sessionId?: string;
+    maxAgentDepth?: number;
+    watchdogNoProgressThreshold?: number;
+    watchdogRepeatedActionThreshold?: number;
+    maxPreparingLLMs?: number;
+    maxPreparedLLMs?: number;
+    writerPreferenceBound?: number;
+    maxObservationEntries?: number;
+    maxObservationBytes?: number;
+    clock?: RuntimeClock;
+    trustedSanitizerIds?: string[];
+    storagePolicy?: StoragePolicyConfig;
+    persistence?: RuntimePersistenceSnapshot;
+    programs?: LaneProgram[];
+    models?: ModelRegistry;
+    hostPolicy?: ModelHostPolicy;
+    modelRouter?: ModelRouter;
+    tools?: RuntimeToolRegistry;
+    toolVersions?: Record<string, string>;
+    policyVersion?: string;
+    routerVersion?: string;
+    effectExecutor?: EffectExecutor;
+    /**
+     * Let an application opt into Runtime-owned Human Effect handling while
+     * still supplying a combined executor for model and tool effects.
+     * Existing custom executors keep their historical behavior by default.
+     */
+    builtinHumanEffects?: boolean;
+    effectSubmissionPreparer?: (submission: EffectSubmission) => EffectSubmission;
+    telemetryExporter?: RuntimeTelemetryExporter;
+    auditLogSink?: RuntimeLogSink;
+    auditLogPrivacy?: PrivacyLabel;
+    persistenceBackend?: RuntimePersistenceBackend;
+    sessionStore?: RuntimeSessionStore;
+    /** Optional durable membership view used to safely compact FactInbox dedupe ids. */
+    factInboxDedupeArchive?: FactInboxDedupeArchive;
+    /** Internal restore CAS baseline; differs from the hydrated envelope digest. */
+    persistenceExpectedDigest?: string;
+    budget?: RuntimeBudgetConfig;
+    schedulerDecision?: SchedulerDecisionConfig;
+}
+export interface RuntimeBudgetConfig {
+    maxTotalAttempts?: number;
+    maxLLMAttempts?: number;
+    maxToolAttempts?: number;
+    maxCostByCurrency?: Record<string, number>;
+}
+/**
+ * A warm start adopts the final Global Context from an explicit PulseSession.
+ * `agentId` remains a source-compatible alias for the pre-session API.
+ */
+export interface WarmStartSpec {
+    sessionId?: string;
+    agentId?: string;
+    globalVersion?: number | 'latest' | 'final';
+    include?: 'facts' | 'facts_and_findings';
+    relevanceRefs?: string[];
+}
+export type AgentPriority = 'background' | 'normal' | 'high' | 'urgent';
+export interface AgentPolicyRef {
+    id: string;
+}
+export interface AgentLimits {
+    id?: string;
+    timeoutMs?: number;
+    maxActiveLanes?: number;
+}
+export interface AgentCreateRequest {
+    goal: string;
+    program: LaneProgram | ProgramRef;
+    agentId?: string;
+    priority?: number | AgentPriority;
+    policy?: AgentPolicyRef;
+    policyId?: string;
+    limits?: AgentLimits;
+    limitsId?: string;
+    maxActiveLanes?: number;
+    warmStart?: WarmStartSpec;
+    parentAgentId?: string;
+    inheritedFloor?: number;
+}
+export interface BackgroundAgentInfo {
+    agentId: string;
+    rootLaneId: string;
+    state: NonNullable<import('../core/types.js').AgentRecord['state']>;
+    detached: true;
+}
+export interface AgentHandle {
+    id: string;
+    agentId: string;
+    laneId: string;
+}
+export declare class ProgramRegistry {
+    private readonly records;
+    register(program: LaneProgram): void;
+    get(programId: string, programVersion?: string): LaneProgram | undefined;
+    resolve(ref: ProgramRef): LaneProgram;
+    has(programId: string, programVersion?: string): boolean;
+    entries(): IterableIterator<[string, LaneProgram]>;
+}
+export declare class PulseRuntime {
+    readonly state: RuntimeState;
+    /** Host-facing read-only effect inspection. Returned records are detached snapshots. */
+    readonly effects: {
+        inspect: (effectId: string) => EffectRecord | undefined;
+    };
+    /** Host-facing read-only result lookup. Returned records are detached snapshots. */
+    readonly results: {
+        get: (resultRef: string) => ResultRecord | undefined;
+    };
+    private shuttingDown;
+    private readonly telemetryExporter;
+    private readonly auditLogSink;
+    private readonly auditLogPrivacy;
+    private readonly persistenceBackend;
+    private readonly sessionStore;
+    private readonly enforcingRecoveryPrograms;
+    private readonly toolVersions;
+    private readonly recoveryCompatibility;
+    private readonly policyVersion;
+    private readonly routerVersion;
+    private readonly budget;
+    private persistenceDigest;
+    private readonly budgetCost;
+    private persistencePending;
+    private persistenceScheduled;
+    private persistenceDirty;
+    private dispatchPersistencePending;
+    private dispatchPersistenceReady;
+    private readonly executionYieldPending;
+    readonly mutationLog: MutationLog;
+    readonly outbox: EffectOutbox;
+    readonly clock: RuntimeClock;
+    readonly ready: ReadyQueue;
+    readonly quarantine: QuarantineScope;
+    readonly priorityInheritance: PriorityInheritance;
+    readonly resourceLocks: ResourceLockManager;
+    readonly storagePolicy: SessionStoragePolicy;
+    readonly factInbox: FactInbox<RuntimeFact>;
+    readonly observationInbox: ObservationInbox;
+    readonly programs: ProgramRegistry;
+    readonly models: ModelRegistry;
+    readonly modelRouter: ModelRouter;
+    readonly tools: RuntimeToolRegistry;
+    private readonly executions;
+    private readonly lockReleases;
+    private readonly waitDeadlineTimers;
+    private readonly lockBlocked;
+    private readonly grantedLockReleases;
+    /** Every lock request id an Effect ever issued (across attempts), keyed by Effect id, so terminal cleanup never misses a queued request. */
+    private readonly lockRequests;
+    /** Consecutive background persistence failures; reset on the next successful write. */
+    private persistenceFailures;
+    private persistenceBackoff;
+    private readonly executor;
+    private factInboxDedupeArchive;
+    private readonly customExecutor;
+    private readonly builtinHumanEffects;
+    private enqueueSeq;
+    private readonly maxSteps;
+    private readonly maxTickMs;
+    private readonly maxConsecutiveControlErrors;
+    private readonly maxRuntimeAt?;
+    private readonly watchdogNoProgressThreshold;
+    private readonly watchdogRepeatedActionThreshold;
+    private readonly maxAgentDepth;
+    private readonly maxPreparingLLMs;
+    private readonly maxPreparedLLMs;
+    private readonly effectSubmissionPreparer;
+    private readonly schedulerDecisionCoordinator;
+    private readonly schedulerDecisionConfig;
+    private readonly schedulerDecisionModelId;
+    private readonly schedulerDecisionMaxReorderDistance;
+    private readonly schedulerDecisionReserveEvery;
+    private readonly schedulerDecisionIncludeGoals;
+    private schedulerDecisionEpoch;
+    private schedulerDecisionRequestSeq;
+    private schedulerDecisionDispatches;
+    private schedulerDecisionCache;
+    private readonly schedulerDecisionRequests;
+    private readonly preparingLLMs;
+    private readonly sessionId;
+    private hostCommandSeq;
+    private factWaiters;
+    private wakeScheduled;
+    private inDrain;
+    private wakeError;
+    private tickBudget;
+    static restore(backend: RuntimePersistenceBackend, config?: Omit<RuntimeConfig, 'persistence'>): Promise<PulseRuntime>;
+    constructor(config?: RuntimeConfig);
+    register(program: LaneProgram): void;
+    createAgent(request: AgentCreateRequest): AgentHandle;
+    createAgent(goal: string, program: LaneProgram, agentId?: string): AgentHandle;
+    start(agentId: string): PulseSession;
+    requestCancel(agentId: string, reason?: string): void;
+    setLanePriority(laneId: string, priority: number): void;
+    effectHandle(effectId: string): EffectHandle;
+    inspectLane(laneId: string): JsonValue;
+    detachAgent(agentId: string): BackgroundAgentInfo;
+    attachAgent(agentId: string): void;
+    backgroundAgents(): BackgroundAgentInfo[];
+    exportPersistence(): RuntimePersistenceSnapshot;
+    createFactInboxDedupeArchiveBatch(through?: number): FactInboxDedupeArchiveBatch;
+    compactFactInboxDedupeThrough(batch: FactInboxDedupeArchiveBatch): number;
+    persist(backend: RuntimePersistenceBackend): Promise<void>;
+    flushPersistence(): Promise<void>;
+    checkpoint(backend: RuntimePersistenceBackend, options?: {
+        compactEventsThrough?: number;
+    }): Promise<RuntimePersistenceSnapshot>;
+    mergeProposals(agentId: string, proposalIds?: string[]): MergePlan;
+    private emit;
+    private assertRecoveryPrograms;
+    private persistenceCompatibility;
+    private assertRecoveryCompatibility;
+    private currentToolVersions;
+    private tryEmit;
+    private rejectHostCommand;
+    private prepareStepOutput;
+    private prepareRegisteredToolSubmission;
+    private executeRegisteredEffect;
+    private journalEffect;
+    private enqueueFact;
+    enqueueHostCommand(command: HostCommand): void;
+    private enqueueEffectCompletion;
+    private enqueueLLMPreparation;
+    private enqueueEffectReconcile;
+    private scheduleWake;
+    private enqueueReadyItem;
+    enqueueLane(laneId: string): void;
+    private requestSchedulerDecision;
+    private applySchedulerDecision;
+    private selectReadyLane;
+    private scheduleRuntimeTimer;
+    private scheduleRuntimeDelay;
+    private seriesStep;
+    tick(): number;
+    run(): Promise<Outcome>;
+    run(maxTicks: number): Promise<Outcome>;
+    run(agentId: string, maxTicks?: number): Promise<Outcome>;
+    runAgent(agentId: string, maxTicks?: number): Promise<Outcome>;
+    waitForIdle(): Promise<void>;
+    shutdown(timeoutMs?: number): Promise<{
+        status: 'stopped' | 'timed_out';
+        unresolvedEffectIds: string[];
+        quarantine: string[];
+    }>;
+    inspect(): JsonValue;
+    telemetry(): RuntimeTelemetrySnapshot;
+    exportTelemetry(timestamp?: number): Promise<RuntimeTelemetrySnapshot>;
+    exportAuditLog(options?: SessionLogExportOptions): Promise<SessionLogExport>;
+    private assertStorageAdmission;
+    private schedulePersistence;
+    private persistenceState;
+    private markArtifactsPersisted;
+    /**
+     * Reconcile the storage policy with the (candidate) runtime state.
+     *
+     * Cost model: keys whose content is immutable once written (events, versioned
+     * Lane/global snapshots, LLM request snapshots, resume inputs, fact envelopes,
+     * published results) are only serialized and hashed on first sight; later
+     * syncs skip them with a map lookup. Only genuinely mutable records (waits,
+     * artifacts) are re-put every time. Pins are recomputed from scratch, which is
+     * a set-diff over keys, not over bodies.
+     */
+    private syncStoragePolicy;
+    private hasQueuedEffects;
+    private hasDueTimer;
+    private hasPendingTickCleanup;
+    private hasPendingHostInteraction;
+    private waitForFact;
+    private completeFinishedChildAgents;
+    completeEffect(effectId: string, execution: EffectExecution, status?: 'succeeded' | 'failed' | 'cancelled', error?: RuntimeError, additionalMutations?: Mutation[]): boolean;
+    markRemoteUnknown(effectId: string, sideEffectState: 'none' | 'applied' | 'known' | 'unknown'): void;
+    reconcileEffect(effectId: string, value: JsonValue, status?: 'succeeded' | 'failed' | 'cancelled', error?: RuntimeError): void;
+    reconcileEffectWith(effectId: string, resolver: (executionRef: JsonValue | undefined, effect: Readonly<EffectRecord>, signal: AbortSignal) => Promise<{
+        status: 'succeeded' | 'failed' | 'cancelled' | 'unknown';
+        output?: JsonValue;
+        error?: RuntimeError;
+    }>, signal?: AbortSignal): Promise<{
+        status: 'succeeded' | 'failed' | 'cancelled' | 'unknown';
+        output?: JsonValue;
+        error?: RuntimeError;
+    }>;
+    reconcileRegisteredEffect(effectId: string, signal?: AbortSignal): Promise<{
+        status: 'succeeded' | 'failed' | 'cancelled' | 'unknown';
+        output?: JsonValue;
+        error?: RuntimeError;
+    }>;
+    abandonEffect(effectId: string): void;
+    cancelEffect(effectId: string, graceMs?: number, reason?: string, additionalMutations?: Mutation[]): boolean;
+    publishArtifact(publication: ArtifactPublication): import('../core/types.js').ArtifactRecord;
+    publishFinding(publication: FindingPublication): import('../core/types.js').FindingRecord;
+    readArtifact(ref: string): Uint8Array;
+    pinArtifact(ref: string): void;
+    unpinArtifact(ref: string): void;
+    markArtifactPersisted(ref: string): void;
+    cancelAgent(agentId: string, reason?: string, additionalMutations?: Mutation[], commandTransactionId?: string): boolean;
+    private finalizeCancellations;
+    explain(laneId?: string): JsonValue;
+    retryEffect(effectId: string, delayMs: number): void;
+    private readyRetryEffect;
+    private scheduleRetry;
+    private dispatchQueuedEffects;
+    private dispatchQueuedEffectsNow;
+    private prepareLLMEffect;
+    private expireEffect;
+    private requestEffectCancellation;
+    private quarantineEffect;
+    private propagateCancelledLanes;
+    private runningCount;
+    budgetUsage(): {
+        attempts: number;
+        costByCurrency: Record<string, number>;
+    };
+    private budgetRejection;
+    private recordBudgetMetadata;
+    private acquireEffectLocks;
+    /**
+     * Release everything an Effect may hold on the lock manager: granted locks,
+     * grants that arrived asynchronously, and requests still waiting in a queue.
+     * This must run unconditionally on every terminal path. An Effect that was
+     * cancelled while still *waiting* for a lock never had an entry in
+     * `lockReleases`; skipping the cleanup in that case leaves a ghost request
+     * that later receives the grant and holds the resource forever.
+     */
+    private releaseEffectLocks;
+    private enqueueNewReadyLanes;
+    private commitAgentState;
+    private commitLaneControlInput;
+    private failLane;
+    private refreshWaits;
+    private scheduleWaitDeadline;
+    private cancelWaitDeadline;
+    private expireWait;
+    private recomputePriorityInheritance;
+}
+export {};