@hunterzhu/pulse-runtime 0.1.5 → 0.1.7

package/dist/scheduler/runtime.d.ts

@@ -1,6 +1,6 @@
 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 type { EffectRecord, EffectSubmission, EffectState, JsonValue, LaneRecord, LaneStepOutput, Outcome, ResumeInput, RuntimeState, RuntimeError, ForkAffinityMode, PrivacyLabel, PrivacyTaint, ProvenanceRef, ResumePoint, ResultRecord, HumanInputRecord } from '../core/types.js';
 import { QuarantineScope } from '../lifecycle/scopes.js';
 import { PulseSession } from '../dsl/session.js';
 import type { ProgramRef } from '../dsl/templates.js';
@@ -18,10 +18,12 @@ 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';
+import { type HumanArbitrationConfig } from './human-arbitration.js';
 export interface LaneStepContext {
     lane: Readonly<LaneRecord>;
     state: Readonly<RuntimeState>;
     resumeInput?: ResumeInput;
+    humanInputs?: readonly HumanInputRecord[];
     now: number;
     observe?: (event: {
         type: 'progress' | 'chunk' | 'trace' | 'warning' | 'diagnostic';
@@ -83,6 +85,12 @@ export type HostCommand = {
     agentId: string;
     effectId: string;
     value: JsonValue;
+} | {
+    type: 'human_input';
+    agentId: string;
+    inputId: string;
+    value: JsonValue;
+    targetEffectId?: string;
 } | {
     type: 'cancel';
     agentId: string;
@@ -132,7 +140,12 @@ interface SchedulerDecisionFact {
     orderedLaneIds: string[];
     modelId: string;
 }
-type RuntimeFact = HostCommand | EffectCompletionFact | LLMPreparationFact | EffectReconcileFact | SchedulerDecisionFact;
+interface HumanArbitrationFact {
+    [key: string]: JsonValue;
+    type: 'human_arbitration';
+    decision: JsonValue;
+}
+type RuntimeFact = HostCommand | EffectCompletionFact | LLMPreparationFact | EffectReconcileFact | SchedulerDecisionFact | HumanArbitrationFact;
 export interface RuntimeConfig {
     maxLaneStepsPerTick?: number;
     maxTickMs?: number;
@@ -187,6 +200,8 @@ export interface RuntimeConfig {
     persistenceExpectedDigest?: string;
     budget?: RuntimeBudgetConfig;
     schedulerDecision?: SchedulerDecisionConfig;
+    /** Optional model used for ordinary Human messages after deterministic control rules. */
+    humanArbitration?: HumanArbitrationConfig;
 }
 export interface RuntimeBudgetConfig {
     maxTotalAttempts?: number;
@@ -263,6 +278,13 @@ export declare class PulseRuntime {
     private readonly auditLogPrivacy;
     private readonly persistenceBackend;
     private readonly sessionStore;
+    /**
+     * The file session store is synchronous by design, so avoid rewriting an
+     * unchanged warm-start snapshot on every scheduler tick.  Without this
+     * guard an idle run can spend its whole event loop serializing and fsyncing
+     * the same snapshot, starving effect dispatch and human input handling.
+     */
+    private readonly sessionStoreDigests;
     private readonly enforcingRecoveryPrograms;
     private readonly toolVersions;
     private readonly recoveryCompatibility;
@@ -305,6 +327,7 @@ export declare class PulseRuntime {
     private factInboxDedupeArchive;
     private readonly customExecutor;
     private readonly builtinHumanEffects;
+    private humanInputProgram;
     private enqueueSeq;
     private readonly maxSteps;
     private readonly maxTickMs;
@@ -317,6 +340,10 @@ export declare class PulseRuntime {
     private readonly maxPreparedLLMs;
     private readonly effectSubmissionPreparer;
     private readonly schedulerDecisionCoordinator;
+    private readonly humanArbitrationCoordinator;
+    private readonly humanArbitrationModelId;
+    private humanArbitrationRequestSeq;
+    private readonly humanArbitrationRequests;
     private readonly schedulerDecisionConfig;
     private readonly schedulerDecisionModelId;
     private readonly schedulerDecisionMaxReorderDistance;
@@ -331,16 +358,34 @@ export declare class PulseRuntime {
     private readonly sessionId;
     private hostCommandSeq;
     private factWaiters;
+    private activityWaiters;
     private wakeScheduled;
+    /**
+     * A lock grant can happen synchronously while an effect completion is being
+     * applied inside tick(). scheduleWake() intentionally avoids re-entering the
+     * drain in that case, so remember forced wake requests and service them once
+     * the current drain has finished.
+     */
+    private wakeAfterDrain;
     private inDrain;
     private wakeError;
     private tickBudget;
     static restore(backend: RuntimePersistenceBackend, config?: Omit<RuntimeConfig, 'persistence'>): Promise<PulseRuntime>;
     constructor(config?: RuntimeConfig);
     register(program: LaneProgram): void;
+    /** Register the program used for urgent, concurrent human interactions. */
+    setHumanInputProgram(program: LaneProgram): void;
     createAgent(request: AgentCreateRequest): AgentHandle;
     createAgent(goal: string, program: LaneProgram, agentId?: string): AgentHandle;
     start(agentId: string): PulseSession;
+    /** Accept external human input without waiting for the current Effect to settle. */
+    submitHumanInput(agentId: string, inputId: string, value: JsonValue, targetEffectId?: string): boolean;
+    humanInputsFor(agentId: string): HumanInputRecord[];
+    private humanArbitrationRequest;
+    private ownsAgentForRuntime;
+    private commitHumanInputDecision;
+    private applyHumanArbitrationDecision;
+    private requestHumanArbitration;
     requestCancel(agentId: string, reason?: string): void;
     setLanePriority(laneId: string, priority: number): void;
     effectHandle(effectId: string): EffectHandle;
@@ -369,7 +414,7 @@ export declare class PulseRuntime {
     private executeRegisteredEffect;
     private journalEffect;
     private enqueueFact;
-    enqueueHostCommand(command: HostCommand): void;
+    enqueueHostCommand(command: HostCommand): boolean;
     private enqueueEffectCompletion;
     private enqueueLLMPreparation;
     private enqueueEffectReconcile;
@@ -417,6 +462,9 @@ export declare class PulseRuntime {
     private hasPendingTickCleanup;
     private hasPendingHostInteraction;
     private waitForFact;
+    /** Wait for a state or observation change without polling the event loop. */
+    waitForActivity(timeoutMs?: number): Promise<void>;
+    private notifyActivity;
     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;