fix(runtime): complete form interaction lifecycle

Generated-by: OpenAI Codex

Author: me2seeks

packages/core/src/__tests__/interaction.test.ts

@@ -1368,6 +1368,23 @@ describe('Interaction decoding and validity', () => {
         ],
       }),
     );
+
+    assert.throws(
+      () =>
+        projectInteractionFormRequest({
+          toolUseId: 'tool-form',
+          message: 'Optional values still consume the persisted answer envelope',
+          requester: { name: 'deploy' },
+          fields: Array.from({ length: 4 }, (_, index) => ({
+            kind: 'string' as const,
+            name: `optional-${index}`,
+            label: `Optional ${index}`,
+            required: false,
+            maxLength: 2_048,
+          })),
+        }),
+      /Interaction form (answer|outcome) exceeds serialized byte limit/,
+    );
   });
 
   test('compares canonical accepted form values structurally', () => {

packages/core/src/interaction.ts

@@ -731,8 +731,22 @@ function projectInteractionFormField(field: InteractionFormField): InteractionFo
         }),
   };
   if (field.kind !== 'single_select' && field.kind !== 'multi_select') {
+    // `name` is a protocol identity returned to the tool; a string default is
+    // rendered into an input the user reads and accepts.
+    if (field.kind === 'string' && field.default !== undefined) {
+      return {
+        ...field,
+        ...display,
+        default: projectInteractionReviewText(
+          field.default,
+          INTERACTION_FORM_VALUE_MAX_BYTES,
+          true,
+        ),
+      };
+    }
     return { ...field, ...display };
   }
