@runtypelabs/persona 3.17.0 → 3.18.0

package/src/client.test.ts

@@ -2717,3 +2717,137 @@ describe('AgentWidgetClient - stopReason propagation', () => {
   });
 });
 
+// ============================================================================
+// step_await (LOCAL tool pause) + resumeFlow
+// ============================================================================
+
+describe('AgentWidgetClient — step_await parsing', () => {
+  const buildStepAwaitStream = (payload: Record<string, unknown>): ReadableStream<Uint8Array> => {
+    const encoder = new TextEncoder();
+    const body = `event: step_await\ndata: ${JSON.stringify({ type: 'step_await', ...payload })}\n\n`;
+    return new ReadableStream({
+      start(controller) {
+        controller.enqueue(encoder.encode(body));
+        controller.close();
+      },
+    });
+  };
+
+  it('emits a complete tool message with awaitingLocalTool=true for local_tool_required', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      body: buildStepAwaitStream({
+        awaitReason: 'local_tool_required',
+        id: 'step-1',
+        name: 'Test Step',
+        stepType: 'prompt',
+        index: 0,
+        toolId: 'runtime_ask_user_question_123',
+        toolName: 'ask_user_question',
+        executionId: 'exec_abc',
+        parameters: {
+          questions: [{ question: 'Who?', options: [{ label: 'A' }, { label: 'B' }] }],
+        },
+      }),
+    });
+
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+
+    const toolMsg = events
+      .filter((e) => e.type === 'message')
+      .map((e) => (e as { message: AgentWidgetMessage }).message)
+      .find((m) => m.variant === 'tool' && m.toolCall?.name === 'ask_user_question');
+
+    expect(toolMsg).toBeDefined();
+    expect(toolMsg!.toolCall!.id).toBe('runtime_ask_user_question_123');
+    expect(toolMsg!.toolCall!.status).toBe('complete');
+    expect(toolMsg!.toolCall!.args).toMatchObject({
+      questions: [{ question: 'Who?', options: [{ label: 'A' }, { label: 'B' }] }],
+    });
+    expect(toolMsg!.agentMetadata?.executionId).toBe('exec_abc');
+    expect(toolMsg!.agentMetadata?.awaitingLocalTool).toBe(true);
+  });
+
+  it('ignores step_await events whose awaitReason is not local_tool_required', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      body: buildStepAwaitStream({
+        awaitReason: 'approval_required',
+        toolId: 't1',
+        toolName: 'some_tool',
+        executionId: 'exec_abc',
+        parameters: {},
+      }),
+    });
+
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+
+    const toolMsg = events
+      .filter((e) => e.type === 'message')
+      .map((e) => (e as { message: AgentWidgetMessage }).message)
+      .find((m) => m.agentMetadata?.awaitingLocalTool);
+    expect(toolMsg).toBeUndefined();
+  });
+});
+
+describe('AgentWidgetClient.resumeFlow', () => {
+  it('POSTs to ${apiUrl}/resume with the expected body shape', async () => {
+    let capturedUrl: string | undefined;
+    let capturedBody: Record<string, unknown> | undefined;
+    let capturedHeaders: Record<string, string> | undefined;
+    global.fetch = vi.fn().mockImplementation(async (url: string, init: RequestInit) => {
+      capturedUrl = url;
+      capturedBody = JSON.parse(init.body as string);
+      capturedHeaders = init.headers as Record<string, string>;
+      return { ok: true, body: null };
+    });
+
+    const client = new AgentWidgetClient({ apiUrl: 'https://api.runtype.com/v1/dispatch' });
+    await client.resumeFlow('exec_xyz', { ["ask_user_question"]: 'Hobbyists' });
+
+    expect(capturedUrl).toBe('https://api.runtype.com/v1/dispatch/resume');
+    expect(capturedBody).toEqual({
+      executionId: 'exec_xyz',
+      toolOutputs: { ["ask_user_question"]: 'Hobbyists' },
+      streamResponse: true,
+    });
+    expect(capturedHeaders!['Content-Type']).toBe('application/json');
+  });
+
+  it('honors a custom streamResponse option', async () => {
+    let capturedBody: Record<string, unknown> | undefined;
+    global.fetch = vi.fn().mockImplementation(async (_url: string, init: RequestInit) => {
+      capturedBody = JSON.parse(init.body as string);
+      return { ok: true, body: null };
+    });
+
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:43111/api/chat/dispatch' });
+    await client.resumeFlow('exec_abc', { t: 'ok' }, { streamResponse: false });
+
+    expect(capturedBody!.streamResponse).toBe(false);
+  });
+
+  it('derives the URL correctly for proxy-style dispatch paths', async () => {
+    let capturedUrl: string | undefined;
+    global.fetch = vi.fn().mockImplementation(async (url: string) => {
+      capturedUrl = url;
+      return { ok: true, body: null };
+    });
+
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:43111/api/chat/dispatch' });
+    await client.resumeFlow('exec_abc', {});
+
+    expect(capturedUrl).toBe('http://localhost:43111/api/chat/dispatch/resume');
+  });
+});
+

