@hunterzhu/pulse-runtime 0.1.5 → 0.1.7

package/dist/dsl/program.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { globalContextRef, laneContextRef } from '../core/types.js';
 import { createDraftProxy } from './context-proxy.js';
-import { contentHash, stableSerialize } from '../context/builder.js';
+import { assertDslInstructionSize, contentHash, stableSerialize } from '../context/builder.js';
 function target(step, fallback) {
     if (typeof step === 'string')
         return { step };
@@ -29,9 +29,7 @@ function scalarProjection(value) {
     return Object.fromEntries(Object.entries(value).filter(([, child]) => child === null || typeof child === 'string' || typeof child === 'number' || typeof child === 'boolean').map(([key, child]) => [key, child]));
 }
 function boundedInstruction(value) {
-    if (Buffer.byteLength(value, 'utf8') > 2048)
-        throw Object.assign(new Error('Instruction exceeds the 2 KB DSL limit.'), { code: 'INSTRUCTION_TOO_LARGE', retryable: false });
-    return value;
+    return assertDslInstructionSize(value);
 }
 function programLLMInput(config, input) {
     return { ...input, ...(config.system === undefined ? {} : { system: config.system }), ...(config.toolSet === undefined ? {} : { toolSetId: config.toolSet }) };
@@ -201,6 +199,16 @@ function collectResumeResultRefs(input, refs) {
             refs.add(ref);
     }
 }
+/** Return a wait resolution even when the scheduler wrapped it in a control error. */
+function waitResolution(input) {
+    if (!input)
+        return undefined;
+    if (input.type === 'wait')
+        return input.resolution;
+    if (input.type === 'control_error')
+        return waitResolution(input.original);
+    return undefined;
+}
 function annotateAction(action, derivedFrom) {
     if (!derivedFrom.length)
         return action;
@@ -213,7 +221,7 @@ function annotateAction(action, derivedFrom) {
 const resultReaders = new WeakMap();
 function readResult(ctx, ref) { return resultReaders.get(ctx)?.(ref); }
 function waitFailure(ctx) {
-    const resolution = ctx.resumeInput?.type === 'wait' ? ctx.resumeInput.resolution : undefined;
+    const resolution = waitResolution(ctx.resumeInput);
     if (!resolution)
         return undefined;
     let dependencyError;
@@ -222,6 +230,10 @@ function waitFailure(ctx) {
             dependencyError = dependency.outcome.error;
             break;
         }
+        if (dependency.state !== 'pending' && dependency.outcome.status === 'cancelled') {
+            dependencyError = dependency.outcome.error ?? { code: 'EFFECT_CANCELLED', message: dependency.outcome.reason ?? 'A waited effect was cancelled.', retryable: false };
+            break;
+        }
     }
     if (dependencyError)
         return dependencyError;
@@ -288,7 +300,7 @@ function makeContext(context, initialState) {
         delta = { target: 'global', baseVersion: agent?.latestGlobalVersion ?? 0, sourceLaneId: context.lane.id, ops: clone(ops), ...(value.privacy === undefined ? {} : { privacy: value.privacy }), proposal: value.proposal };
     };
     const ctx = {
-        lane: context.lane, goal: context.lane.goal, global, globalVersion, laneState: readonlyState, history, now: context.now, ...(context.lane.progressWatchdog === undefined ? {} : { watchdog: context.lane.progressWatchdog }), ...(context.resumeInput ? { resumeInput: context.resumeInput } : {}),
+        lane: context.lane, goal: context.lane.goal, global, globalVersion, laneState: readonlyState, history, now: context.now, ...(context.lane.progressWatchdog === undefined ? {} : { watchdog: context.lane.progressWatchdog }), ...(context.resumeInput ? { resumeInput: context.resumeInput } : {}), ...(context.humanInputs?.length ? { humanInputs: context.humanInputs } : {}),
         results: { meta: resultMeta, summary: (ref) => { if (context.state.results.has(ref) && resultVisible(context, ref))
                 derivedRefs.add(ref); return resultMeta(ref)?.summary; } },
         mergeProposals: [...context.state.mergeProposals.values()].filter((proposal) => proposal.agentId === context.lane.agentId).map((proposal) => { for (const ref of proposal.delta.derivedFrom ?? [])
@@ -371,16 +383,34 @@ export class StepBuilder {
     }
     addReActLoopStep(name, options) {
         this.compactionBoundaries.add(name);
+        // The decode step handles ReAct compaction after consuming the current
+        // model result. This preserves the wait's result references while the
+        // summary is being generated.
         const readTurns = (ctx) => { const sdk = sdkLocals(ctx.lane.resume.locals); const turn = sdk[`${name}Turns`]; return typeof turn === 'number' && Number.isInteger(turn) && turn >= 0 ? turn : 0; };
         const inputKey = `${name}Inputs`;
         const readInputs = (ctx) => { const value = sdkLocals(ctx.lane.resume.locals)[inputKey]; return value && typeof value === 'object' && !Array.isArray(value) ? value : {}; };
-        const writeTurns = (ctx, turns, inputs = readInputs(ctx)) => { const locals = ctx.lane.resume.locals; const base = locals && typeof locals === 'object' && !Array.isArray(locals) ? locals : {}; return { ...base, $sdk: { ...sdkLocals(locals), [`${name}Turns`]: turns, [inputKey]: asJson(inputs) } }; };
-        const resultRefFromWait = (ctx) => { const dependency = ctx.resumeInput?.type === 'wait' ? Object.values(ctx.resumeInput.resolution.dependencies)[0] : undefined; return dependency?.state === 'settled' ? dependency.outcome.resultRef : undefined; };
-        const resultRefsFromWait = (ctx) => ctx.resumeInput?.type === 'wait' ? Object.values(ctx.resumeInput.resolution.dependencies).flatMap((dependency) => dependency.state === 'settled' && dependency.outcome.resultRef ? [dependency.outcome.resultRef] : []) : [];
+        const writeTurns = (ctx, turns, inputs = readInputs(ctx)) => { const { conversation: _conversation, ...persistedInputs } = inputs; const locals = ctx.lane.resume.locals; const base = locals && typeof locals === 'object' && !Array.isArray(locals) ? locals : {}; return { ...base, $sdk: { ...sdkLocals(locals), [`${name}Turns`]: turns, [inputKey]: asJson(persistedInputs) } }; };
+        const pendingResultKey = `${name}PendingResultRef`;
+        const pendingResultRef = (ctx) => { const value = sdkLocals(ctx.lane.resume.locals)[pendingResultKey]; return typeof value === 'string' ? value : undefined; };
+        const clearPendingResult = (ctx) => {
+            const locals = ordinaryLocals(ctx.lane.resume.locals);
+            const sdk = { ...sdkLocals(ctx.lane.resume.locals) };
+            delete sdk[pendingResultKey];
+            return { ...locals, $sdk: sdk };
+        };
+        const resultRefFromWait = (ctx) => {
+            const pending = pendingResultRef(ctx);
+            if (pending)
+                return pending;
+            const resolution = waitResolution(ctx.resumeInput);
+            const dependency = resolution === undefined ? undefined : Object.values(resolution.dependencies).find((candidate) => candidate.state === 'settled');
+            return dependency?.state === 'settled' ? dependency.outcome.resultRef : undefined;
+        };
+        const resultRefsFromWait = (ctx) => { const resolution = waitResolution(ctx.resumeInput); return resolution === undefined ? [] : Object.values(resolution.dependencies).flatMap((dependency) => dependency.state === 'settled' && dependency.outcome.resultRef ? [dependency.outcome.resultRef] : []); };
         const instruction = (ctx) => boundedInstruction(typeof options.instruction === 'string' ? options.instruction : options.instruction({ goal: ctx.goal, state: scalarProjection(ctx.laneState) }));
-        const submitModel = (ctx, turn, inputs = {}) => { const resultRefs = [...new Set(inputs.results ?? [])]; const findingRefs = [...new Set(inputs.findings ?? [])]; const artifactRefs = [...new Set(inputs.artifacts ?? [])]; const dataRefs = [...resultRefs, ...findingRefs, ...artifactRefs.map((ref) => ({ kind: 'artifact', ref }))]; const requirements = { ...(options.requirements ?? {}), ...(options.toolAllow === undefined ? {} : { toolCalling: true }) }; return { actions: [{ type: 'submit_effects', effects: [{ key: `${name}-turn-${turn}`, kind: 'llm', concurrencyClass: 'llm', input: programLLMInput(this.config, { task: options.task ?? 'reason', instruction: instruction(ctx), inputs: { ...(resultRefs.length ? { results: resultRefs } : {}), ...(findingRefs.length ? { findings: findingRefs } : {}), ...(artifactRefs.length ? { artifacts: artifactRefs } : {}), ...(inputs.events?.length ? { events: [...new Set(inputs.events)] } : {}) }, turn, ...(inputs.toolDiscovery === undefined ? {} : { toolDiscovery: inputs.toolDiscovery }), ...(options.outputSchema === undefined ? {} : { outputSchema: zodJsonSchema(options.outputSchema) }), ...(Object.keys(requirements).length ? { requirements } : {}) }), ...(dataRefs.length ? { derivedFrom: dataRefs } : {}) }], wait: { onUnsatisfied: 'resume_with_error' } }], next: { programId: this.config.id, programVersion: this.config.version, step: `${name}:decode`, locals: writeTurns(ctx, turn, inputs) }, locals: writeTurns(ctx, turn, inputs) }; };
+        const submitModel = (ctx, turn, inputs = {}) => { const resultRefs = [...new Set(inputs.results ?? [])]; const findingRefs = [...new Set(inputs.findings ?? [])]; const artifactRefs = [...new Set(inputs.artifacts ?? [])]; const dataRefs = [...resultRefs, ...findingRefs, ...artifactRefs.map((ref) => ({ kind: 'artifact', ref }))]; const requirements = { ...(options.requirements ?? {}), ...(options.toolAllow === undefined ? {} : { toolCalling: true }) }; return { actions: [{ type: 'submit_effects', effects: [{ key: `${name}-turn-${turn}`, kind: 'llm', concurrencyClass: 'llm', input: programLLMInput(this.config, { task: options.task ?? 'reason', instruction: instruction(ctx), inputs: { ...(resultRefs.length ? { results: resultRefs } : {}), ...(findingRefs.length ? { findings: findingRefs } : {}), ...(artifactRefs.length ? { artifacts: artifactRefs } : {}), ...(inputs.events?.length ? { events: [...new Set(inputs.events)] } : {}), ...(inputs.conversation?.length ? { conversation: inputs.conversation } : {}) }, turn, ...(inputs.toolDiscovery === undefined ? {} : { toolDiscovery: inputs.toolDiscovery }), ...(options.outputSchema === undefined ? {} : { outputSchema: zodJsonSchema(options.outputSchema) }), ...(Object.keys(requirements).length ? { requirements } : {}) }), ...(dataRefs.length ? { derivedFrom: dataRefs } : {}) }], wait: { onUnsatisfied: 'resume_with_error' } }], next: { programId: this.config.id, programVersion: this.config.version, step: `${name}:decode`, locals: writeTurns(ctx, turn, inputs) }, locals: writeTurns(ctx, turn, inputs) }; };
         this.handlers.set(name, (ctx) => { const turn = readTurns(ctx) + 1; const inputs = options.inputs?.(ctx) ?? {}; const output = submitModel(ctx, turn, inputs); return { ...output, next: `${name}:decode` }; });
-        this.handlers.set(`${name}:tools`, (ctx) => { const turn = readTurns(ctx); const previous = readInputs(ctx); const inputs = { ...previous, results: [...new Set([...(previous.results ?? []), ...resultRefsFromWait(ctx)])] }; return { ...submitModel(ctx, turn + 1, inputs), next: `${name}:decode` }; });
+        this.handlers.set(`${name}:tools`, (ctx) => { const turn = readTurns(ctx); const previous = readInputs(ctx); const current = options.inputs?.(ctx) ?? {}; const inputs = { ...current, ...previous, results: [...new Set([...(previous.results ?? []), ...resultRefsFromWait(ctx)])] }; return { ...submitModel(ctx, turn + 1, inputs), next: `${name}:decode` }; });
         this.handlers.set(`${name}:decode`, (ctx) => {
             const turns = readTurns(ctx);
             const ref = resultRefFromWait(ctx);
@@ -388,19 +418,33 @@ export class StepBuilder {
             const record = value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
             const finishReason = record?.finishReason;
             const toolCalls = Array.isArray(record?.toolCalls) ? record.toolCalls : [];
-            const fail = (runtimeError) => options.onError ? { next: options.onError(runtimeError, ctx) } : (() => { const error = Object.assign(new Error(runtimeError.message), runtimeError); throw error; })();
+            const fail = (runtimeError) => options.onError ? { next: options.onError(runtimeError, ctx), locals: clearPendingResult(ctx) } : (() => { const error = Object.assign(new Error(runtimeError.message), runtimeError); throw error; })();
             const dependencyError = waitFailure(ctx);
             if (dependencyError)
                 return fail(dependencyError);
             const maxTurns = Math.max(1, Math.floor(options.maxTurns ?? 10));
-            const maxTurnsReached = () => options.onMaxTurns ? { next: options.onMaxTurns(ctx) } : fail({ code: 'MAX_TURNS_REACHED', message: `ReAct loop ${name} reached its maximum of ${maxTurns} turns.`, retryable: false });
+            const maxTurnsReached = () => options.onMaxTurns ? { next: options.onMaxTurns(ctx), locals: clearPendingResult(ctx) } : fail({ code: 'MAX_TURNS_REACHED', message: `ReAct loop ${name} reached its maximum of ${maxTurns} turns.`, retryable: false });
+            // The current model result must be retained while older history is
+            // summarized. The generic compaction macro then returns to decode and
+            // this pending reference lets us continue processing the same result.
+            const compaction = this.config.historyCompaction;
+            const pressure = ctx.lane.historyPressure;
+            const shouldCompactAfterResult = compaction !== undefined && ref !== undefined && pendingResultRef(ctx) === undefined && sdkLocals(ctx.lane.resume.locals).compactPending !== true && pressure !== undefined && pressure.historyTokens > pressure.softTokens && ctx.lane.context.history.length > Math.max(0, Math.floor(compaction.keepRecentRounds));
+            if (shouldCompactAfterResult) {
+                const locals = ordinaryLocals(ctx.lane.resume.locals);
+                const sdk = sdkLocals(ctx.lane.resume.locals);
+                return { actions: [], next: '$compact:summarize', locals: { ...locals, $sdk: { ...sdk, compactPending: true, compactReturnStep: `${name}:decode`, [pendingResultKey]: ref } } };
+            }
             if (finishReason === 'tool_calls') {
                 if (turns >= maxTurns || toolCalls.length === 0)
                     return maxTurnsReached();
                 const invalidTool = toolCalls.find((call) => { const item = call && typeof call === 'object' && !Array.isArray(call) ? call : {}; const toolName = typeof item.name === 'string' ? item.name : ''; return !toolName || (options.toolAllow !== undefined && !options.toolAllow.includes(toolName)); });
                 if (invalidTool !== undefined)
                     return fail({ code: 'ACTION_TOOL_NOT_ALLOWED', message: 'Model requested a tool outside the ReAct allow-list.', retryable: false });
-                const sourceEffectId = ctx.resumeInput?.type === 'wait' ? Object.values(ctx.resumeInput.resolution.dependencies).find((dependency) => dependency.state === 'settled' && dependency.target.kind === 'effect')?.target.id : undefined;
+                const resolution = waitResolution(ctx.resumeInput);
+                const sourceEffectId = ref !== undefined && ctx.results.meta(ref)?.producer.kind === 'effect'
+                    ? ctx.results.meta(ref)?.producer.id
+                    : resolution === undefined ? undefined : Object.values(resolution.dependencies).find((dependency) => dependency.state === 'settled' && dependency.target.kind === 'effect')?.target.id;
                 const sourcePrivacy = ref === undefined ? undefined : ctx.results.meta(ref)?.privacy;
                 const toolDerivedFrom = ref === undefined ? [] : [ref];
                 const calls = toolCalls.map((call, index) => {
@@ -409,6 +453,72 @@ export class StepBuilder {
                     const toolName = typeof item.name === 'string' ? item.name : '';
                     return { originalId, toolName, toolCallId: `${name}:${turns}:${originalId}`, input: item.input ?? {} };
                 });
+                const askCalls = calls.filter((call) => String(call.toolName).startsWith('ask.'));
+                if (askCalls.length > 0) {
+                    if (askCalls.length !== calls.length)
+                        return fail({ code: 'ASK_MIXED_TOOL_CALLS', message: 'An ask interaction must be requested in a separate model turn from workspace tools.', retryable: false });
+                    if (askCalls.length !== 1)
+                        return fail({ code: 'ASK_MULTIPLE_REQUESTS', message: 'Only one ask interaction may be requested at a time.', retryable: false });
+                    const call = askCalls[0];
+                    const rawInput = call.input && typeof call.input === 'object' && !Array.isArray(call.input) ? call.input : {};
+                    const askType = call.toolName === 'ask.choice' ? 'choice' : call.toolName === 'ask.multi' ? 'multi' : call.toolName === 'ask.input' ? 'input' : undefined;
+                    if (!askType)
+                        return fail({ code: 'ASK_TOOL_UNKNOWN', message: `Unknown ask tool ${String(call.toolName)}.`, retryable: false });
+                    if (typeof rawInput.prompt === 'string' && rawInput.prompt.length > 2_000)
+                        return fail({ code: 'ASK_PROMPT_TOO_LARGE', message: 'Ask prompts must be 2000 characters or fewer.', retryable: false });
+                    const prompt = typeof rawInput.prompt === 'string' && rawInput.prompt.trim() ? rawInput.prompt : `Pulse needs your input for ${askType}.`;
+                    const askInput = { kind: 'ask', type: askType, toolName: String(call.toolName), toolCallId: String(call.toolCallId), prompt };
+                    if (askType === 'choice' || askType === 'multi') {
+                        const rawOptions = Array.isArray(rawInput.options) ? rawInput.options : [];
+                        if (rawOptions.length > 50)
+                            return fail({ code: 'ASK_OPTIONS_TOO_MANY', message: 'ask.choice and ask.multi accept at most 50 options.', retryable: false });
+                        const seen = new Set();
+                        const options = rawOptions.flatMap((option) => {
+                            const item = typeof option === 'string' ? { label: option, value: option } : option && typeof option === 'object' && !Array.isArray(option) ? option : undefined;
+                            if (!item || typeof item.label !== 'string' || typeof item.value !== 'string')
+                                return [];
+                            if (item.label.length === 0 || item.label.length > 500 || item.value.length === 0 || item.value.length > 500 || seen.has(item.value))
+                                return [];
+                            seen.add(item.value);
+                            return [{ label: item.label, value: item.value }];
+                        });
+                        if (options.length === 0)
+                            return fail({ code: 'ASK_OPTIONS_REQUIRED', message: 'ask.choice and ask.multi require at least one valid option.', retryable: false });
+                        askInput.options = options;
+                        if (askType === 'multi') {
+                            const min = typeof rawInput.min === 'number' && Number.isInteger(rawInput.min) ? rawInput.min : undefined;
+                            const max = typeof rawInput.max === 'number' && Number.isInteger(rawInput.max) ? rawInput.max : undefined;
+                            if ((rawInput.min !== undefined && (min === undefined || min < 0)) || (rawInput.max !== undefined && (max === undefined || max < 1)) || (min !== undefined && max !== undefined && min > max))
+                                return fail({ code: 'ASK_RANGE_INVALID', message: 'ask.multi min and max must be integers with min <= max.', retryable: false });
+                            if (min !== undefined)
+                                askInput.min = min;
+                            if (max !== undefined)
+                                askInput.max = max;
+                        }
+                    }
+                    else {
+                        if (typeof rawInput.placeholder === 'string') {
+                            if (rawInput.placeholder.length > 500)
+                                return fail({ code: 'ASK_PROMPT_TOO_LARGE', message: 'Ask placeholders must be 500 characters or fewer.', retryable: false });
+                            askInput.placeholder = rawInput.placeholder;
+                        }
+                        if (typeof rawInput.defaultValue === 'string') {
+                            if (rawInput.defaultValue.length > 2_000)
+                                return fail({ code: 'ASK_PROMPT_TOO_LARGE', message: 'Ask default values must be 2000 characters or fewer.', retryable: false });
+                            askInput.defaultValue = rawInput.defaultValue;
+                        }
+                    }
+                    const humanEffect = {
+                        key: `${name}-ask-${turns}`,
+                        ...(sourceEffectId === undefined ? {} : { llmEffectId: sourceEffectId }),
+                        ...(sourcePrivacy === undefined ? {} : { privacy: sourcePrivacy }),
+                        ...(toolDerivedFrom.length ? { derivedFrom: [...toolDerivedFrom] } : {}),
+                        kind: 'human',
+                        concurrencyClass: 'none',
+                        input: askInput,
+                    };
+                    return { actions: [{ type: 'submit_effects', effects: [humanEffect], wait: { onUnsatisfied: 'resume_with_error' } }], next: `${name}:tools`, locals: clearPendingResult(ctx) };
+                }
                 const makeToolEffects = (approvedCalls) => ({ type: 'submit_effects', effects: approvedCalls.map((call, index) => ({ key: `${name}-tool-${turns}-${index + 1}`, toolCallId: String(call.toolCallId ?? `${name}:${turns}:${String(call.originalId)}`), ...(sourceEffectId === undefined ? {} : { llmEffectId: sourceEffectId }), ...(sourcePrivacy === undefined ? {} : { privacy: sourcePrivacy }), ...(toolDerivedFrom.length ? { derivedFrom: [...toolDerivedFrom] } : {}), kind: 'tool', concurrencyClass: 'tool', input: { toolCallId: String(call.toolCallId ?? `${name}:${turns}:${String(call.originalId)}`), name: String(call.toolName), arguments: call.input, ...(sourcePrivacy === undefined ? {} : { privacy: sourcePrivacy }), ...(toolDerivedFrom.length ? { derivedFrom: [...toolDerivedFrom] } : {}) } })), wait: { onUnsatisfied: 'resume_with_error' } });
                 if (options.toolApproval) {
                     const approvalKey = `${name}PendingToolCalls`;
@@ -419,13 +529,21 @@ export class StepBuilder {
                     const extra = typeof options.toolApproval.prompt === 'string' ? options.toolApproval.prompt : options.toolApproval.prompt(calls.map((call) => ({ name: call.toolName, toolCallId: call.originalId })), ctx);
                     const prompt = boundedInstruction(`Approve ${calls.length} tool call(s). Digest ${digest}.\n${listing}\n${extra}`);
                     this.handlers.set(`${name}:approval`, (approvalCtx) => {
-                        const dependency = approvalCtx.resumeInput?.type === 'wait' ? Object.values(approvalCtx.resumeInput.resolution.dependencies)[0] : undefined;
+                        const resolution = waitResolution(approvalCtx.resumeInput);
+                        const dependency = resolution === undefined ? undefined : Object.values(resolution.dependencies).find((candidate) => candidate.state === 'settled');
                         const approvalError = waitFailure(approvalCtx);
                         if (approvalError)
                             return fail(approvalError);
-                        if (dependency?.state !== 'settled')
-                            return fail({ code: 'APPROVAL_RESPONSE_MISSING', message: 'Approval response was not received.', retryable: false });
-                        const value = dependency.outcome.resultRef ? readResult(approvalCtx, dependency.outcome.resultRef) : undefined;
+                        const settledDependency = dependency;
+                        if (settledDependency?.state !== 'settled') {
+                            return fail({
+                                code: 'APPROVAL_RESPONSE_MISSING',
+                                message: 'Approval response was not received.',
+                                retryable: false,
+                                details: { dependencyState: settledDependency?.state ?? 'missing', waitId: resolution?.waitId ?? null },
+                            });
+                        }
+                        const value = settledDependency.outcome.resultRef ? readResult(approvalCtx, settledDependency.outcome.resultRef) : undefined;
                         const parsed = z.object({ approved: z.boolean(), reason: z.string().optional() }).safeParse(value);
                         if (!parsed.success)
                             return fail({ code: 'APPROVAL_RESPONSE_INVALID', message: 'Approval response must contain approved=true or false.', retryable: false, details: parsed.error.message });
@@ -447,7 +565,7 @@ export class StepBuilder {
                     });
                     return { actions: [{ type: 'submit_effects', effects: [{ key: `${name}-approval-${turns}`, kind: 'human', concurrencyClass: 'none', input: { prompt, digest, tools: calls }, ...(toolDerivedFrom.length ? { derivedFrom: [...toolDerivedFrom] } : {}) }], wait: { onUnsatisfied: 'resume_with_error' } }], next: `${name}:approval`, locals: { ...locals, $sdk: { ...sdkLocals(locals), [approvalKey]: calls, [digestKey]: digest } } };
                 }
-                return { actions: [makeToolEffects(calls)], next: `${name}:tools` };
+                return { actions: [makeToolEffects(calls)], next: `${name}:tools`, locals: clearPendingResult(ctx) };
             }
             if (turns >= maxTurns)
                 return maxTurnsReached();
@@ -460,15 +578,15 @@ export class StepBuilder {
             if (!ref)
                 return fail({ code: 'MISSING_RESULT_REF', message: 'ReAct result did not produce a ResultRef.', retryable: false });
             if (typeof options.onFinish === 'function')
-                return { next: options.onFinish(ref, ctx) };
+                return { next: options.onFinish(ref, ctx), locals: clearPendingResult(ctx) };
             if (options.onFinish.structured) {
                 const structuredValue = record?.structured ?? value;
                 const parsed = options.onFinish.structured.schema.safeParse(structuredValue);
                 if (!parsed.success)
                     return fail({ code: 'OUTPUT_SCHEMA_VIOLATION', message: 'ReAct structured result did not match schema.', retryable: false, details: parsed.error.message });
-                return { next: options.onFinish.structured.onParsed(parsed.data, ctx) };
+                return { next: options.onFinish.structured.onParsed(parsed.data, ctx), locals: clearPendingResult(ctx) };
             }
-            return { next: options.onFinish.text(ref, ctx) };
+            return { next: options.onFinish.text(ref, ctx), locals: clearPendingResult(ctx) };
         });
         return this;
     }
@@ -624,7 +742,7 @@ export class StepBuilder {
                 if (upToSeq === undefined)
                     return { next: returnStep === compactSummarize ? entry : returnStep, locals: { ...locals, $sdk: sdk } };
                 return {
-                    actions: [{ type: 'submit_effects', effects: [{ key: '$compact-summary', kind: 'llm', concurrencyClass: 'llm', input: programLLMInput(this.config, { task: compaction.summarizeTask, historySeqs: candidates.map((record) => record.seq), upToSeq }) }], wait: { onUnsatisfied: 'resume_with_error' } }],
+                    actions: [{ type: 'submit_effects', effects: [{ key: '$compact-summary', kind: 'llm', concurrencyClass: 'llm', input: programLLMInput(this.config, { task: compaction.summarizeTask, ...(compaction.instruction === undefined ? {} : { instruction: compaction.instruction }), historySeqs: candidates.map((record) => record.seq), upToSeq }) }], wait: { onUnsatisfied: 'resume_with_error' } }],
                     next: compactApply,
                     locals: { ...locals, $sdk: { ...sdk, compactPending: true, compactReturnStep: returnStep, compactUpToSeq: upToSeq } },
                 };
@@ -662,7 +780,12 @@ export class StepBuilder {
             step: (context) => {
                 const sdk = sdkLocals(context.lane.resume.locals);
                 const pressure = context.lane.historyPressure;
-                const shouldCompact = compaction !== undefined && this.compactionBoundaries.has(context.lane.resume.step) && !context.lane.resume.step.startsWith('$compact:') && context.lane.activeWaitId === undefined && sdk.compactPending !== true && pressure !== undefined && pressure.historyTokens > pressure.softTokens && context.lane.context.history.length > Math.max(0, Math.floor(compaction.keepRecentRounds));
+                const keepRecentRounds = compaction === undefined ? 0 : Math.max(0, Math.floor(compaction.keepRecentRounds));
+                const foldable = context.lane.context.history.slice(0, Math.max(0, context.lane.context.history.length - keepRecentRounds));
+                // A prefix that is already one compaction summary cannot get smaller by
+                // summarizing it again. Wait until newer rounds accumulate.
+                const onlyExistingSummary = foldable.length === 1 && foldable[0]?.instruction === '[history compacted]';
+                const shouldCompact = compaction !== undefined && this.compactionBoundaries.has(context.lane.resume.step) && !context.lane.resume.step.startsWith('$compact:') && context.lane.activeWaitId === undefined && sdk.compactPending !== true && pressure !== undefined && pressure.historyTokens > pressure.softTokens && context.lane.context.history.length > keepRecentRounds && !onlyExistingSummary;
                 if (shouldCompact)
                     return { actions: [], next: { programId: this.config.id, programVersion: this.config.version, step: compactSummarize, locals: { ...ordinaryLocals(context.lane.resume.locals), $sdk: { ...sdk, compactPending: true, compactReturnStep: context.lane.resume.step } } } };
                 const requestedStep = shouldCompact ? compactSummarize : context.lane.resume.step;

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,9 +69,11 @@ 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));
+            // Wait for runtime activity instead of polling with setImmediate while
+            // an external effect is still in flight.
+            await this.runtime.waitForActivity();
         }
     }
     async snapshot() {
@@ -71,11 +87,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,
         };
@@ -83,11 +100,21 @@ export class PulseSession {
     async outcome() { return this.execution; }
     async reply(effectId, value) {
         const effect = this.runtime.state.effects.get(effectId);
-        if (!effect || effect.agentId !== this.agentId)
+        if (!effect || !this.ownsAgent(effect.agentId))
             throw new Error('EFFECT_NOT_OWNED');
         if (effect.kind !== 'human' || effect.outcome)
             throw new Error('EFFECT_NOT_REPLYABLE');
-        this.runtime.enqueueHostCommand({ type: 'reply', agentId: this.agentId, effectId, value });
+        if (!this.runtime.enqueueHostCommand({ type: 'reply', agentId: effect.agentId, effectId, value })) {
+            throw new Error('HOST_COMMAND_NOT_ENQUEUED');
+        }
+    }
+    /** 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) {
+        if (!this.runtime.submitHumanInput(this.agentId, inputId, value, targetEffectId)) {
+            throw new Error('HOST_COMMAND_NOT_ENQUEUED');
+        }
     }
     async cancel(reason) { this.runtime.requestCancel(this.agentId, reason); }
 }

package/dist/dsl/templates.d.ts

@@ -1,4 +1,4 @@
-import { type LaneProgramDefinition, type StepContext, type InstructionView, type NextStepTarget, type StepInputs } from './program.js';
+import { type HistoryCompactionOptions, type LaneProgramDefinition, type StepContext, type InstructionView, type NextStepTarget, type StepInputs } from './program.js';
 import type { LaneProgram } from '../scheduler/runtime.js';
 import type { Outcome, JsonValue } from '../core/types.js';
 import type { ZodTypeAny } from 'zod';
@@ -24,10 +24,7 @@ export declare function defineReActLane(config: {
         prompt: string | ((calls: JsonValue, ctx: StepContext<JsonValue>) => string);
         onDenied?: (reason: string, ctx: StepContext<JsonValue>) => NextStepTarget<JsonValue>;
     };
-    historyCompaction?: {
-        summarizeTask: string;
-        keepRecentRounds: number;
-    };
+    historyCompaction?: HistoryCompactionOptions;
 }): LaneProgramDefinition;
 export declare function defineSeriesLane(config: {
     id: string;

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,62 @@
+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;
+    const targetLaneId = typeof object?.laneId === 'string' ? object.laneId : undefined;
+    const targetEffectId = typeof object?.effectId === 'string' ? object.effectId : undefined;
+    if (!command && text) {
+        const normalizedText = text.toLowerCase().replace(/[\s，。！？!?、,.]+/g, '');
+        const isContinuation = /^(继续|继续处理|接着做|往下做|恢复任务|resume|continue|goon|keepgoing)$/.test(normalizedText);
+        const isStatusCheck = /^(你还活着吗|还在吗|有进展吗|进展呢|现在怎么样|areyoualive|areyoustillthere|anyupdate|status)$/.test(normalizedText);
+        if (isContinuation || isStatusCheck) {
+            return { schemaVersion: 1, decisionId: `rule:${inputId}`, inputId, agentId, action: 'steer', ...(targetLaneId === undefined ? {} : { targetLaneId }), reason: isContinuation ? 'Human asked the current task to continue.' : 'Human asked for the current task status.', modelId };
+        }
+    }
+    if (!command)
+        return undefined;
+    const normalized = command.toLowerCase();
+    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;
+}