@hunterzhu/pulse-runtime 0.1.5 → 0.1.6

package/dist/core/inbox.d.ts

@@ -57,6 +57,8 @@ export interface FactInboxSnapshot<T extends JsonValue = JsonValue> {
     nextSeq: number;
     seen: string[];
     queue: FactEnvelope<T>[];
+    /** Number of queued urgent entries at the head of `queue` (v2+). */
+    urgentCount?: number;
     dedupeLedger?: FactInboxDedupeLedgerSnapshot;
 }
 export declare class FactInbox<T extends JsonValue = JsonValue> {
@@ -64,13 +66,17 @@ export declare class FactInbox<T extends JsonValue = JsonValue> {
     private readonly seen;
     private nextSeq;
     private archivedThrough;
+    private urgentCount;
     private dedupeArchive;
     constructor(options?: {
         dedupeArchive?: FactInboxDedupeArchive;
     });
     /** Attach a backend-provided archive before the first compaction. */
     attachDedupeArchive(archive: FactInboxDedupeArchive): void;
+    private enqueueInternal;
     enqueue(fact: T, eventId: string): FactEnvelope<T> | undefined;
+    /** Insert a host control fact ahead of already queued background work. */
+    enqueueUrgent(fact: T, eventId: string): FactEnvelope<T> | undefined;
     drain(limit?: number): FactEnvelope<T>[];
     get size(): number;
     get dedupeWatermark(): number;

package/dist/core/inbox.js

@@ -14,6 +14,7 @@ export class FactInbox {
     seen = new Map();
     nextSeq = 1;
     archivedThrough = 0;
+    urgentCount = 0;
     dedupeArchive;
     constructor(options = {}) {
         this.dedupeArchive = options.dedupeArchive;
@@ -26,18 +27,28 @@ export class FactInbox {
             throw new Error('FACT_INBOX_DEDUPE_ARCHIVE_ALREADY_COMPACTED');
         this.dedupeArchive = archive;
     }
-    enqueue(fact, eventId) {
+    enqueueInternal(fact, eventId, urgent) {
         if (!eventId || this.seen.has(eventId) || this.dedupeArchive?.contains(eventId))
             return undefined;
         const envelope = { eventId, receivedSeq: this.nextSeq++, fact: structuredClone(fact) };
         this.seen.set(eventId, envelope.receivedSeq);
-        this.queue.push(envelope);
+        if (urgent) {
+            this.queue.splice(this.urgentCount, 0, envelope);
+            this.urgentCount++;
+        }
+        else
+            this.queue.push(envelope);
         return structuredClone(envelope);
     }
+    enqueue(fact, eventId) { return this.enqueueInternal(fact, eventId, false); }
+    /** Insert a host control fact ahead of already queued background work. */
+    enqueueUrgent(fact, eventId) { return this.enqueueInternal(fact, eventId, true); }
     drain(limit = Number.POSITIVE_INFINITY) {
         if (limit !== Number.POSITIVE_INFINITY && (!Number.isInteger(limit) || limit < 0))
             throw new Error('INVALID_FACT_DRAIN_LIMIT');
-        return this.queue.splice(0, limit).map((envelope) => structuredClone(envelope));
+        const drained = this.queue.splice(0, limit);
+        this.urgentCount = Math.max(0, this.urgentCount - drained.length);
+        return drained.map((envelope) => structuredClone(envelope));
     }
     get size() { return this.queue.length; }
     get dedupeWatermark() { return this.archivedThrough; }
@@ -50,6 +61,7 @@ export class FactInbox {
             nextSeq: this.nextSeq,
             seen: [...this.seen.keys()],
             queue: this.queue.map((envelope) => structuredClone(envelope)),
+            ...(this.urgentCount === 0 ? {} : { urgentCount: this.urgentCount }),
             dedupeLedger: {
                 schemaVersion: 1,
                 archivedThrough: this.archivedThrough,
@@ -117,10 +129,11 @@ export class FactInbox {
             this.seen.set(eventId, receivedSeq);
         this.nextSeq = restored.nextSeq;
         this.archivedThrough = restored.archivedThrough;
+        this.urgentCount = restored.urgentCount;
     }
     static fromSnapshot(snapshot, options = {}) {
         const value = snapshot;
-        if (!value || (value.schemaVersion !== 1 && value.schemaVersion !== 2) || !Number.isInteger(value.nextSeq) || value.nextSeq < 1 || !Array.isArray(value.seen) || value.seen.some((eventId) => typeof eventId !== 'string' || eventId.length === 0) || !Array.isArray(value.queue))
+        if (!value || (value.schemaVersion !== 1 && value.schemaVersion !== 2) || !Number.isInteger(value.nextSeq) || value.nextSeq < 1 || !Array.isArray(value.seen) || value.seen.some((eventId) => typeof eventId !== 'string' || eventId.length === 0) || !Array.isArray(value.queue) || (value.urgentCount !== undefined && (!Number.isInteger(value.urgentCount) || value.urgentCount < 0 || value.urgentCount > value.queue.length)))
             throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
         if (new Set(value.seen).size !== value.seen.length)
             throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
@@ -151,8 +164,8 @@ export class FactInbox {
                 throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
             if (inbox.queue.some((candidate) => candidate.eventId === envelope.eventId || candidate.receivedSeq === envelope.receivedSeq))
                 throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
-            if (envelope.receivedSeq <= maxReceivedSeq)
-                throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
+            // Urgent host facts may be inserted ahead of older entries, so queue
+            // order is intentionally different from received sequence order.
             const knownSeq = seen.get(envelope.eventId);
             if (knownSeq !== undefined && knownSeq !== envelope.receivedSeq)
                 throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
@@ -161,14 +174,25 @@ export class FactInbox {
             inbox.queue.push({ eventId: envelope.eventId, receivedSeq: envelope.receivedSeq, fact: structuredClone(envelope.fact) });
             maxReceivedSeq = Math.max(maxReceivedSeq, envelope.receivedSeq);
         }
+        // Preserve the serialized queue order. Urgent entries are allowed to have
+        // newer receivedSeq values ahead of background entries, but each priority
+        // band must retain its own FIFO order. This rejects ambiguous snapshots
+        // instead of silently normalizing a caller-provided reorder.
+        const urgentCount = value.urgentCount ?? 0;
+        const urgentSeqs = value.queue.slice(0, urgentCount).map((entry) => entry.receivedSeq);
+        const backgroundSeqs = value.queue.slice(urgentCount).map((entry) => entry.receivedSeq);
+        const isAscending = (seqs) => seqs.every((seq, index) => index === 0 || seq > seqs[index - 1]);
+        if (!isAscending(urgentSeqs) || !isAscending(backgroundSeqs))
+            throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
         if (value.nextSeq <= maxReceivedSeq)
             throw new Error('INVALID_FACT_INBOX_SNAPSHOT');
         for (const [eventId, receivedSeq] of seen)
             inbox.seen.set(eventId, receivedSeq);
         inbox.nextSeq = value.nextSeq;
+        inbox.urgentCount = urgentCount;
         return inbox;
     }
-    clear() { this.queue.length = 0; }
+    clear() { this.queue.length = 0; this.urgentCount = 0; }
 }
 export class ObservationInbox {
     maxEntries;

package/dist/core/mutations.d.ts

@@ -1,4 +1,4 @@
-import type { RuntimeEventInput, RuntimeState, RuntimeError, ContextVersion, JsonValue, AgentRecord, LaneRecord, EffectRecord, WaitRecord, ResultRecord, FindingRecord, ArtifactRecord, LaneId, WaitId, EffectId, HistoryRecord, MergeProposal, ToolCallCorrelation, PrivacyMetadata } from './types.js';
+import type { RuntimeEventInput, RuntimeState, RuntimeError, ContextVersion, JsonValue, AgentRecord, LaneRecord, EffectRecord, WaitRecord, ResultRecord, FindingRecord, ArtifactRecord, LaneId, WaitId, EffectId, HistoryRecord, MergeProposal, ToolCallCorrelation, PrivacyMetadata, HumanInputRecord } from './types.js';
 export type Mutation = {
     op: 'setAgent';
     agentId: string;
@@ -36,6 +36,10 @@ export type Mutation = {
 } | {
     op: 'setToolCallCorrelation';
     record: ToolCallCorrelation;
+} | {
+    op: 'setHumanInput';
+    inputId: string;
+    record: HumanInputRecord;
 } | {
     op: 'insertMergeProposal';
     proposal: MergeProposal;

package/dist/core/mutations.js

@@ -21,7 +21,7 @@ export function forkRuntimeStateForAdmission(state, mutations) {
     for (const id of dirtyLanes) {
         const lane = lanes.get(id);
         if (lane)
-            lanes.set(id, { ...lane, ...(lane.visibleResultRefs === undefined ? {} : { visibleResultRefs: new Set(lane.visibleResultRefs) }) });
+            lanes.set(id, { ...lane, ...(lane.visibleResultRefs === undefined ? {} : { visibleResultRefs: new Set(lane.visibleResultRefs) }), ...(lane.pendingHumanInputs === undefined ? {} : { pendingHumanInputs: structuredClone(lane.pendingHumanInputs) }) });
     }
     return {
         ...state,
@@ -33,6 +33,7 @@ export function forkRuntimeStateForAdmission(state, mutations) {
         artifacts: new Map(state.artifacts),
         toolCallCorrelations: new Map(state.toolCallCorrelations),
         mergeProposals: new Map(state.mergeProposals),
+        humanInputs: new Map(state.humanInputs),
         events: state.events.slice(),
         nextIds: { ...state.nextIds },
         trustedSanitizerIds: new Set(state.trustedSanitizerIds),
@@ -91,6 +92,9 @@ export function apply(state, mutations, defaults = {}) {
             case 'setToolCallCorrelation':
                 state.toolCallCorrelations.set(mutation.record.toolCallId, mutation.record);
                 break;
+            case 'setHumanInput':
+                state.humanInputs.set(mutation.inputId, mutation.record);
+                break;
             case 'insertMergeProposal':
                 state.mergeProposals.set(mutation.proposal.id, mutation.proposal);
                 break;

package/dist/core/types.d.ts

@@ -123,6 +123,8 @@ export interface LaneRecord {
     resume: ResumePoint;
     series?: SeriesLaneSpec;
     pendingResumeInput?: ResumeInput;
+    /** Human messages steered into this lane while it was executing or waiting. */
+    pendingHumanInputs?: HumanInputRecord[];
     /** Control proposals that arrived while another ResumeInput occupied the slot. */
     pendingControlProposals?: ControlProposal[];
     contextSnapshotVersion: ContextVersion;
@@ -319,6 +321,9 @@ export type ResumeInput = {
 } | {
     type: 'submitted';
     targets: Record<string, TargetRef>;
+} | {
+    type: 'human';
+    input: HumanInputRecord;
 } | {
     type: 'control_error';
     error: RuntimeError;
@@ -559,6 +564,7 @@ export interface RuntimeState {
     artifacts: Map<ArtifactRef, ArtifactRecord>;
     toolCallCorrelations: Map<string, ToolCallCorrelation>;
     mergeProposals: Map<string, MergeProposal>;
+    humanInputs: Map<string, HumanInputRecord>;
     events: RuntimeEvent[];
     eventsCompactedThrough?: number;
     nextIds: {
@@ -598,6 +604,20 @@ export interface ToolCallCorrelation {
     toolEffectId: EffectId;
     resultRef?: ResultRef;
 }
+/** Durable external input accepted while other Effects are still running. */
+export interface HumanInputRecord {
+    id: string;
+    agentId: AgentId;
+    value: JsonValue;
+    receivedAt: number;
+    status: 'pending' | 'consumed' | 'deferred';
+    targetEffectId?: EffectId;
+    handledByLaneId?: LaneId;
+    decision?: 'respond' | 'steer' | 'spawn' | 'defer' | 'cancel';
+    decisionReason?: string;
+    decisionModelId?: string;
+    decidedAt?: number;
+}
 export declare function createRuntimeState(maxTotalLanes?: number, options?: {
     maxQueuedEffects?: number;
     maxRunning?: Partial<Record<ConcurrencyClass, number>>;

package/dist/core/types.js

@@ -84,7 +84,7 @@ export function privacyTaintsForDerivedRefs(state, lane, refs) {
     return output;
 }
 export function createRuntimeState(maxTotalLanes = 64, options = {}) {
-    return { now: 0, agents: new Map(), lanes: new Map(), effects: new Map(), waits: new Map(), results: new Map(), artifacts: new Map(), toolCallCorrelations: new Map(), mergeProposals: new Map(), events: [], nextIds: { agent: 1, lane: 1, effect: 1, wait: 1, result: 1, artifact: 1, proposal: 1, event: 1 }, maxTotalLanes, maxQueuedEffects: options.maxQueuedEffects ?? 256, maxRunning: { llm: 4, tool: 16, agent: 4, none: Number.POSITIVE_INFINITY, ...(options.maxRunning ?? {}) }, forkAffinity: options.forkAffinity ?? 'advise', historySoftTokens: options.historySoftTokens ?? 8_000, historyHardTokens: options.historyHardTokens ?? 16_000, maxResultSummaryBytes: options.maxResultSummaryBytes ?? 4_096, trustedSanitizerIds: new Set(options.trustedSanitizerIds ?? []) };
+    return { now: 0, agents: new Map(), lanes: new Map(), effects: new Map(), waits: new Map(), results: new Map(), artifacts: new Map(), toolCallCorrelations: new Map(), mergeProposals: new Map(), humanInputs: new Map(), events: [], nextIds: { agent: 1, lane: 1, effect: 1, wait: 1, result: 1, artifact: 1, proposal: 1, event: 1 }, maxTotalLanes, maxQueuedEffects: options.maxQueuedEffects ?? 256, maxRunning: { llm: 4, tool: 16, agent: 4, none: Number.POSITIVE_INFINITY, ...(options.maxRunning ?? {}) }, forkAffinity: options.forkAffinity ?? 'advise', historySoftTokens: options.historySoftTokens ?? 8_000, historyHardTokens: options.historyHardTokens ?? 16_000, maxResultSummaryBytes: options.maxResultSummaryBytes ?? 4_096, trustedSanitizerIds: new Set(options.trustedSanitizerIds ?? []) };
 }
 export function privacyRank(label) { return label === 'public' ? 0 : label === 'cloud_allowed' ? 1 : 2; }
 export function strictestPrivacy(labels) { return labels.reduce((current, next) => privacyRank(next) > privacyRank(current) ? next : current, 'public'); }

package/dist/dsl/session.d.ts

@@ -26,6 +26,7 @@ export interface PulseSessionSnapshot {
     waits: unknown[];
     results: unknown[];
     mergeProposals: unknown[];
+    humanInputs: unknown[];
     quarantine: unknown[];
     observationsPending: number;
 }
@@ -36,10 +37,16 @@ export declare class PulseSession {
     /** Stable session handle used by the explicit warm-start API. */
     readonly sessionId: string;
     constructor(runtime: PulseRuntime, agentId: string);
+    private ownsAgent;
     private ownsEvent;
+    private hasActiveDescendant;
     stream(fromSeq?: number): AsyncIterable<SessionEvent>;
     snapshot(): Promise<PulseSessionSnapshot>;
     outcome(): Promise<Outcome>;
     reply(effectId: string, value: JsonValue): Promise<void>;
+    /** Submit a human message while the agent is still running. The scheduler
+     * records it immediately; targetEffectId is optional for direct replies to
+     * a waiting Human Effect. */
+    submitHumanInput(inputId: string, value: JsonValue, targetEffectId?: string): Promise<void>;
     cancel(reason: string): Promise<void>;
 }

package/dist/dsl/session.js

@@ -19,15 +19,29 @@ export class PulseSession {
             };
         });
     }
+    ownsAgent(agentId) {
+        let current = this.runtime.state.agents.get(agentId);
+        const seen = new Set();
+        while (current && !seen.has(current.id)) {
+            if (current.id === this.agentId)
+                return true;
+            seen.add(current.id);
+            current = current.parentAgentId === undefined ? undefined : this.runtime.state.agents.get(current.parentAgentId);
+        }
+        return false;
+    }
     ownsEvent(event) {
-        if (event.agentId === this.agentId)
+        if (event.agentId !== undefined && this.ownsAgent(event.agentId))
+            return true;
+        if (event.laneId !== undefined && this.ownsAgent(this.runtime.state.lanes.get(event.laneId)?.agentId ?? ''))
+            return true;
+        if (event.effectId !== undefined && this.ownsAgent(this.runtime.state.effects.get(event.effectId)?.agentId ?? ''))
             return true;
-        if (event.laneId !== undefined)
-            return this.runtime.state.lanes.get(event.laneId)?.agentId === this.agentId;
-        if (event.effectId !== undefined)
-            return this.runtime.state.effects.get(event.effectId)?.agentId === this.agentId;
         return false;
     }
+    hasActiveDescendant() {
+        return [...this.runtime.state.agents.values()].some((agent) => this.ownsAgent(agent.id) && agent.id !== this.agentId && agent.state !== undefined && !['succeeded', 'failed', 'cancelled'].includes(agent.state));
+    }
     async *stream(fromSeq = 0) {
         let cursor = fromSeq;
         let observationCursor = 0;
@@ -55,7 +69,7 @@ export class PulseSession {
                 yield { kind: 'observation', type: 'observation', seq: observation.seq, observation: observation };
             }
             const root = [...this.runtime.state.lanes.values()].find((lane) => lane.agentId === this.agentId && lane.ownerLaneId === undefined);
-            if (root && ['succeeded', 'failed', 'cancelled'].includes(root.status) && (this.runtime.state.events.at(-1)?.seq ?? compactedThrough) === cursor)
+            if (root && ['succeeded', 'failed', 'cancelled'].includes(root.status) && !this.hasActiveDescendant() && (this.runtime.state.events.at(-1)?.seq ?? compactedThrough) === cursor)
                 return;
             await new Promise((resolve) => setImmediate(resolve));
         }
@@ -71,11 +85,12 @@ export class PulseSession {
             now: this.runtime.state.now,
             eventSeq: this.runtime.state.events.at(-1)?.seq ?? 0,
             agent: agent ? structuredClone({ id: agent.id, goal: agent.goal ?? null, state: agent.state ?? null, latestGlobalVersion: agent.latestGlobalVersion, globalVersions: [...agent.globalVersions.entries()].map(([version, value]) => ({ version, value, ...(agent.globalPrivacy?.get(version) === undefined ? {} : { privacy: agent.globalPrivacy.get(version) }) })) }) : null,
-            lanes: [...this.runtime.state.lanes.values()].filter((lane) => laneIds.has(lane.id)).map((lane) => structuredClone({ id: lane.id, agentId: lane.agentId, ownerLaneId: lane.ownerLaneId ?? null, status: lane.status, cancelReason: lane.cancelReason ?? null, failure: lane.failure ?? null, version: lane.version, goal: lane.goal, priority: lane.priority, inheritedFloor: lane.inheritedFloor ?? null, readySince: lane.readySince, resume: lane.resume, pendingResumeInput: lane.pendingResumeInput ?? null, contextSnapshotVersion: lane.contextSnapshotVersion, context: lane.context, visibleResultRefs: lane.visibleResultRefs ? [...lane.visibleResultRefs] : [], historyPressure: lane.historyPressure ?? null, activeWaitId: lane.activeWaitId ?? null, children: [...lane.children], ownedEffectIds: [...lane.ownedEffectIds], resultRef: lane.resultRef ?? null, closingResult: lane.closingResult ?? null, consecutiveControlErrors: lane.consecutiveControlErrors ?? 0, unresolvedEffectIds: lane.unresolvedEffectIds ?? [], progressWatchdog: lane.progressWatchdog ?? null })),
+            lanes: [...this.runtime.state.lanes.values()].filter((lane) => laneIds.has(lane.id)).map((lane) => structuredClone({ id: lane.id, agentId: lane.agentId, ownerLaneId: lane.ownerLaneId ?? null, status: lane.status, cancelReason: lane.cancelReason ?? null, failure: lane.failure ?? null, version: lane.version, goal: lane.goal, priority: lane.priority, inheritedFloor: lane.inheritedFloor ?? null, readySince: lane.readySince, resume: lane.resume, pendingResumeInput: lane.pendingResumeInput ?? null, pendingHumanInputs: lane.pendingHumanInputs ?? [], contextSnapshotVersion: lane.contextSnapshotVersion, context: lane.context, visibleResultRefs: lane.visibleResultRefs ? [...lane.visibleResultRefs] : [], historyPressure: lane.historyPressure ?? null, activeWaitId: lane.activeWaitId ?? null, children: [...lane.children], ownedEffectIds: [...lane.ownedEffectIds], resultRef: lane.resultRef ?? null, closingResult: lane.closingResult ?? null, consecutiveControlErrors: lane.consecutiveControlErrors ?? 0, unresolvedEffectIds: lane.unresolvedEffectIds ?? [], progressWatchdog: lane.progressWatchdog ?? null })),
             effects: effects.map((effect) => structuredClone(effect)),
             waits: [...this.runtime.state.waits.values()].filter((wait) => laneIds.has(wait.laneId)).map((wait) => structuredClone(wait)),
             results: [...this.runtime.state.results.values()].filter((result) => (result.effectId !== undefined && effectIds.has(result.effectId)) || [...this.runtime.state.lanes.values()].some((lane) => laneIds.has(lane.id) && lane.resultRef === result.id)).map((result) => structuredClone(result)),
             mergeProposals: [...this.runtime.state.mergeProposals.values()].filter((proposal) => proposal.agentId === this.agentId).map((proposal) => structuredClone(proposal)),
+            humanInputs: [...this.runtime.state.humanInputs.values()].filter((input) => input.agentId === this.agentId).map((input) => structuredClone(input)),
             quarantine: structuredClone(this.runtime.quarantine.snapshot().filter((entry) => effectIds.has(entry.effectId))),
             observationsPending: this.runtime.observationInbox.snapshot().filter((observation) => observation.agentId === this.agentId).length,
         };
@@ -89,5 +104,11 @@ export class PulseSession {
             throw new Error('EFFECT_NOT_REPLYABLE');
         this.runtime.enqueueHostCommand({ type: 'reply', agentId: this.agentId, effectId, value });
     }
+    /** Submit a human message while the agent is still running. The scheduler
+     * records it immediately; targetEffectId is optional for direct replies to
+     * a waiting Human Effect. */
+    async submitHumanInput(inputId, value, targetEffectId) {
+        this.runtime.submitHumanInput(this.agentId, inputId, value, targetEffectId);
+    }
     async cancel(reason) { this.runtime.requestCancel(this.agentId, reason); }
 }

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from './transitions/index.js';
 export * from './dependencies/index.js';
 export * from './scheduler/index.js';
 export * from './scheduler/runtime.js';
+export * from './scheduler/human-arbitration.js';
 export * from './lifecycle/index.js';
 export * from './context/index.js';
 export * from './models/index.js';

package/dist/index.js

@@ -7,6 +7,7 @@ export * from './transitions/index.js';
 export * from './dependencies/index.js';
 export * from './scheduler/index.js';
 export * from './scheduler/runtime.js';
+export * from './scheduler/human-arbitration.js';
 export * from './lifecycle/index.js';
 export * from './context/index.js';
 export * from './models/index.js';

package/dist/scheduler/human-arbitration.d.ts

@@ -0,0 +1,59 @@
+import type { EffectRecord, HumanInputRecord, JsonValue, LaneRecord } from '../core/types.js';
+export type HumanArbitrationAction = 'respond' | 'steer' | 'spawn' | 'defer' | 'cancel';
+export interface HumanArbitrationCandidate {
+    laneId: string;
+    agentId: string;
+    status: LaneRecord['status'];
+    priority: number;
+    goal?: string;
+    activeWaitId?: string;
+}
+export interface HumanArbitrationEffectCandidate {
+    effectId: string;
+    agentId: string;
+    laneId: string;
+    kind: EffectRecord['kind'];
+    state: EffectRecord['state'];
+    sideEffectPolicy?: EffectRecord['sideEffectPolicy'];
+    sideEffectState: EffectRecord['sideEffectState'];
+}
+export interface HumanArbitrationRequest {
+    schemaVersion: 1;
+    decisionId: string;
+    agentId: string;
+    input: HumanInputRecord;
+    lanes: readonly HumanArbitrationCandidate[];
+    effects: readonly HumanArbitrationEffectCandidate[];
+    availableLLMSlots: number;
+}
+export interface HumanArbitrationDecision {
+    schemaVersion?: 1;
+    decisionId: string;
+    inputId: string;
+    agentId: string;
+    action: HumanArbitrationAction;
+    targetLaneId?: string;
+    targetEffectId?: string;
+    reason?: string;
+    modelId: string;
+}
+export interface HumanArbitrationModel {
+    readonly id: string;
+    decide(request: HumanArbitrationRequest, signal: AbortSignal): Promise<HumanArbitrationDecision>;
+}
+export interface HumanArbitrationConfig {
+    model?: HumanArbitrationModel;
+    timeoutMs?: number;
+}
+export declare class HumanArbitrationCoordinator {
+    private readonly model;
+    private readonly timeoutMs;
+    private outstanding;
+    private readonly controllers;
+    constructor(model: HumanArbitrationModel, timeoutMs: number);
+    get pending(): number;
+    request(request: HumanArbitrationRequest, onDecision: (decision: HumanArbitrationDecision) => void, onFailure: () => void): boolean;
+    cancel(): void;
+}
+/** Deterministic, side-effect-safe control grammar used before model arbitration. */
+export declare function ruleHumanArbitration(value: JsonValue, agentId: string, inputId: string, modelId?: string): HumanArbitrationDecision | undefined;

package/dist/scheduler/human-arbitration.js

@@ -0,0 +1,54 @@
+export class HumanArbitrationCoordinator {
+    model;
+    timeoutMs;
+    outstanding = 0;
+    controllers = new Set();
+    constructor(model, timeoutMs) {
+        this.model = model;
+        this.timeoutMs = timeoutMs;
+    }
+    get pending() { return this.outstanding; }
+    request(request, onDecision, onFailure) {
+        if (this.outstanding > 0)
+            return false;
+        const controller = new AbortController();
+        this.controllers.add(controller);
+        this.outstanding++;
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        void Promise.resolve().then(() => this.model.decide(structuredClone(request), controller.signal)).then((decision) => {
+            if (decision && typeof decision === 'object')
+                onDecision(structuredClone(decision));
+            else
+                onFailure();
+        }, () => onFailure()).finally(() => {
+            clearTimeout(timer);
+            this.controllers.delete(controller);
+            this.outstanding--;
+        });
+        return true;
+    }
+    cancel() { for (const controller of this.controllers)
+        controller.abort(); this.controllers.clear(); }
+}
+/** Deterministic, side-effect-safe control grammar used before model arbitration. */
+export function ruleHumanArbitration(value, agentId, inputId, modelId = 'rules') {
+    const object = value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+    const text = typeof value === 'string' ? value.trim() : typeof object?.text === 'string' ? object.text.trim() : undefined;
+    const command = typeof object?.command === 'string' ? object.command : text?.startsWith('/') ? text.slice(1).split(/\s+/, 1)[0] : undefined;
+    if (!command)
+        return undefined;
+    const normalized = command.toLowerCase();
+    const targetLaneId = typeof object?.laneId === 'string' ? object.laneId : undefined;
+    const targetEffectId = typeof object?.effectId === 'string' ? object.effectId : undefined;
+    if (normalized === 'cancel' || normalized === 'stop' || normalized === 'abort')
+        return { schemaVersion: 1, decisionId: `rule:${inputId}`, inputId, agentId, action: 'cancel', ...(targetLaneId === undefined ? {} : { targetLaneId }), ...(targetEffectId === undefined ? {} : { targetEffectId }), reason: 'Human requested cancellation.', modelId };
+    if (normalized === 'steer' || normalized === 'redirect')
+        return { schemaVersion: 1, decisionId: `rule:${inputId}`, inputId, agentId, action: 'steer', ...(targetLaneId === undefined ? {} : { targetLaneId }), reason: 'Human requested steering.', modelId };
+    if (normalized === 'spawn' || normalized === 'parallel')
+        return { schemaVersion: 1, decisionId: `rule:${inputId}`, inputId, agentId, action: 'spawn', reason: 'Human requested a concurrent interaction.', modelId };
+    if (normalized === 'defer' || normalized === 'later')
+        return { schemaVersion: 1, decisionId: `rule:${inputId}`, inputId, agentId, action: 'defer', reason: 'Human requested deferral.', modelId };
+    if (normalized === 'respond' || normalized === 'reply')
+        return { schemaVersion: 1, decisionId: `rule:${inputId}`, inputId, agentId, action: 'respond', ...(targetEffectId === undefined ? {} : { targetEffectId }), modelId };
+    return undefined;
+}

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;
@@ -305,6 +320,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 +333,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;
@@ -332,15 +352,32 @@ export declare class PulseRuntime {
     private hostCommandSeq;
     private factWaiters;
     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): void;
+    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;

package/dist/scheduler/runtime.js

@@ -24,6 +24,7 @@ import { prepareFindingPublication } from '../storage/findings.js';
 import { runtimeErrorFromCause } from '../core/errors.js';
 import { RuntimeToolRegistry } from '../tools/registry.js';
 import { SchedulerDecisionCoordinator, schedulerDecisionCandidateFromLane } from './decision.js';
+import { HumanArbitrationCoordinator, ruleHumanArbitration } from './human-arbitration.js';
 function encodeEffectExecution(execution) {
     const encoded = structuredClone(execution);
     const artifact = execution.artifact;
@@ -111,6 +112,19 @@ function validateHostCommand(command) {
         }
         return;
     }
+    if (value.type === 'human_input') {
+        if (typeof value.agentId !== 'string' || value.agentId.length === 0 || typeof value.inputId !== 'string' || value.inputId.length === 0)
+            throw new Error('INVALID_HOST_COMMAND');
+        if (value.targetEffectId !== undefined && (typeof value.targetEffectId !== 'string' || value.targetEffectId.length === 0))
+            throw new Error('INVALID_HOST_COMMAND');
+        try {
+            strictJsonValue(value.value);
+        }
+        catch {
+            throw new Error('INVALID_HOST_COMMAND_VALUE');
+        }
+        return;
+    }
     if (value.type === 'cancel' || value.type === 'cancel_effect') {
         if (typeof value.agentId !== 'string' || value.agentId.length === 0 || typeof value.reason !== 'string' || value.reason.length === 0)
             throw new Error('INVALID_HOST_COMMAND');
@@ -125,6 +139,31 @@ function validateHostCommand(command) {
     }
     throw new Error('INVALID_HOST_COMMAND');
 }
+function parseHumanArbitrationDecision(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const candidate = value;
+    const actions = new Set(['respond', 'steer', 'spawn', 'defer', 'cancel']);
+    if (typeof candidate.decisionId !== 'string' || typeof candidate.inputId !== 'string' || typeof candidate.agentId !== 'string' || typeof candidate.modelId !== 'string' || typeof candidate.action !== 'string' || !actions.has(candidate.action))
+        return undefined;
+    if (candidate.targetLaneId !== undefined && typeof candidate.targetLaneId !== 'string')
+        return undefined;
+    if (candidate.targetEffectId !== undefined && typeof candidate.targetEffectId !== 'string')
+        return undefined;
+    if (candidate.reason !== undefined && typeof candidate.reason !== 'string')
+        return undefined;
+    return {
+        schemaVersion: 1,
+        decisionId: candidate.decisionId,
+        inputId: candidate.inputId,
+        agentId: candidate.agentId,
+        action: candidate.action,
+        ...(candidate.targetLaneId === undefined ? {} : { targetLaneId: candidate.targetLaneId }),
+        ...(candidate.targetEffectId === undefined ? {} : { targetEffectId: candidate.targetEffectId }),
+        ...(candidate.reason === undefined ? {} : { reason: candidate.reason }),
+        modelId: candidate.modelId,
+    };
+}
 function artifactOutput(value) {
     if (value instanceof Uint8Array)
         return { mediaType: 'application/octet-stream', content: new Uint8Array(value) };
@@ -456,6 +495,7 @@ export class PulseRuntime {
     factInboxDedupeArchive;
     customExecutor;
     builtinHumanEffects;
+    humanInputProgram;
     enqueueSeq = 1;
     maxSteps;
     maxTickMs;
@@ -468,6 +508,10 @@ export class PulseRuntime {
     maxPreparedLLMs;
     effectSubmissionPreparer;
     schedulerDecisionCoordinator;
+    humanArbitrationCoordinator;
+    humanArbitrationModelId;
+    humanArbitrationRequestSeq = 1;
+    humanArbitrationRequests = new Map();
     schedulerDecisionConfig;
     schedulerDecisionModelId;
     schedulerDecisionMaxReorderDistance;
@@ -483,6 +527,13 @@ export class PulseRuntime {
     hostCommandSeq = 1;
     factWaiters = [];
     wakeScheduled = false;
+    /**
+     * 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.
+     */
+    wakeAfterDrain = false;
     inDrain = false;
     wakeError;
     tickBudget;
@@ -616,6 +667,8 @@ export class PulseRuntime {
             timeoutMs: this.schedulerDecisionConfig.decisionTimeoutMs,
             maxOutstanding: this.schedulerDecisionConfig.maxOutstandingDecisions,
         });
+        this.humanArbitrationModelId = config.humanArbitration?.model?.id;
+        this.humanArbitrationCoordinator = config.humanArbitration?.model === undefined ? undefined : new HumanArbitrationCoordinator(config.humanArbitration.model, config.humanArbitration.timeoutMs ?? 250);
         this.telemetryExporter = config.telemetryExporter;
         this.auditLogSink = config.auditLogSink;
         this.auditLogPrivacy = config.auditLogPrivacy;
@@ -639,6 +692,11 @@ export class PulseRuntime {
         this.syncStoragePolicy();
     }
     register(program) { this.programs.register(program); }
+    /** Register the program used for urgent, concurrent human interactions. */
+    setHumanInputProgram(program) {
+        this.register(program);
+        this.humanInputProgram = program;
+    }
     createAgent(goalOrRequest, program, agentId) {
         if (this.shuttingDown)
             throw new Error('RUNTIME_SHUTTING_DOWN');
@@ -750,6 +808,187 @@ export class PulseRuntime {
     }
     start(agentId) { if (!this.state.agents.has(agentId))
         throw new Error(`UNKNOWN_AGENT:${agentId}`); return new PulseSession(this, agentId); }
+    /** Accept external human input without waiting for the current Effect to settle. */
+    submitHumanInput(agentId, inputId, value, targetEffectId) {
+        if (!agentId)
+            throw new Error('INVALID_AGENT_ID');
+        if (!inputId)
+            throw new Error('INVALID_HUMAN_INPUT_ID');
+        strictJsonValue(value);
+        this.enqueueHostCommand({ type: 'human_input', agentId, inputId, value, ...(targetEffectId === undefined ? {} : { targetEffectId }) });
+    }
+    humanInputsFor(agentId) {
+        return [...this.state.humanInputs.values()].filter((input) => input.agentId === agentId).map((input) => structuredClone(input));
+    }
+    humanArbitrationRequest(agent, input) {
+        const lanes = [...this.state.lanes.values()].filter((lane) => lane.agentId === agent.id || this.ownsAgentForRuntime(lane.agentId, agent.id)).map((lane) => ({ laneId: lane.id, agentId: lane.agentId, status: lane.status, priority: lane.priority, ...(lane.goal ? { goal: lane.goal } : {}), ...(lane.activeWaitId === undefined ? {} : { activeWaitId: lane.activeWaitId }) }));
+        const effects = [...this.state.effects.values()].filter((effect) => effect.agentId === agent.id || this.ownsAgentForRuntime(effect.agentId, agent.id)).map((effect) => ({ effectId: effect.id, agentId: effect.agentId, laneId: effect.ownerLaneId, kind: effect.kind, state: effect.state, ...(effect.sideEffectPolicy === undefined ? {} : { sideEffectPolicy: effect.sideEffectPolicy }), sideEffectState: effect.sideEffectState }));
+        const llmLimit = this.state.maxRunning.llm;
+        const availableLLMSlots = Number.isFinite(llmLimit) ? Math.max(0, llmLimit - this.runningCount('llm') - 1) : Number.POSITIVE_INFINITY;
+        return { schemaVersion: 1, decisionId: `human-decision-${this.sessionId}-${this.humanArbitrationRequestSeq}`, agentId: agent.id, input: structuredClone(input), lanes, effects, availableLLMSlots };
+    }
+    ownsAgentForRuntime(candidateAgentId, ancestorAgentId) {
+        let current = this.state.agents.get(candidateAgentId);
+        const seen = new Set();
+        while (current && !seen.has(current.id)) {
+            if (current.id === ancestorAgentId)
+                return true;
+            seen.add(current.id);
+            current = current.parentAgentId === undefined ? undefined : this.state.agents.get(current.parentAgentId);
+        }
+        return false;
+    }
+    commitHumanInputDecision(record, decision, eventType = 'human.input.decided') {
+        const next = structuredClone(record);
+        next.decision = decision.action;
+        if (decision.reason === undefined)
+            delete next.decisionReason;
+        else
+            next.decisionReason = decision.reason;
+        next.decisionModelId = decision.modelId;
+        next.decidedAt = this.state.now;
+        const event = { type: eventType, agentId: record.agentId, data: { inputId: record.id, action: decision.action, modelId: decision.modelId, ...(decision.reason === undefined ? {} : { reason: decision.reason }), ...(decision.targetLaneId === undefined ? {} : { targetLaneId: decision.targetLaneId }), ...(decision.targetEffectId === undefined ? {} : { targetEffectId: decision.targetEffectId }) } };
+        const mutations = [{ op: 'setHumanInput', inputId: record.id, record: next }, { op: 'appendEvent', event }];
+        this.assertStorageAdmission(mutations);
+        commitMutationTransaction(this.state, this.mutationLog, `human-input:${record.id}:decision:${decision.action}`, mutations, this.state.now, this.sessionId);
+        Object.assign(record, next);
+        this.state.humanInputs.set(record.id, record);
+    }
+    applyHumanArbitrationDecision(decision) {
+        const record = this.state.humanInputs.get(decision.inputId);
+        if (!record || record.agentId !== decision.agentId || record.status !== 'pending')
+            return false;
+        const targetEffectId = decision.targetEffectId ?? record.targetEffectId;
+        if (decision.action === 'respond') {
+            if (targetEffectId !== undefined) {
+                const effect = this.state.effects.get(targetEffectId);
+                if (!effect || effect.agentId !== record.agentId || effect.kind !== 'human' || effect.outcome)
+                    return false;
+                this.commitHumanInputDecision(record, decision);
+                record.status = 'consumed';
+                const consumed = structuredClone(record);
+                const mutations = [{ op: 'setHumanInput', inputId: record.id, record: consumed }];
+                this.assertStorageAdmission(mutations);
+                commitMutationTransaction(this.state, this.mutationLog, `human-input:${record.id}:respond`, mutations, this.state.now, this.sessionId);
+                Object.assign(record, consumed);
+                this.completeEffect(effect.id, { value: record.value }, 'succeeded');
+                return true;
+            }
+            const next = structuredClone(record);
+            next.status = 'consumed';
+            this.commitHumanInputDecision(record, decision, 'human.input.responded');
+            const mutations = [{ op: 'setHumanInput', inputId: record.id, record: next }];
+            this.assertStorageAdmission(mutations);
+            commitMutationTransaction(this.state, this.mutationLog, `human-input:${record.id}:responded`, mutations, this.state.now, this.sessionId);
+            Object.assign(record, next);
+            this.state.humanInputs.set(record.id, record);
+            return true;
+        }
+        if (decision.action === 'steer') {
+            const lane = this.state.lanes.get(decision.targetLaneId ?? this.state.agents.get(record.agentId)?.rootLaneId ?? '');
+            if (!lane || lane.agentId !== record.agentId || ['succeeded', 'failed', 'cancelled'].includes(lane.status)) {
+                const deferred = structuredClone(record);
+                deferred.status = 'deferred';
+                this.commitHumanInputDecision(record, { ...decision, action: 'defer', reason: decision.reason ?? 'Target lane is no longer active.' }, 'human.input.deferred');
+                Object.assign(record, deferred);
+                return true;
+            }
+            const nextLane = structuredClone(lane);
+            nextLane.pendingHumanInputs = [...(nextLane.pendingHumanInputs ?? []), structuredClone(record)];
+            nextLane.priority = Math.max(nextLane.priority, 2);
+            nextLane.version++;
+            const next = structuredClone(record);
+            next.status = 'consumed';
+            next.handledByLaneId = lane.id;
+            this.commitHumanInputDecision(record, decision);
+            const mutations = [{ op: 'setHumanInput', inputId: record.id, record: next }, { op: 'setLane', laneId: lane.id, record: nextLane }, { op: 'appendEvent', event: { type: 'human.input.steered', agentId: record.agentId, laneId: lane.id, data: { inputId: record.id, priority: 'human' } } }];
+            this.assertStorageAdmission(mutations);
+            commitMutationTransaction(this.state, this.mutationLog, `human-input:${record.id}:steer`, mutations, this.state.now, this.sessionId);
+            Object.assign(record, next);
+            this.state.humanInputs.set(record.id, record);
+            Object.assign(lane, nextLane);
+            this.state.lanes.set(lane.id, lane);
+            if (lane.status === 'ready')
+                this.enqueueReadyItem(readyItemFromLane(lane));
+            return true;
+        }
+        if (decision.action === 'spawn') {
+            if (this.humanInputProgram === undefined) {
+                const deferred = { ...decision, action: 'defer', reason: decision.reason ?? 'No Human interaction program is registered.' };
+                return this.applyHumanArbitrationDecision(deferred);
+            }
+            try {
+                const child = this.createAgent({ goal: `Human input: ${typeof record.value === 'string' ? record.value : JSON.stringify(record.value)}`, program: this.humanInputProgram, priority: 'urgent', parentAgentId: record.agentId, warmStart: { agentId: record.agentId, globalVersion: 'latest', include: 'facts_and_findings' } });
+                const next = structuredClone(record);
+                next.status = 'consumed';
+                next.handledByLaneId = child.laneId;
+                this.commitHumanInputDecision(record, decision);
+                const mutations = [{ op: 'setHumanInput', inputId: record.id, record: next }, { op: 'appendEvent', event: { type: 'human.input.dispatched', agentId: record.agentId, laneId: child.laneId, data: { inputId: record.id, decision: 'spawn', childAgentId: child.agentId } } }];
+                this.assertStorageAdmission(mutations);
+                commitMutationTransaction(this.state, this.mutationLog, `human-input:${record.id}:spawn`, mutations, this.state.now, this.sessionId);
+                Object.assign(record, next);
+                this.state.humanInputs.set(record.id, record);
+            }
+            catch (cause) {
+                return this.applyHumanArbitrationDecision({ ...decision, action: 'defer', reason: cause instanceof Error ? cause.message : String(cause) });
+            }
+            return true;
+        }
+        if (decision.action === 'cancel') {
+            const targetEffect = targetEffectId === undefined ? undefined : this.state.effects.get(targetEffectId);
+            if (targetEffect && (targetEffect.agentId !== record.agentId || targetEffect.outcome))
+                return false;
+            this.commitHumanInputDecision(record, decision);
+            const next = structuredClone(record);
+            next.status = 'consumed';
+            const mutations = [{ op: 'setHumanInput', inputId: record.id, record: next }];
+            this.assertStorageAdmission(mutations);
+            commitMutationTransaction(this.state, this.mutationLog, `human-input:${record.id}:cancel`, mutations, this.state.now, this.sessionId);
+            Object.assign(record, next);
+            this.state.humanInputs.set(record.id, record);
+            if (targetEffect)
+                this.cancelEffect(targetEffect.id, targetEffect.cancelGraceMs ?? 0, decision.reason ?? 'HUMAN_CANCELLED');
+            else
+                this.cancelAgent(record.agentId, decision.reason ?? 'HUMAN_CANCELLED');
+            return true;
+        }
+        const deferred = structuredClone(record);
+        deferred.status = 'deferred';
+        this.commitHumanInputDecision(record, decision, 'human.input.deferred');
+        const mutations = [{ op: 'setHumanInput', inputId: record.id, record: deferred }];
+        this.assertStorageAdmission(mutations);
+        commitMutationTransaction(this.state, this.mutationLog, `human-input:${record.id}:defer`, mutations, this.state.now, this.sessionId);
+        Object.assign(record, deferred);
+        this.state.humanInputs.set(record.id, record);
+        return true;
+    }
+    requestHumanArbitration(agent, input) {
+        const coordinator = this.humanArbitrationCoordinator;
+        if (!coordinator)
+            return false;
+        const request = this.humanArbitrationRequest(agent, input);
+        const requestId = request.decisionId;
+        this.humanArbitrationRequestSeq++;
+        this.humanArbitrationRequests.set(requestId, { agentId: agent.id, inputId: input.id });
+        const accepted = coordinator.request(request, (decision) => {
+            this.humanArbitrationRequests.delete(requestId);
+            if (decision.decisionId !== requestId || decision.inputId !== input.id || decision.agentId !== agent.id || decision.modelId !== this.humanArbitrationModelId)
+                return;
+            try {
+                this.enqueueFact({ type: 'human_arbitration', decision: strictJsonValue(decision) }, `human-arbitration:${requestId}`, true);
+            }
+            catch { /* malformed model output is handled as a deferred input */ }
+        }, () => {
+            this.humanArbitrationRequests.delete(requestId);
+            try {
+                this.enqueueFact({ type: 'human_arbitration', decision: strictJsonValue({ schemaVersion: 1, decisionId: requestId, inputId: input.id, agentId: agent.id, action: 'defer', reason: 'Human arbitration timed out.', modelId: this.humanArbitrationModelId ?? 'model' }) }, `human-arbitration:${requestId}:timeout`, true);
+            }
+            catch { /* runtime shutdown */ }
+        });
+        if (!accepted)
+            this.humanArbitrationRequests.delete(requestId);
+        return accepted;
+    }
     requestCancel(agentId, reason = 'USER_REQUESTED') {
         if (!agentId)
             throw new Error('INVALID_AGENT_ID');
@@ -1156,13 +1395,13 @@ export class PulseRuntime {
         }
         this.mutationLog.append(transactionId, mutations, this.state.now);
     }
-    enqueueFact(fact, eventId) {
+    enqueueFact(fact, eventId, urgent = false) {
         const candidateInbox = FactInbox.fromSnapshot(this.factInbox.snapshot());
-        if (!candidateInbox.enqueue(fact, eventId))
+        if (!(urgent ? candidateInbox.enqueueUrgent(fact, eventId) : candidateInbox.enqueue(fact, eventId)))
             return false;
         const candidatePolicy = this.storagePolicy.clone();
         this.syncStoragePolicy(candidatePolicy, this.state, candidateInbox);
-        const envelope = this.factInbox.enqueue(fact, eventId);
+        const envelope = urgent ? this.factInbox.enqueueUrgent(fact, eventId) : this.factInbox.enqueue(fact, eventId);
         if (!envelope)
             return false;
         this.syncStoragePolicy();
@@ -1175,7 +1414,8 @@ export class PulseRuntime {
     enqueueHostCommand(command) {
         validateHostCommand(command);
         const eventId = `host-command-${this.hostCommandSeq}`;
-        if (!this.enqueueFact(command, eventId))
+        const urgent = command.type === 'human_input' || command.type === 'reply' || command.type === 'cancel' || command.type === 'cancel_effect';
+        if (!this.enqueueFact(command, eventId, urgent))
             return;
         this.hostCommandSeq++;
     }
@@ -1193,7 +1433,12 @@ export class PulseRuntime {
         this.enqueueFact(fact, `effect-reconcile:${effect.id}:${effect.attemptId}:${status}`);
     }
     scheduleWake(force = false) {
-        if (this.wakeScheduled || this.inDrain)
+        if (this.inDrain) {
+            if (force)
+                this.wakeAfterDrain = true;
+            return;
+        }
+        if (this.wakeScheduled)
             return;
         if (!force && this.factInbox.size === 0)
             return;
@@ -1211,7 +1456,9 @@ export class PulseRuntime {
             }
             finally {
                 this.inDrain = false;
-                if (this.wakeError === undefined && (this.factInbox.size > 0 || this.hasPendingTickCleanup()))
+                const wakeAfterDrain = this.wakeAfterDrain;
+                this.wakeAfterDrain = false;
+                if (this.wakeError === undefined && (wakeAfterDrain || this.factInbox.size > 0 || this.hasPendingTickCleanup()))
                     this.scheduleWake(true);
             }
         });
@@ -1409,6 +1656,17 @@ export class PulseRuntime {
                 else if (envelope.fact.type === 'scheduler_decision') {
                     commandApplied = this.applySchedulerDecision(envelope.fact);
                 }
+                else if (envelope.fact.type === 'human_arbitration') {
+                    const decision = parseHumanArbitrationDecision(envelope.fact.decision);
+                    if (decision !== undefined)
+                        commandApplied = this.applyHumanArbitrationDecision(decision);
+                    else {
+                        const raw = envelope.fact.decision && typeof envelope.fact.decision === 'object' && !Array.isArray(envelope.fact.decision) ? envelope.fact.decision : {};
+                        const record = typeof raw.inputId === 'string' ? this.state.humanInputs.get(raw.inputId) : undefined;
+                        if (record && record.status === 'pending')
+                            commandApplied = this.applyHumanArbitrationDecision({ schemaVersion: 1, decisionId: typeof raw.decisionId === 'string' ? raw.decisionId : `invalid:${record.id}`, inputId: record.id, agentId: record.agentId, action: 'defer', reason: 'Human arbitration returned an invalid decision.', modelId: 'runtime-safety' });
+                    }
+                }
                 else if (envelope.fact.type === 'effect_completion') {
                     if (envelope.fact.dispatchError !== undefined)
                         this.tryEmit({ type: 'effect.dispatch_failed', effectId: envelope.fact.effectId, data: envelope.fact.dispatchError });
@@ -1434,6 +1692,43 @@ export class PulseRuntime {
                         commandApplied = true;
                     }
                 }
+                else if (envelope.fact.type === 'human_input') {
+                    const agent = this.state.agents.get(envelope.fact.agentId);
+                    if (!agent) {
+                        this.rejectHostCommand(envelope.eventId, 'AGENT_NOT_FOUND');
+                        commandApplied = true;
+                    }
+                    else if (this.state.humanInputs.has(envelope.fact.inputId)) {
+                        this.tryEmit({ type: 'human.input.duplicate', agentId: agent.id, data: { inputId: envelope.fact.inputId } });
+                        this.emit({ type: 'command.applied', data: { eventId: envelope.eventId, duplicate: true } });
+                        commandApplied = true;
+                    }
+                    else {
+                        const target = envelope.fact.targetEffectId === undefined ? undefined : this.state.effects.get(envelope.fact.targetEffectId);
+                        if (target !== undefined && (target.agentId !== agent.id || target.kind !== 'human' || target.outcome !== undefined)) {
+                            this.rejectHostCommand(envelope.eventId, target.agentId !== agent.id ? 'EFFECT_NOT_OWNED' : 'EFFECT_NOT_REPLYABLE');
+                            commandApplied = true;
+                        }
+                        else {
+                            const record = { id: envelope.fact.inputId, agentId: agent.id, value: structuredClone(envelope.fact.value), receivedAt: this.state.now, status: 'pending', ...(target === undefined ? {} : { targetEffectId: target.id }) };
+                            const event = { type: 'human.input.received', agentId: agent.id, ...(target === undefined ? {} : { effectId: target.id }), data: { inputId: record.id, value: record.value, priority: 'human', ...(target === undefined ? {} : { targetEffectId: target.id }) } };
+                            const mutations = [{ op: 'setHumanInput', inputId: record.id, record }, { op: 'appendEvent', event }, { op: 'appendEvent', event: { type: 'command.applied', data: { eventId: envelope.eventId } } }];
+                            this.assertStorageAdmission(mutations);
+                            commitMutationTransaction(this.state, this.mutationLog, `human-input:${record.id}`, mutations, this.state.now, this.sessionId);
+                            commandApplied = true;
+                            if (target !== undefined) {
+                                this.applyHumanArbitrationDecision({ schemaVersion: 1, decisionId: `target:${record.id}`, inputId: record.id, agentId: agent.id, action: 'respond', targetEffectId: target.id, modelId: 'target-effect' });
+                            }
+                            else {
+                                const rule = ruleHumanArbitration(record.value, agent.id, record.id);
+                                if (rule !== undefined)
+                                    this.applyHumanArbitrationDecision(rule);
+                                else if (!this.requestHumanArbitration(agent, record) && this.humanInputProgram !== undefined)
+                                    this.applyHumanArbitrationDecision({ schemaVersion: 1, decisionId: `default:${record.id}`, inputId: record.id, agentId: agent.id, action: 'spawn', modelId: 'runtime-default' });
+                            }
+                        }
+                    }
+                }
                 else if (envelope.fact.type === 'reply') {
                     const effect = this.state.effects.get(envelope.fact.effectId);
                     if (effect?.agentId === envelope.fact.agentId && effect.kind === 'human' && !effect.outcome)
@@ -1458,7 +1753,7 @@ export class PulseRuntime {
                     else
                         commandApplied = this.cancelEffect(envelope.fact.effectId, 0, envelope.fact.reason, [{ op: 'appendEvent', event: { type: 'command.applied', data: { eventId: envelope.eventId } } }]);
                 }
-                else {
+                else if (envelope.fact.type === 'set_lane_priority') {
                     const lane = this.state.lanes.get(envelope.fact.laneId);
                     if (!lane) {
                         this.rejectHostCommand(envelope.eventId, 'LANE_NOT_FOUND');
@@ -1484,6 +1779,9 @@ export class PulseRuntime {
                         commandApplied = true;
                     }
                 }
+                else {
+                    commandApplied = false;
+                }
                 if (!commandApplied && envelope.fact.type !== 'effect_completion' && envelope.fact.type !== 'scheduler_decision')
                     this.emit({ type: 'command.applied', data: { eventId: envelope.eventId } });
             }
@@ -1528,7 +1826,7 @@ export class PulseRuntime {
                 continue;
             }
             let output;
-            const stepContext = { lane: stepLane, state: structuredClone(this.state), ...(lane.pendingResumeInput ? { resumeInput: structuredClone(lane.pendingResumeInput) } : {}), now: this.state.now, observe: (event) => { this.observationInbox.enqueue({ ...event, agentId: lane.agentId, laneId: lane.id, timestamp: this.state.now }); } };
+            const stepContext = { lane: stepLane, state: structuredClone(this.state), ...(lane.pendingResumeInput ? { resumeInput: structuredClone(lane.pendingResumeInput) } : {}), ...(lane.pendingHumanInputs?.length ? { humanInputs: structuredClone(lane.pendingHumanInputs) } : {}), now: this.state.now, observe: (event) => { this.observationInbox.enqueue({ ...event, agentId: lane.agentId, laneId: lane.id, timestamp: this.state.now }); } };
             try {
                 output = withPureStepGuard(() => lane.series || program.seriesMember ? this.seriesStep(program, stepContext, lane.series) : program.step(stepContext));
             }
@@ -1602,6 +1900,7 @@ export class PulseRuntime {
                         return mutation;
                     const nextLane = structuredClone(mutation.record);
                     delete nextLane.consecutiveControlErrors;
+                    delete nextLane.pendingHumanInputs;
                     replaceResumeInput(nextLane, undefined);
                     nextLane.progressWatchdog = watchdog.state;
                     return { ...mutation, record: nextLane };
@@ -1791,6 +2090,8 @@ export class PulseRuntime {
     async shutdown(timeoutMs = 5_000) {
         this.shuttingDown = true;
         this.schedulerDecisionCoordinator?.cancel();
+        this.humanArbitrationCoordinator?.cancel();
+        this.humanArbitrationRequests.clear();
         this.schedulerDecisionRequests.clear();
         this.schedulerDecisionCache = undefined;
         for (const agent of this.state.agents.values())
@@ -2026,6 +2327,18 @@ export class PulseRuntime {
     hasPendingHostInteraction(agentId) { return [...this.state.effects.values()].some((effect) => effect.kind === 'human' && !effect.outcome && (agentId === undefined || effect.agentId === agentId)); }
     waitForFact() { return new Promise((resolve) => this.factWaiters.push(resolve)); }
     completeFinishedChildAgents() {
+        // Human interaction Agents are detached from the main Lane rather than
+        // represented by an agent Effect. Settle their Agent record when the root
+        // Lane reaches a terminal state so session streams can close correctly.
+        for (const child of this.state.agents.values()) {
+            if (child.parentAgentId === undefined || ['succeeded', 'failed', 'cancelled'].includes(child.state ?? ''))
+                continue;
+            const root = this.state.lanes.get(child.rootLaneId);
+            if (!root || !['succeeded', 'failed', 'cancelled'].includes(root.status))
+                continue;
+            const status = root.status === 'succeeded' ? 'succeeded' : root.status === 'cancelled' ? 'cancelled' : 'failed';
+            this.commitAgentState(child.id, status, `agent:${child.id}:interaction-settled:${root.version}`);
+        }
         for (const effect of this.state.effects.values()) {
             if (effect.kind !== 'agent' || !effect.childAgentId || effect.outcome)
                 continue;
@@ -2620,7 +2933,8 @@ export class PulseRuntime {
             return { id: lane.id, agentId: lane.agentId, status: lane.status, cancelReason: lane.cancelReason ?? null, failure: lane.failure?.error ?? null, goal: lane.goal, basePriority: lane.priority, effectivePriority: ready?.effectivePriority ?? lane.priority, queueWaitMs: ready ? Math.max(0, this.state.now - lane.readySince) : 0, blockedBy, activeWaitId: lane.activeWaitId ?? null, lastEventSeq: lastEvent('lane', lane.id), watchdog: lane.progressWatchdog ?? null, consecutiveControlErrors: lane.consecutiveControlErrors ?? 0, lastInterventionReason: lane.progressWatchdog?.lastReason ?? null, unresolvedEffectIds: lane.unresolvedEffectIds ?? [] };
         });
         const effects = [...this.state.effects.values()].filter((effect) => laneId === undefined || effect.ownerLaneId === laneId).map((effect) => ({ id: effect.id, state: effect.state, executionState: effect.executionState, sideEffectState: effect.sideEffectState, attemptId: effect.attemptId, inheritedFloor: effect.inheritedFloor ?? null, deadlineAt: effect.deadlineAt ?? null, lastEventSeq: lastEvent('effect', effect.id), preparation: effect.preparation ?? null, metadata: latestEffectMetadata(effect.id) }));
-        return { now: this.state.now, lanes, effects, preparation: { preparing: this.preparingLLMs.size, prepared: [...this.state.effects.values()].filter((effect) => effect.state === 'queued' && effect.preparation?.state === 'prepared').length, maxPreparing: this.maxPreparingLLMs, maxPrepared: this.maxPreparedLLMs }, quarantine: this.quarantine.unresolvedEffectIds };
+        const humanInputs = [...this.state.humanInputs.values()].filter((input) => laneId === undefined || input.agentId === this.state.lanes.get(laneId)?.agentId).map((input) => structuredClone(input));
+        return { now: this.state.now, lanes, effects, humanInputs, preparation: { preparing: this.preparingLLMs.size, prepared: [...this.state.effects.values()].filter((effect) => effect.state === 'queued' && effect.preparation?.state === 'prepared').length, maxPreparing: this.maxPreparingLLMs, maxPrepared: this.maxPreparedLLMs }, quarantine: this.quarantine.unresolvedEffectIds };
     }
     retryEffect(effectId, delayMs) {
         const effect = this.state.effects.get(effectId);
@@ -2709,6 +3023,13 @@ export class PulseRuntime {
         // Higher effective priority (max of own priority and inherited floor) dispatches first, matching ReadyQueue semantics.
         const effectivePriority = (effect) => Math.max(effect.schedulePriority ?? 0, effect.inheritedFloor ?? Number.NEGATIVE_INFINITY);
         const queued = [...this.state.effects.values()].filter((effect) => effect.state === 'queued' && !this.executions.has(effect.id)).sort((a, b) => (effectivePriority(b) - effectivePriority(a)) || a.id.localeCompare(b.id));
+        const llmLimit = () => {
+            const configured = this.state.maxRunning.llm;
+            if ((this.humanInputProgram === undefined && this.humanArbitrationCoordinator === undefined) || !Number.isFinite(configured))
+                return configured;
+            const hasUrgentHumanWork = queued.some((candidate) => candidate.kind === 'llm' && effectivePriority(candidate) >= 2);
+            return hasUrgentHumanWork ? configured : Math.max(0, configured - 1);
+        };
         for (const effect of queued) {
             if (this.tickBudget && !this.tickBudget.canStart())
                 break;
@@ -2716,7 +3037,7 @@ export class PulseRuntime {
                 continue;
             if (effect.kind === 'llm' && !this.prepareLLMEffect(effect))
                 continue;
-            if (effect.concurrencyClass !== 'none' && this.runningCount(effect.concurrencyClass) >= this.state.maxRunning[effect.concurrencyClass])
+            if (effect.concurrencyClass !== 'none' && this.runningCount(effect.concurrencyClass) >= (effect.concurrencyClass === 'llm' ? llmLimit() : this.state.maxRunning[effect.concurrencyClass]))
                 continue;
             const budgetError = this.budgetRejection(effect);
             if (budgetError) {

package/dist/storage/session.d.ts

@@ -1,4 +1,4 @@
-import type { AgentRecord, ArtifactRecord, EffectRecord, JsonValue, LaneRecord, MergeProposal, PrivacyLabel, PrivacyMetadata, ResultRecord, RuntimeEvent, RuntimeState, WaitRecord, ToolCallCorrelation } from '../core/types.js';
+import type { AgentRecord, ArtifactRecord, EffectRecord, JsonValue, LaneRecord, MergeProposal, PrivacyLabel, PrivacyMetadata, ResultRecord, RuntimeEvent, RuntimeState, WaitRecord, ToolCallCorrelation, HumanInputRecord } from '../core/types.js';
 export interface SessionSnapshot {
     schemaVersion: 1;
     state: {
@@ -18,6 +18,7 @@ export interface SessionSnapshot {
         artifacts?: Array<[string, ArtifactRecord]>;
         toolCallCorrelations?: Array<[string, ToolCallCorrelation]>;
         mergeProposals: Array<[string, MergeProposal]>;
+        humanInputs?: Array<[string, HumanInputRecord]>;
         events: RuntimeEvent[];
         eventsCompactedThrough?: number;
         nextIds: RuntimeState['nextIds'];

package/dist/storage/session.js

@@ -304,6 +304,17 @@ function validateStateConfiguration(value) {
         throw new Error('INVALID_SESSION_SNAPSHOT');
     if (value.trustedSanitizerIds !== undefined && (!Array.isArray(value.trustedSanitizerIds) || new Set(value.trustedSanitizerIds).size !== value.trustedSanitizerIds.length || value.trustedSanitizerIds.some((id) => typeof id !== 'string' || id.length === 0)))
         throw new Error('INVALID_SESSION_SNAPSHOT');
+    if (value.humanInputs !== undefined) {
+        const ids = new Set();
+        for (const entry of value.humanInputs) {
+            if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== 'string' || entry[0].length === 0 || ids.has(entry[0]))
+                throw new Error('INVALID_SESSION_SNAPSHOT');
+            const input = entry[1];
+            if (!input || input.id !== entry[0] || typeof input.agentId !== 'string' || input.agentId.length === 0 || !['pending', 'consumed', 'deferred'].includes(input.status) || typeof input.receivedAt !== 'number' || !Number.isFinite(input.receivedAt))
+                throw new Error('INVALID_SESSION_SNAPSHOT');
+            ids.add(entry[0]);
+        }
+    }
 }
 export function exportRuntimeState(state) {
     return {
@@ -318,6 +329,7 @@ export function exportRuntimeState(state) {
             artifacts: [...state.artifacts.entries()].map(([ref, artifact]) => [ref, structuredClone(artifact)]),
             toolCallCorrelations: [...state.toolCallCorrelations.entries()].map(([id, correlation]) => [id, structuredClone(correlation)]),
             mergeProposals: [...state.mergeProposals.entries()].map(([id, proposal]) => [id, structuredClone(proposal)]),
+            humanInputs: [...state.humanInputs.entries()].map(([id, input]) => [id, structuredClone(input)]),
             events: state.events.map((event) => normalizeRuntimeEvent(event, event.seq, { sessionId: event.sessionId, timestamp: event.timestamp })),
             ...(state.eventsCompactedThrough === undefined ? {} : { eventsCompactedThrough: state.eventsCompactedThrough }),
             nextIds: { ...state.nextIds },
@@ -440,6 +452,8 @@ export function importRuntimeState(snapshot) {
         state.toolCallCorrelations.set(id, structuredClone(correlation));
     for (const [id, proposal] of value.state.mergeProposals ?? [])
         state.mergeProposals.set(id, structuredClone(proposal));
+    for (const [id, input] of value.state.humanInputs ?? [])
+        state.humanInputs.set(id, structuredClone(input));
     state.events = value.state.events.map((event) => normalizeRuntimeEvent(event, event.seq, { sessionId: event.sessionId, timestamp: event.timestamp }));
     if (value.state.eventsCompactedThrough !== undefined)
         state.eventsCompactedThrough = value.state.eventsCompactedThrough;

package/dist/transitions/validate.js

@@ -7,7 +7,7 @@ import { ContextBuilder, contentHash, estimateHistoryTokens, hasUnsafePathSegmen
 const isLocal = (value) => 'local' in value;
 const clone = (value) => structuredClone(value);
 const resultMetadata = (value) => ({ sizeBytes: Buffer.byteLength(stableSerialize(value), 'utf8'), contentHash: contentHash(value) });
-const laneCopy = (lane) => ({ ...lane, resume: clone(lane.resume), context: clone(lane.context), ...(lane.visibleResultRefs === undefined ? {} : { visibleResultRefs: new Set(lane.visibleResultRefs) }), children: new Set(lane.children), ownedEffectIds: new Set(lane.ownedEffectIds), ...(lane.pendingResumeInput === undefined ? {} : { pendingResumeInput: clone(lane.pendingResumeInput) }), ...(lane.pendingControlProposals === undefined ? {} : { pendingControlProposals: clone(lane.pendingControlProposals) }), ...(lane.pendingOutcome === undefined ? {} : { pendingOutcome: clone(lane.pendingOutcome) }) });
+const laneCopy = (lane) => ({ ...lane, resume: clone(lane.resume), context: clone(lane.context), ...(lane.visibleResultRefs === undefined ? {} : { visibleResultRefs: new Set(lane.visibleResultRefs) }), children: new Set(lane.children), ownedEffectIds: new Set(lane.ownedEffectIds), ...(lane.pendingResumeInput === undefined ? {} : { pendingResumeInput: clone(lane.pendingResumeInput) }), ...(lane.pendingHumanInputs === undefined ? {} : { pendingHumanInputs: clone(lane.pendingHumanInputs) }), ...(lane.pendingControlProposals === undefined ? {} : { pendingControlProposals: clone(lane.pendingControlProposals) }), ...(lane.pendingOutcome === undefined ? {} : { pendingOutcome: clone(lane.pendingOutcome) }) });
 function isRuntimeJsonValue(value, seen = new Set()) {
     if (value === null || typeof value === 'string' || typeof value === 'boolean')
         return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunterzhu/pulse-runtime",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "repository": {
     "type": "git",
     "url": "https://github.com/zhuhengtan/Pulse"