chore: add helpers

packages/framework/src/agent.ts

@@ -3,7 +3,7 @@ import { zodFunction, zodResponseFormat } from 'openai/helpers/zod.js'
 import { z } from 'zod'
 
 import { openai, Provider } from './models.js'
-import { WorkflowState } from './state.js'
+import { finish, WorkflowState } from './state.js'
 import { Tool } from './tool.js'
 import { Message } from './types.js'
 import { Workflow } from './workflow.js'
@@ -131,11 +131,7 @@ export const agent = (options: AgentOptions = {}): Agent => {
           }
         }
 
-        return {
-          ...state,
-          status: 'finished',
-          messages: [state.messages[0], agentResponse],
-        }
+        return finish(state, agentResponse)
       }),
   }
 }

packages/framework/src/agents/final_boss.ts

@@ -3,6 +3,7 @@ import { zodResponseFormat } from 'openai/helpers/zod'
 import { z } from 'zod'
 
 import { agent, AgentOptions } from '../agent.js'
+import { finish } from '../state.js'
 
 const defaults: AgentOptions = {
   run: async (state, context, workflow) => {
@@ -34,11 +35,7 @@ const defaults: AgentOptions = {
     if (!result) {
       throw new Error('No parsed response received')
     }
-    return {
-      ...state,
-      status: 'finished',
-      messages: [...state.messages, { role: 'assistant', content: result.finalAnswer }],
-    }
+    return finish(state, { role: 'assistant', content: result.finalAnswer })
   },
 }
 

packages/framework/src/agents/resource_planner.ts

@@ -3,7 +3,7 @@ import { zodResponseFormat } from 'openai/helpers/zod'
 import { z } from 'zod'
 
 import { agent, AgentOptions } from '../agent.js'
-import { childState } from '../state.js'
+import { handoff } from '../state.js'
 
 const defaults: AgentOptions = {
   run: async (state, context, workflow) => {
@@ -54,10 +54,7 @@ const defaults: AgentOptions = {
       throw new Error('No content in response')
     }
 
-    return childState({
-      agent: content.agent,
-      messages: state.messages,
-    })
+    return handoff(state, content.agent, state.messages)
   },
 }
 

packages/framework/src/agents/supervisor.ts

@@ -4,7 +4,7 @@ import { z } from 'zod'
 
 import { agent, AgentOptions } from '../agent.js'
 import { getSteps } from '../messages.js'
-import { childState } from '../state.js'
+import { delegate } from '../state.js'
 
 const defaults: AgentOptions = {
   run: async (state, context, workflow) => {
@@ -68,21 +68,16 @@ const defaults: AgentOptions = {
         }
       }
 
-      const requests = content.tasks.map((request) => ({
-        role: 'user' as const,
-        content: request.task,
-      }))
-
-      return {
-        ...state,
-        status: 'running',
-        children: requests.map((request) =>
-          childState({
-            agent: 'resourcePlanner',
-            messages: [request],
-          })
-        ),
-      }
+      return delegate(
+        state,
+        content.tasks.map((item) => [
+          'resourcePlanner',
+          {
+            role: 'user',
+            content: item.task,
+          },
+        ])
+      )
     } catch (error) {
       throw new Error('Failed to determine next task')
     }

packages/framework/src/iterate.ts

@@ -1,4 +1,4 @@
-import { childState, WorkflowState } from './state.js'
+import { childState, finish, WorkflowState } from './state.js'
 import { runTools } from './tool_calls.js'
 import { Message } from './types.js'
 import { Workflow } from './workflow.js'
@@ -45,13 +45,13 @@ export async function run(
   }
 
   if (state.status === 'running' || state.status === 'idle') {
-    return agent.run(state, context, workflow)
-  }
-
-  if (state.status === 'failed') {
-    return {
-      ...state,
-      status: 'finished',
+    try {
+      return agent.run(state, context, workflow)
+    } catch (error) {
+      return finish(state, {
+        role: 'assistant',
+        content: error instanceof Error ? error.message : 'Unknown error',
+      })
     }
   }
 

packages/framework/src/state.ts

@@ -37,3 +37,39 @@ export const rootState = (workflow: Workflow): WorkflowState =>
   })
 
 export type WorkflowState = Required<WorkflowStateOptions>
+
+export const getRequest = (state: WorkflowState): Message => {
+  return state.messages[0]
+}
+
+export const finish = (state: WorkflowState, response: Message): WorkflowState => {
+  return {
+    ...state,
+    status: 'finished',
+    messages: [getRequest(state), response],
+  }
+}
+
+export const delegate = (state: WorkflowState, requests: [string, Message][]): WorkflowState => {
+  return {
+    ...state,
+    status: 'running',
+    children: requests.map(([agent, request]) =>
+      childState({
+        agent,
+        messages: [request],
+      })
+    ),
+  }
+}
+
+export const handoff = (
+  state: WorkflowState,
+  agent: string,
+  messages: Message[]
+): WorkflowState => {
+  return childState({
+    agent,
+    messages,
+  })
+}