+  // Select values are protocol identities; labels are their display text.
   const options = field.options.map((option) => ({
     ...option,
     label: projectInteractionReviewText(option.label, INTERACTION_FORM_FIELD_LABEL_MAX_BYTES),
@@ -1248,6 +1262,45 @@ function assertFormHasAcceptedAnswer(request: InteractionFormRequest): void {
   }
   serializedLimit(answer, INTERACTION_ANSWER_SERIALIZED_MAX_BYTES, 'Interaction form answer');
   assertAcceptedFormAnswerFitsCanonicalOutcome(answer);
+  assertEveryFormAnswerFitsCanonicalOutcome(request);
+}
+
+/**
+ * Admission must reserve the whole legal answer envelope, not only a smallest
+ * witness. This intentionally over-approximates format-constrained strings:
+ * rejecting an over-large form is safe, whereas accepting one that can later
+ * reject a valid user answer strands the interaction.
+ */
+function assertEveryFormAnswerFitsCanonicalOutcome(request: InteractionFormRequest): void {
+  const values = Object.fromEntries(
+    request.fields.map((field) => [field.name, formFieldMaximumEnvelope(field)]),
+  );
+  const answer = { kind: 'form' as const, action: 'accept' as const, values };
+  serializedLimit(answer, INTERACTION_ANSWER_SERIALIZED_MAX_BYTES, 'Interaction form answer');
+  assertAcceptedFormAnswerFitsCanonicalOutcome(answer);
+}
+
+function formFieldMaximumEnvelope(field: InteractionFormField): InteractionFormValue {
+  if (field.kind === 'string') {
+    const maximumCodePoints = Math.min(
+      field.maxLength ?? INTERACTION_FORM_VALUE_MAX_BYTES,
+      Math.floor(INTERACTION_FORM_VALUE_MAX_BYTES / 4),
+    );
+    return '😀'.repeat(maximumCodePoints);
+  }
+  if (field.kind === 'number' || field.kind === 'integer') return -1.7976931348623157e308;
+  if (field.kind === 'boolean') return false;
+  if (field.kind === 'single_select') {
+    return field.options.reduce(
+      (longest, option) =>
+        Buffer.byteLength(option.value) > Buffer.byteLength(longest) ? option.value : longest,
+      field.options[0]!.value,
+    );
+  }
+  return [...field.options]
+    .sort((left, right) => Buffer.byteLength(right.value) - Buffer.byteLength(left.value))
+    .slice(0, field.maxItems ?? field.options.length)
+    .map((option) => option.value);
 }
 
 function assertAcceptedFormAnswerFitsCanonicalOutcome(

packages/runtime/src/__tests__/session-projection-helpers.test.ts

@@ -130,12 +130,18 @@ describe('session projection helpers', () => {
     assert.deepStrictEqual(statusFromEvent({ type: 'user_question_request', ts: 1 } as never), {
       status: 'waiting_for_user',
     });
+    assert.deepStrictEqual(statusFromEvent({ type: 'form_request', ts: 1 } as never), {
+      status: 'waiting_for_user',
+    });
     assert.deepStrictEqual(
       statusFromEvent({ type: 'sandbox_boundary_decision_ack', ts: 1 } as never),
       {
         status: 'running',
       },
     );
+    assert.deepStrictEqual(statusFromEvent({ type: 'form_answer_ack', ts: 1 } as never), {
+      status: 'running',
+    });
     assert.strictEqual(
       statusFromEvent({ type: 'sandbox_boundary_decision_ack', ts: 1 } as never, {
         allowInteractionResume: false,

packages/runtime/src/__tests__/stream-graph-projection.test.ts

@@ -566,6 +566,19 @@ describe('committed stream graph projection', () => {
                 userQuestionAnswerAccepted: { requestId: 'question-1' },
               },
             }),
+            runtimeEvent(run, {
+              id: 'form-request',
+              ts: baseTs + 4,
+              actions: {
+                formRequest: {
+                  requestId: 'form-1',
+                  toolUseId: 'tool-3',
+                  message: 'Choose settings',
+                  requester: { name: 'fixture' },
+                  fields: [{ kind: 'boolean', name: 'confirm', label: 'Confirm', required: true }],
+                },
+              },
+            }),
           ],
         },
       ],
@@ -577,9 +590,11 @@ describe('committed stream graph projection', () => {
         [{ kind: 'attention', reason: 'permission_request' }],
         [{ kind: 'attention', reason: 'user_question_request' }],
         [],
+        [{ kind: 'attention', reason: 'form_request' }],
       ],
     );
     assert.deepEqual(records[2]?.facets, ['runtime_fact']);
+    assert.deepEqual(records[3]?.facets, ['form_request']);
     assert.equal(replayAgentGraphRecords(records).operators.research?.status, 'running');
   });
 

packages/runtime/src/agent-run.ts

@@ -1900,7 +1900,9 @@ async function appendUserMessageOnce(
 
 function isInteractionResumeAck(event: SessionEvent): boolean {
   return (
-    event.type === 'sandbox_boundary_decision_ack' || event.type === 'user_question_answer_ack'
+    event.type === 'sandbox_boundary_decision_ack' ||
+    event.type === 'user_question_answer_ack' ||
+    event.type === 'form_answer_ack'
   );
 }
 

packages/runtime/src/interaction-authority.ts

@@ -24,6 +24,7 @@ import type {
   FormRequestEvent,
   SandboxBoundaryDecisionAckEvent,
   SandboxBoundaryRequestEvent,
+  SessionEvent,
   UserQuestionAnswerAckEvent,
   UserQuestionRequestEvent,
 } from '@maka/core/events';
@@ -207,6 +208,26 @@ type HostedInteractionSettlementAckEvent =
   | UserQuestionAnswerAckEvent
   | FormAnswerAckEvent
   | SandboxBoundaryDecisionAckEvent;
+
+export function isHostedInteractionRequestEvent(
+  event: SessionEvent,
+): event is HostedInteractionRequestEvent {
+  return (
+    event.type === 'user_question_request' ||
+    event.type === 'form_request' ||
+    event.type === 'sandbox_boundary_request'
+  );
+}
+
+export function isHostedInteractionSettlementAckEvent(
+  event: SessionEvent,
+): event is HostedInteractionSettlementAckEvent {
+  return (
+    event.type === 'user_question_answer_ack' ||
+    event.type === 'form_answer_ack' ||
+    event.type === 'sandbox_boundary_decision_ack'
+  );
+}
 type RuntimeHostedInteractionOutcome =
   | RuntimeUserQuestionOutcome
   | RuntimeFormOutcome

packages/runtime/src/runtime-kernel.ts

@@ -146,6 +146,8 @@ import {
   RuntimeInteractionFailStopError,
   RuntimeInteractionInvariantError,
   bindRuntimeInteractionRun,
+  isHostedInteractionRequestEvent,
+  isHostedInteractionSettlementAckEvent,
   type RuntimeInteractionAuthority,
   type RuntimeInteractionRunBinding,
   type RuntimeInteractionRunClosureReason,
@@ -1588,10 +1590,7 @@ export class RuntimeKernel implements RuntimeKernelLike {
     binding: RuntimeInteractionRunBinding | undefined,
     event: SessionEvent,
   ): void {
-    if (
-      binding &&
-      (event.type === 'user_question_request' || event.type === 'sandbox_boundary_request')
-    ) {
+    if (binding && isHostedInteractionRequestEvent(event)) {
       binding.assertPendingAdmission(event);
     }
   }
@@ -3332,10 +3331,7 @@ async function interactionResumeAllowed(
   interactionRun: RuntimeInteractionRunBinding | undefined,
   event: SessionEvent,
 ): Promise<boolean> {
-  if (
-    !interactionRun ||
-    (event.type !== 'user_question_answer_ack' && event.type !== 'sandbox_boundary_decision_ack')
-  ) {
+  if (!interactionRun || !isHostedInteractionSettlementAckEvent(event)) {
     return true;
   }
   return await interactionRun.canResumeAfterSettlementAck(event);

packages/runtime/src/session-projection-helpers.ts

@@ -119,11 +119,13 @@ export function statusFromEvent(
     case 'sandbox_boundary_request':
       return { status: 'waiting_for_user', blockedReason: 'permission_required' };
     case 'user_question_request':
+    case 'form_request':
       return { status: 'waiting_for_user' };
     case 'sandbox_boundary_decision_ack':
       if (options.allowInteractionResume === false) return undefined;
       return { status: 'running' };
     case 'user_question_answer_ack':
+    case 'form_answer_ack':
       if (options.allowInteractionResume === false) return undefined;
       return { status: 'running' };
     case 'error':

packages/runtime/src/stream-graph-projection.ts

@@ -37,6 +37,7 @@ export const AGENT_GRAPH_RECORD_FACETS = [
   'permission_request',
   'permission_decision',
   'user_question_request',
+  'form_request',
   'transfer',
   'usage',
   'completed',
@@ -55,7 +56,10 @@ export type AgentGraphActivationStatus =
   | 'aborted'
   | 'cancelled';
 
-export type AgentGraphSupervisorAttentionReason = 'permission_request' | 'user_question_request';
+export type AgentGraphSupervisorAttentionReason =
+  | 'permission_request'
+  | 'user_question_request'
+  | 'form_request';
 
 export type AgentGraphSupervisorSignal =
   | {
@@ -521,6 +525,7 @@ function runtimeEventFacets(event: RuntimeEvent, run: AgentRunHeader): AgentGrap
   if (actions?.permissionRequest) facets.push('permission_request');
   if (actions?.permissionDecision) facets.push('permission_decision');
   if (actions?.userQuestionRequest) facets.push('user_question_request');
+  if (actions?.formRequest) facets.push('form_request');
   if (actions?.transferToAgent) facets.push('transfer');
   if (actions?.tokenUsage) facets.push('usage');
 
@@ -541,6 +546,9 @@ function runtimeEventSupervisorSignals(
   if (event.actions?.userQuestionRequest) {
     signals.push({ kind: 'attention', reason: 'user_question_request' });
   }
+  if (event.actions?.formRequest) {
+    signals.push({ kind: 'attention', reason: 'form_request' });
+  }
   const terminalStatus = runtimeEventTerminalStatus(event, run);
   if (terminalStatus) {
     signals.push({ kind: 'terminal', status: terminalStatus });

packages/runtime/src/stream-graph-read-model.ts

@@ -941,6 +941,11 @@ function projectClientSessionEvent(
         facets: ['user_question_request'],
         signals: [{ kind: 'attention', reason: 'user_question_request' }],
       };
+    case 'form_request':
+      return {
+        facets: ['form_request'],
+        signals: [{ kind: 'attention', reason: 'form_request' }],
+      };
     case 'token_usage':
       return { facets: ['usage'], signals: [] };
     case 'error':