refactor(core)!: rework agent run lifecycle and status semantics
BREAKING CHANGE: stop() is now async and resolves after the run fully settles; status decouples from task outcome (new 'stopped' state, LLM self-reported failure now ends as 'completed'). Lifecycle hooks re-throw instead of being folded into the result; agent errors go to history. Adds agent.lastResult.
This commit is contained in:
Simon
@@ -42,7 +42,7 @@ export type PageAgentCoreConfig = AgentConfig & { pageController: PageController
|
||||
* - loop
|
||||
*
|
||||
* ## Event System
|
||||
* - `statuschange` - Agent status transitions (idle → running → completed/error)
|
||||
* - `statuschange` - Agent status transitions (idle → running → completed/error/stopped)
|
||||
* - `historychange` - History events updated (persistent, part of agent memory)
|
||||
* - `activity` - Real-time activity feedback (transient, for UI only)
|
||||
* - `dispose` - Agent cleanup triggered
|
||||
@@ -91,6 +91,10 @@ export class PageAgentCore extends EventTarget {
|
||||
#abortController = new AbortController()
|
||||
#observations: string[] = []
|
||||
|
||||
/** Resolves when the current run has fully settled. Awaited by `stop()`. */
|
||||
#running: Promise<void> = Promise.resolve()
|
||||
#lastResult: ExecutionResult | null = null
|
||||
|
||||
/** internal states during a single task execution */
|
||||
#states = {
|
||||
/** Accumulated wait time in seconds */
|
||||
@@ -147,13 +151,19 @@ export class PageAgentCore extends EventTarget {
|
||||
return this.#status
|
||||
}
|
||||
|
||||
/** Result of the most recent run, or `null` before the first run completes. */
|
||||
get lastResult(): ExecutionResult | null {
|
||||
return this.#lastResult
|
||||
}
|
||||
|
||||
/** Emit statuschange event */
|
||||
#emitStatusChange(): void {
|
||||
this.dispatchEvent(new Event('statuschange'))
|
||||
}
|
||||
|
||||
/** Emit historychange event */
|
||||
#emitHistoryChange(): void {
|
||||
#emitHistoryChange(pushHistoricalEvent?: HistoricalEvent): void {
|
||||
if (pushHistoricalEvent) this.history.push(pushHistoricalEvent)
|
||||
this.dispatchEvent(new Event('historychange'))
|
||||
}
|
||||
|
||||
@@ -183,14 +193,22 @@ export class PageAgentCore extends EventTarget {
|
||||
this.#observations.push(content)
|
||||
}
|
||||
|
||||
/** Stop the current task. Agent remains reusable. */
|
||||
stop() {
|
||||
this.pageController.cleanUpHighlights()
|
||||
this.pageController.hideMask()
|
||||
/**
|
||||
* Stop the current task and wait until the run has fully settled.
|
||||
* Once resolved, `status` is `stopped` and the agent can be reused.
|
||||
*/
|
||||
async stop(): Promise<void> {
|
||||
if (this.#status !== 'running') return
|
||||
this.#abortController.abort()
|
||||
await this.#running
|
||||
}
|
||||
|
||||
/**
|
||||
* external errors (pre-checks/config/hooks) will threw;
|
||||
* agent errors will be caught and added to history, and return a failed result
|
||||
*/
|
||||
async execute(task: string): Promise<ExecutionResult> {
|
||||
// pre-checks
|
||||
if (this.disposed) throw new Error('PageAgent has been disposed. Create a new instance.')
|
||||
if (this.#status === 'running') throw new Error('A task is already running.')
|
||||
if (!task) throw new Error('Task is required')
|
||||
@@ -206,131 +224,137 @@ export class PageAgentCore extends EventTarget {
|
||||
this.#setStatus('running')
|
||||
this.#emitHistoryChange()
|
||||
|
||||
let resolveRunning!: () => void
|
||||
this.#running = new Promise<void>((resolve) => (resolveRunning = resolve))
|
||||
|
||||
// Disable ask_user tool if onAskUser is not set
|
||||
if (!this.onAskUser) {
|
||||
this.tools.delete('ask_user')
|
||||
}
|
||||
if (!this.onAskUser) this.tools.delete('ask_user')
|
||||
|
||||
const onBeforeStep = this.config.onBeforeStep
|
||||
const onAfterStep = this.config.onAfterStep
|
||||
const onBeforeTask = this.config.onBeforeTask
|
||||
const onAfterTask = this.config.onAfterTask
|
||||
|
||||
// graceful exit
|
||||
try {
|
||||
await onBeforeTask?.(this)
|
||||
await this.pageController.showMask()
|
||||
} catch (error) {
|
||||
this.#setStatus('error')
|
||||
throw error
|
||||
}
|
||||
|
||||
let step = 0
|
||||
let taskSuccess: boolean
|
||||
let taskResult: string
|
||||
await onBeforeTask?.(this)
|
||||
|
||||
while (true) {
|
||||
try {
|
||||
console.group(`step: ${step}`)
|
||||
let step = 0
|
||||
let taskResult: ExecutionResult
|
||||
|
||||
while (true) {
|
||||
await onBeforeStep?.(this, step)
|
||||
|
||||
// observe
|
||||
// handle internal agent errors
|
||||
try {
|
||||
console.group(`step: ${step}`)
|
||||
|
||||
console.log(chalk.blue.bold('👀 Observing...'))
|
||||
// observe
|
||||
|
||||
this.#states.browserState = await this.pageController.getBrowserState()
|
||||
await this.#handleObservations(step)
|
||||
console.log(chalk.blue.bold('👀 Observing...'))
|
||||
|
||||
// assemble prompts
|
||||
this.#states.browserState = await this.pageController.getBrowserState()
|
||||
await this.#handleObservations(step)
|
||||
|
||||
const messages = [
|
||||
{ role: 'system' as const, content: this.#getSystemPrompt() },
|
||||
{ role: 'user' as const, content: await this.#assembleUserPrompt() },
|
||||
]
|
||||
// assemble prompts
|
||||
|
||||
const macroTool = { AgentOutput: this.#packMacroTool() }
|
||||
const messages = [
|
||||
{ role: 'system' as const, content: this.#getSystemPrompt() },
|
||||
{ role: 'user' as const, content: await this.#assembleUserPrompt() },
|
||||
]
|
||||
|
||||
// invoke LLM
|
||||
const macroTool = { AgentOutput: this.#packMacroTool() }
|
||||
|
||||
console.log(chalk.blue.bold('🧠 Thinking...'))
|
||||
this.#emitActivity({ type: 'thinking' })
|
||||
// invoke LLM
|
||||
|
||||
const result = await this.#llm.invoke(messages, macroTool, this.#abortController.signal, {
|
||||
toolChoiceName: 'AgentOutput',
|
||||
normalizeResponse: (res) => normalizeResponse(res, this.tools),
|
||||
})
|
||||
console.log(chalk.blue.bold('🧠 Thinking...'))
|
||||
this.#emitActivity({ type: 'thinking' })
|
||||
|
||||
// assemble history
|
||||
const result = await this.#llm.invoke(messages, macroTool, this.#abortController.signal, {
|
||||
toolChoiceName: 'AgentOutput',
|
||||
normalizeResponse: (res) => normalizeResponse(res, this.tools),
|
||||
})
|
||||
|
||||
const macroResult = result.toolResult as MacroToolResult
|
||||
const input = macroResult.input
|
||||
const output = macroResult.output
|
||||
const reflection: Partial<AgentReflection> = {
|
||||
evaluation_previous_goal: input.evaluation_previous_goal,
|
||||
memory: input.memory,
|
||||
next_goal: input.next_goal,
|
||||
// assemble history
|
||||
|
||||
const macroResult = result.toolResult as MacroToolResult
|
||||
const input = macroResult.input
|
||||
const output = macroResult.output
|
||||
const reflection: Partial<AgentReflection> = {
|
||||
evaluation_previous_goal: input.evaluation_previous_goal,
|
||||
memory: input.memory,
|
||||
next_goal: input.next_goal,
|
||||
}
|
||||
const actionName = Object.keys(input.action)[0]
|
||||
const action: AgentStepEvent['action'] = {
|
||||
name: actionName,
|
||||
input: input.action[actionName],
|
||||
output: output,
|
||||
}
|
||||
|
||||
this.#emitHistoryChange({
|
||||
type: 'step',
|
||||
stepIndex: step,
|
||||
reflection,
|
||||
action,
|
||||
usage: result.usage,
|
||||
rawResponse: result.rawResponse,
|
||||
rawRequest: result.rawRequest,
|
||||
})
|
||||
|
||||
if (actionName === 'done') {
|
||||
const success = action.input?.success ?? false
|
||||
const data = action.input?.text || 'no text provided'
|
||||
console.log(chalk.green.bold('Task completed'), success, data)
|
||||
taskResult = { success, data, history: this.history }
|
||||
this.#setStatus('completed')
|
||||
break
|
||||
}
|
||||
} catch (error: unknown) {
|
||||
const isAbortError = (error as any)?.name === 'AbortError'
|
||||
if (!isAbortError) console.error('Task failed', error)
|
||||
const message = isAbortError ? 'Task aborted' : String(error)
|
||||
this.#emitActivity({ type: 'error', message: message })
|
||||
this.#emitHistoryChange({ type: 'error', message: message, rawResponse: error })
|
||||
taskResult = { success: false, data: message, history: this.history }
|
||||
this.#setStatus(isAbortError ? 'stopped' : 'error')
|
||||
break
|
||||
} finally {
|
||||
console.groupEnd()
|
||||
}
|
||||
const actionName = Object.keys(input.action)[0]
|
||||
const action: AgentStepEvent['action'] = {
|
||||
name: actionName,
|
||||
input: input.action[actionName],
|
||||
output: output,
|
||||
}
|
||||
|
||||
this.history.push({
|
||||
type: 'step',
|
||||
stepIndex: step,
|
||||
reflection,
|
||||
action,
|
||||
usage: result.usage,
|
||||
rawResponse: result.rawResponse,
|
||||
rawRequest: result.rawRequest,
|
||||
} as AgentStepEvent)
|
||||
this.#emitHistoryChange()
|
||||
|
||||
await onAfterStep?.(this, this.history)
|
||||
|
||||
console.groupEnd()
|
||||
|
||||
if (actionName === 'done') {
|
||||
taskSuccess = action.input?.success ?? false
|
||||
taskResult = action.input?.text || 'no text provided'
|
||||
console.log(chalk.green.bold('Task completed'), taskSuccess, taskResult)
|
||||
step++
|
||||
if (step > this.config.maxSteps) {
|
||||
const message = 'Step count exceeded maximum limit'
|
||||
console.error(message)
|
||||
this.#emitActivity({ type: 'error', message: message })
|
||||
this.#emitHistoryChange({ type: 'error', message: message })
|
||||
taskResult = { success: false, data: message, history: this.history }
|
||||
this.#setStatus('error')
|
||||
break
|
||||
}
|
||||
} catch (error: unknown) {
|
||||
console.groupEnd()
|
||||
const isAbortError = (error as any)?.name === 'AbortError'
|
||||
if (!isAbortError) console.error('Task failed', error)
|
||||
taskResult = isAbortError ? 'Task aborted' : String(error)
|
||||
taskSuccess = false
|
||||
this.#emitActivity({ type: 'error', message: taskResult })
|
||||
this.history.push({ type: 'error', message: taskResult, rawResponse: error })
|
||||
this.#emitHistoryChange()
|
||||
break
|
||||
}
|
||||
|
||||
step++
|
||||
if (step > this.config.maxSteps) {
|
||||
taskResult = 'Step count exceeded maximum limit'
|
||||
taskSuccess = false
|
||||
this.#emitActivity({ type: 'error', message: taskResult })
|
||||
this.history.push({ type: 'error', message: taskResult })
|
||||
this.#emitHistoryChange()
|
||||
break
|
||||
}
|
||||
await waitFor(this.config.stepDelay ?? 0.4)
|
||||
} // while
|
||||
|
||||
await waitFor(this.config.stepDelay ?? 0.4)
|
||||
await onAfterTask?.(this, taskResult)
|
||||
|
||||
this.#lastResult = taskResult
|
||||
return taskResult
|
||||
} catch (error) {
|
||||
this.#emitActivity({ type: 'error', message: String(error) })
|
||||
this.#setStatus('error')
|
||||
throw error
|
||||
} finally {
|
||||
this.pageController.cleanUpHighlights()
|
||||
this.pageController.hideMask()
|
||||
this.#abortController.abort()
|
||||
resolveRunning()
|
||||
}
|
||||
|
||||
this.#onDone(taskSuccess)
|
||||
const result: ExecutionResult = {
|
||||
success: taskSuccess,
|
||||
data: taskResult,
|
||||
history: this.history,
|
||||
}
|
||||
await onAfterTask?.(this, result)
|
||||
return result
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -605,13 +629,6 @@ export class PageAgentCore extends EventTarget {
|
||||
return prompt
|
||||
}
|
||||
|
||||
#onDone(success = true) {
|
||||
this.pageController.cleanUpHighlights()
|
||||
this.pageController.hideMask() // No await - fire and forget
|
||||
this.#setStatus(success ? 'completed' : 'error')
|
||||
this.#abortController.abort()
|
||||
}
|
||||
|
||||
dispose() {
|
||||
console.log('Disposing PageAgent...')
|
||||
this.disposed = true
|
||||
|
||||
Reference in New Issue
Block a user