package/src/client.ts

@@ -775,6 +775,49 @@ export class AgentWidgetClient {
     });
   }
 
+  /**
+   * Resume a paused flow execution by supplying outputs for LOCAL
+   * (client-executed) tools. Used by the built-in `ask_user_question`
+   * answer-pill sheet, but generic enough for any LOCAL tool.
+   *
+   * Posts to the upstream `/resume` endpoint (the dispatch URL with
+   * `/dispatch` replaced by `/resume` — works for both direct-to-Runtype
+   * and the persona proxy) and returns the raw Response so the caller can
+   * pipe its SSE body through `connectStream()`.
+   *
+   * @param executionId - The paused execution id carried on `step_await`.
+   * @param toolOutputs - Map keyed by tool name → the tool's result value.
+   */
+  public async resumeFlow(
+    executionId: string,
+    toolOutputs: Record<string, unknown>,
+    options?: { streamResponse?: boolean }
+  ): Promise<Response> {
+    const trimmed = this.config.apiUrl?.replace(/\/+$/, '') || DEFAULT_CLIENT_API_BASE;
+    // Runtype mounts POST /resume as a child route of /v1/dispatch, so the
+    // final URL is always `${apiUrl}/resume`. Proxies should follow the
+    // same shape (`/api/chat/dispatch/resume`) to keep the widget agnostic.
+    const url = `${trimmed}/resume`;
+
+    let headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...this.headers
+    };
+    if (this.getHeaders) {
+      Object.assign(headers, await this.getHeaders());
+    }
+
+    return fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        executionId,
+        toolOutputs,
+        streamResponse: options?.streamResponse ?? true,
+      }),
+    });
+  }
+
   private async buildAgentPayload(
     messages: AgentWidgetMessage[]
   ): Promise<AgentWidgetAgentRequestPayload> {
@@ -1722,6 +1765,34 @@ export class AgentWidgetClient {
           if (callKey) {
             toolContext.byCall.delete(callKey);
           }
+        } else if (payloadType === "step_await" && payload.awaitReason === "local_tool_required" && payload.toolName) {
+          // LOCAL tool pause. Runtype's prompt step throws LocalToolRequiredError
+          // when the model calls a tool with `toolType: "local"`. The server
+          // emits step_await with the tool name, params, and execution id; the
+          // execution pauses until the client POSTs /resume with toolOutputs.
+          //
+          // Upsert a fully-populated tool-variant message so the existing
+          // ask_user_question bubble + sheet paths fire. Mark the message with
+          // `awaitingLocalTool: true` so the UI knows to resolve via
+          // resumeFlow rather than the legacy sendMessage fallback.
+          const toolId = (payload.toolId as string) ?? `local-${nextSequence()}`;
+          const toolMessage = ensureToolMessage(toolId);
+          const tool = toolMessage.toolCall ?? { id: toolId, status: "pending" as const };
+          tool.name = payload.toolName as string;
+          tool.args = payload.parameters;
+          tool.status = "complete";
+          tool.chunks = tool.chunks ?? [];
+          tool.startedAt =
+            tool.startedAt ?? resolveTimestamp(payload.startedAt ?? payload.timestamp);
+          tool.completedAt = tool.completedAt ?? tool.startedAt;
+          toolMessage.toolCall = tool;
+          toolMessage.streaming = false;
+          toolMessage.agentMetadata = {
+            ...toolMessage.agentMetadata,
+            executionId: (payload.executionId as string) ?? toolMessage.agentMetadata?.executionId,
+            awaitingLocalTool: true,
+          };
+          emitMessage(toolMessage);
         } else if (payloadType === "text_start") {
           // Lifecycle event: a new text segment is beginning (emitted at tool boundaries).
           // When toolContext is present this fired inside a nested flow — it must not