feat: Expose jobs via React SDK (#637)

* Feat: Expose jobs via React SDK

* feat: Support for job approval

* chore: Update tests

Author: johnjcsmith

control-plane/src/modules/contract.ts

@@ -1176,6 +1176,8 @@ export const definition = {
           authContext: z.any().nullable(),
           feedbackComment: z.string().nullable(),
           feedbackScore: z.number().nullable(),
+          result: anyObject.nullable().optional(),
+          tags: z.record(z.string()).nullable().optional(),
           attachedFunctions: z.array(z.string()).nullable(),
           name: z.string().nullable(),
         }),

control-plane/src/modules/runs/queues.ts

@@ -6,7 +6,7 @@ import { getRun } from "./";
 import { processRun } from "./agent/run";
 import { generateTitle } from "./summarization";
 
-import { and, eq } from "drizzle-orm";
+import { and, eq, } from "drizzle-orm";
 import { Consumer } from "sqs-consumer";
 import { z } from "zod";
 import { injectTraceContext } from "../observability/tracer";

control-plane/src/modules/timeline.ts

@@ -1,7 +1,7 @@
 import { getJobsForRun } from "./jobs/jobs";
 import { getActivityForTimeline } from "./observability/events";
 import { getRunMessagesForDisplay } from "./runs/messages";
-import { getRun } from "./runs";
+import { getRun, getRunDetails } from "./runs";
 
 export const timeline = {
   getRunTimeline: async ({
@@ -53,7 +53,7 @@ export const timeline = {
         clusterId,
         runId,
       }),
-      getRun({
+      getRunDetails({
         clusterId,
         runId,
       }),

sdk-react/src/contract.ts

@@ -234,6 +234,17 @@ export const definition = {
       }),
     },
   },
+  createEphemeralSetup: {
+    method: "POST",
+    path: "/ephemeral-setup",
+    responses: {
+      200: z.object({
+        clusterId: z.string(),
+        apiKey: z.string(),
+      }),
+    },
+    body: z.undefined(),
+  },
   getContract: {
     method: "GET",
     path: "/contract",
@@ -292,6 +303,8 @@ export const definition = {
         resultType: z.string().nullable(),
         createdAt: z.date(),
         blobs: z.array(blobSchema),
+        approved: z.boolean().nullable(),
+        approvalRequested: z.boolean().nullable(),
       }),
     },
   },
@@ -725,15 +738,23 @@ export const definition = {
       authorization: z.string(),
     }),
     body: z.object({
-      runId: z
+      id: z
         .string()
         .optional()
         .describe(
-          "The run ID. If not provided, a new run will be created. If provided, the run will be created with the given"
+          "The run ID. If not provided, a new run will be created. If provided, the run will be created with the given. If the run already exists, it will be returned."
         )
         .refine(
-          val => !val || /^[0-9A-Z]{26}$/.test(val),
-          "Run ID must be a valid ULID (26 uppercase alphanumeric characters)"
+          val => !val || /^[0-9A-Za-z-_]{16,128}$/.test(val),
+          "Run ID must contain only alphanumeric characters, dashes, and underscores. Must be between 16 and 128 characters long."
+        ),
+      runId: z
+        .string()
+        .optional()
+        .describe("Deprecated. Use `id` instead.")
+        .refine(
+          val => !val || /^[0-9A-Za-z-_]{16,128}$/.test(val),
+          "Run ID must contain only alphanumeric characters, dashes, and underscores. Must be between 16 and 128 characters long."
         ),
       initialPrompt: z
         .string()
@@ -761,9 +782,18 @@ export const definition = {
         ),
       onStatusChange: z
         .object({
-          statuses: z.array(z.enum(["pending", "running", "paused", "done", "failed"])).describe(" A list of Run statuses which should trigger the handler").optional().default(["done", "failed"]),
-          function: functionReference.describe("A function to call when the run status changes").optional(),
-          webhook: z.string().describe("A webhook URL to call when the run status changes").optional(),
+          statuses: z
+            .array(z.enum(["pending", "running", "paused", "done", "failed"]))
+            .describe(" A list of Run statuses which should trigger the handler")
+            .optional()
+            .default(["done", "failed"]),
+          function: functionReference
+            .describe("A function to call when the run status changes")
+            .optional(),
+          webhook: z
+            .string()
+            .describe("A webhook URL to call when the run status changes")
+            .optional(),
         })
         .optional()
         .describe("Mechanism for receiving notifications when the run status changes"),
@@ -1146,6 +1176,8 @@ export const definition = {
           authContext: z.any().nullable(),
           feedbackComment: z.string().nullable(),
           feedbackScore: z.number().nullable(),
+          result: anyObject.nullable().optional(),
+          tags: z.record(z.string()).nullable().optional(),
           attachedFunctions: z.array(z.string()).nullable(),
           name: z.string().nullable(),
         }),

sdk-react/src/hooks/useMessages.ts

@@ -1,4 +1,4 @@
-import { ListMessagesResponse } from "./useRun";
+import { RunTimelineMessages } from "./useRun";
 
 /**
  * Message types supported in the Inferable conversation system.
@@ -74,7 +74,7 @@ import { ListMessagesResponse } from "./useRun";
  * });
  * ```
  */
-export const useMessages = (messages?: ListMessagesResponse) => {
+export const useMessages = (messages?: RunTimelineMessages) => {
   return {
     /**
      * Returns all messages sorted by their ID
@@ -91,7 +91,7 @@ export const useMessages = (messages?: ListMessagesResponse) => {
      * @param type - The message type to filter by ("human", "agent", or "invocation-result")
      * @returns Array of messages matching the specified type
      */
-    getOfType: (type: ListMessagesResponse[number]["type"]) =>
+    getOfType: (type: RunTimelineMessages[number]["type"]) =>
       messages?.filter(message => message.type === type),
   };
 };

sdk-react/src/hooks/useRun.test.ts

@@ -8,8 +8,7 @@ type ApiClient = ReturnType<typeof createApiClient>;
 
 const createMockApiClient = () => ({
   createRun: jest.fn() as jest.Mock<any>,
-  listMessages: jest.fn() as jest.Mock<any>,
-  getRun: jest.fn() as jest.Mock<any>,
+  getRunTimeline: jest.fn() as jest.Mock<any>,
   createMessage: jest.fn() as jest.Mock<any>,
   listRuns: jest.fn() as jest.Mock<any>,
 });
@@ -29,10 +28,6 @@ describe("useRun", () => {
     jest.clearAllMocks();
   });
 
-  const mockSchema = z.object({
-    result: z.any(),
-  });
-
   const createMockInferable = (client: MockApiClient) => ({
     client: client as unknown as ApiClient,
     clusterId: "test-cluster",
@@ -48,11 +43,12 @@ describe("useRun", () => {
 
   it("should use existing runId when provided", async () => {
     const existingRunId = "existing-run-123";
-    mockApiClient.listMessages.mockResolvedValue({ status: 200, body: [], headers: new Headers() });
-    mockApiClient.getRun.mockResolvedValue({
+    mockApiClient.getRunTimeline.mockResolvedValue({
       status: 200,
-      body: { id: existingRunId, status: "running" },
-      headers: new Headers(),
+      body: {
+        messages: [],
+        run: { id: existingRunId, status: "running" },
+      }, headers: new Headers()
     });
 
     const mockInferable = createMockInferable(mockApiClient);
@@ -72,10 +68,12 @@ describe("useRun", () => {
     const runId = "test-run-123";
     const messageText = "test message";
 
-    mockApiClient.listMessages.mockResolvedValue({ status: 200, body: [], headers: new Headers() });
-    mockApiClient.getRun.mockResolvedValue({
+    mockApiClient.getRunTimeline.mockResolvedValue({
       status: 200,
-      body: { id: runId, status: "running" },
+      body: {
+        run: {id: runId, status: "running" },
+        messages: [],
+      },
       headers: new Headers(),
     });
     mockApiClient.createMessage.mockResolvedValueOnce({

sdk-react/src/hooks/useRun.ts

@@ -4,8 +4,9 @@ import { z } from "zod";
 import { contract } from "../contract";
 import { useInferable } from "./useInferable";
 
-export type ListMessagesResponse = ClientInferResponseBody<(typeof contract)["listMessages"], 200>;
-type GetRunResponse = ClientInferResponseBody<(typeof contract)["getRun"], 200>;
+export type RunTimelineMessages = ClientInferResponseBody<(typeof contract)["listMessages"], 200>;
+type RunTimelineRun = ClientInferResponseBody<(typeof contract)["getRunTimeline"], 200>["run"];
+type RunTimelineJobs = ClientInferResponseBody<(typeof contract)["getRunTimeline"], 200>["jobs"];
 
 /**
  * Return type for the useRun hook containing all the necessary methods and data for managing a run session
@@ -20,14 +21,18 @@ interface UseRunReturn<T extends z.ZodObject<any>> {
    */
   createMessage: (input: string) => Promise<void>;
   /** Array of messages in the current run, including human messages, agent responses, and invocation results */
-  messages: ListMessagesResponse;
+  messages: RunTimelineMessages;
   /** Current run details including status, metadata, and result if available */
-  run?: GetRunResponse;
+  run?: RunTimelineRun;
   /**
    * Typed result of the run based on the provided schema T.
    * Only available when the run is complete and successful.
    */
   result?: z.infer<T>;
+  /** Array of jobs in the current run */
+  jobs: RunTimelineJobs;
+  /** Function to approve or deny a job in the current run */
+  submitApproval: (jobId: string, approved: boolean) => Promise<void>;
   /** Error object if any errors occurred during the session */
   error: Error | null;
 }
@@ -102,8 +107,9 @@ export function useRun<T extends z.ZodObject<any>>(
   options: UseRunOptions = {}
 ): UseRunReturn<T> {
   const { persist = true } = options;
-  const [messages, setMessages] = useState<ListMessagesResponse>([]);
-  const [run, setRun] = useState<GetRunResponse>();
+  const [messages, setMessages] = useState<RunTimelineMessages>([]);
+  const [jobs, setJobs] = useState<RunTimelineJobs>([]);
+  const [run, setRun] = useState<RunTimelineRun>();
   const [runId, setRunId] = useState<string | undefined>(() => {
     if (persist && typeof window !== "undefined") {
       return localStorage.getItem(STORAGE_KEY) || undefined;
@@ -120,6 +126,7 @@ export function useRun<T extends z.ZodObject<any>>(
       setRunId(newRunId);
       setMessages([]);
       setRun(undefined);
+      setJobs([]);
       lastMessageId.current = null;
     },
     [persist]
@@ -136,29 +143,36 @@ export function useRun<T extends z.ZodObject<any>>(
       if (!runId) return;
 
       try {
-        const [messageResponse, runResponse] = await Promise.all([
-          inferable.client.listMessages({
+        const [timelineResponse] = await Promise.all([
+          inferable.client.getRunTimeline({
             params: { clusterId: inferable.clusterId, runId: runId },
             query: {
-              after: lastMessageId.current ?? "0",
-              waitTime: 20,
+              messagesAfter: lastMessageId.current ?? "0",
             },
           }),
-          inferable.client.getRun({
-            params: { clusterId: inferable.clusterId, runId: runId },
-          }),
         ]);
 
+
         if (!isMounted) return;
 
-        if (messageResponse.status === 200) {
+        if (timelineResponse.status === 200) {
+
+          const runHasChanged = JSON.stringify(timelineResponse.body.run) !== JSON.stringify(run);
+
+          if (runHasChanged) {
+            setRun(timelineResponse.body.run);
+          }
+
+          const jobsHasChanged = JSON.stringify(timelineResponse.body.jobs) !== JSON.stringify(jobs);
+          setJobs(timelineResponse.body.jobs);
+
           lastMessageId.current =
-            messageResponse.body.sort((a, b) => b.id.localeCompare(a.id))[0]?.id ??
+            timelineResponse.body.messages.sort((a, b) => b.id.localeCompare(a.id))[0]?.id ??
             lastMessageId.current;
 
           setMessages(existing =>
             existing.concat(
-              messageResponse.body.filter(
+              timelineResponse.body.messages.filter(
                 message =>
                   message.type === "agent" ||
                   message.type === "human" ||
@@ -169,21 +183,11 @@ export function useRun<T extends z.ZodObject<any>>(
         } else {
           setError(
             new Error(
-              `Could not list messages. Status: ${messageResponse.status} Body: ${JSON.stringify(messageResponse.body)}`
+              `Could not list messages. Status: ${timelineResponse.status} Body: ${JSON.stringify(timelineResponse.body)}`
             )
           );
         }
 
-        if (runResponse.status === 200) {
-          const runHasChanged = JSON.stringify(runResponse.body) !== JSON.stringify(run);
-
-          if (runHasChanged) {
-            setRun(runResponse.body);
-          }
-        } else {
-          setError(new Error(`Could not get run. Status: ${runResponse.status}`));
-        }
-
         // Schedule next poll
         timeoutId = setTimeout(pollMessages, 1000);
       } catch (error) {
@@ -226,12 +230,35 @@ export function useRun<T extends z.ZodObject<any>>(
     [inferable.client, runId]
   );
 
+
+  const submitApproval = useMemo(
+    () => async (jobId: string, approved: boolean) => {
+      const response = await inferable.client.createJobApproval({
+        body: { approved },
+        params: { clusterId: inferable.clusterId, jobId },
+      })
+
+
+      if (response.status !== 204) {
+        setError(
+          new Error(
+            `Could not submit approval. Status: ${response.status} Body: ${JSON.stringify(response.body)}`
+          )
+        );
+      }
+
+    }, [inferable.client]
+  );
+
+
   return {
     createMessage,
     messages,
+    jobs,
     run,
     result: run?.result ? run.result : undefined,
     error,
     setRunId: setRunIdWithPersistence,
+    submitApproval,
   };
 }