feat: add Plugin Common Tools roadmap documentation

- Introduced HTML and Markdown versions of the Plugin Common Tools roadmap.
- Documented phases of development, including goals, status, scope, tasks, and acceptance criteria.
- Established a status legend for tracking progress on each phase.
- Highlighted the need for discussions on approval policies affecting multiple phases.

Author: exoticknight

examples/copilotkit/src/components/chat-panel.tsx

@@ -30,7 +30,6 @@ interface ChatPanelProps {
   threadId: string
 }
 
-type DemoDecision = 'approved' | 'rejected'
 type DemoScope = 'call' | 'conversation' | 'run'
 
 interface DemoToolbarProps {
@@ -137,17 +136,8 @@ const useRunChatMessage = () => {
   }, [agent, copilotkit])
 }
 
-const HITL_APPROVED_MESSAGE_PREFIX = 'Approved HITL request'
-const HITL_REJECTED_MESSAGE_PREFIX = 'Rejected HITL request'
 const buttonClass = 'rounded border border-border bg-background px-2 py-1 text-xs hover:bg-muted disabled:cursor-not-allowed disabled:opacity-60'
 
-const createResumeMessage = (decision: DemoDecision, id: string, scope?: DemoScope) => {
-  if (decision === 'rejected')
-    return `${HITL_REJECTED_MESSAGE_PREFIX} ${id}`
-
-  return `${HITL_APPROVED_MESSAGE_PREFIX} ${id}${scope == null ? '' : ` (${scope})`}`
-}
-
 const DemoToolbar = ({ agentInstance, demoReplay, hitlControl }: DemoToolbarProps) => {
   const runChatMessage = useRunChatMessage()
   const [runningAction, setRunningAction] = useState<HITLDemoAction>()
@@ -193,12 +183,11 @@ const DemoToolbar = ({ agentInstance, demoReplay, hitlControl }: DemoToolbarProp
 }
 
 const HitlToolCard = ({ args, hitlControl, name, result, status, toolCallId }: HitlToolCardProps) => {
-  const runChatMessage = useRunChatMessage()
   const review = parseHitlReview(result)
   const reviewPending = review == null ? false : hitlControl.pending().some(request => request.id === review.id)
-  const [busy, setBusy] = useState<DemoDecision>()
+  const [busy, setBusy] = useState<'approved' | 'rejected'>()
 
-  const resume = async (decision: DemoDecision, scope?: DemoScope) => {
+  const decide = (decision: 'approved' | 'rejected', scope?: DemoScope) => {
     if (review == null)
       return
 
@@ -210,12 +199,6 @@ const HitlToolCard = ({ args, hitlControl, name, result, status, toolCallId }: H
       return
 
     setBusy(decision)
-    try {
-      await runChatMessage(createResumeMessage(decision, review.id, scope))
-    }
-    finally {
-      setBusy(undefined)
-    }
   }
 
   if (review != null && !reviewPending)
@@ -231,10 +214,10 @@ const HitlToolCard = ({ args, hitlControl, name, result, status, toolCallId }: H
         <div className="mb-2 text-xs text-amber-900">{review.reason}</div>
         <pre className="mb-3 max-h-40 overflow-auto rounded bg-background/80 p-2 text-xs leading-snug">{prettyJson(review.args)}</pre>
         <div className="flex flex-wrap gap-2">
-          <button className={buttonClass} disabled={busy != null} onClick={() => void resume('approved', 'call')} type="button">Approve once</button>
-          <button className={buttonClass} disabled={busy != null} onClick={() => void resume('approved', 'run')} type="button">Approve turn</button>
-          <button className={buttonClass} disabled={busy != null} onClick={() => void resume('approved', 'conversation')} type="button">Approve conversation</button>
-          <button className={buttonClass} disabled={busy != null} onClick={() => void resume('rejected')} type="button">Reject</button>
+          <button className={buttonClass} disabled={busy != null} onClick={() => decide('approved', 'call')} type="button">Approve once</button>
+          <button className={buttonClass} disabled={busy != null} onClick={() => decide('approved', 'run')} type="button">Approve turn</button>
+          <button className={buttonClass} disabled={busy != null} onClick={() => decide('approved', 'conversation')} type="button">Approve conversation</button>
+          <button className={buttonClass} disabled={busy != null} onClick={() => decide('rejected')} type="button">Reject</button>
         </div>
       </div>
     )

examples/copilotkit/test/hitl-runtime.test.ts

@@ -4,7 +4,7 @@ import { createAgent } from '@apeira/core'
 import { hitl } from '@apeira/plugin-hitl'
 import { describe, expect, it } from 'vitest'
 
-import { createHitlDemoTools, createHitlReplayFetch, createHitlResumeInput } from '../../shared/hitl-demo'
+import { createHitlDemoTools, createHitlReplayFetch } from '../../shared/hitl-demo'
 
 const userInput = (content: string): ItemParam => ({
   content,
@@ -27,6 +27,29 @@ const readEvents = async (stream: ReadableStream<AgentEvent>) => {
   return events
 }
 
+const readEventsAndDecide = async (
+  stream: ReadableStream<AgentEvent>,
+  decide: (id: string) => void,
+) => {
+  const reader = stream.getReader()
+  const events: AgentEvent[] = []
+  let decided = false
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done)
+      break
+
+    events.push(value)
+    if (!decided && value.type === 'tool-interruption') {
+      decided = true
+      decide(value.interruption.id)
+    }
+  }
+
+  return events
+}
+
 const createDemoSession = () => {
   const controller = hitl({ mode: 'ask' })
   const replay = createHitlReplayFetch()
@@ -58,68 +81,78 @@ const text = (events: AgentEvent[]) =>
 describe('hitl demo runtime integration', () => {
   it('asks again after a call-scope approval', async () => {
     const { controller, session } = createDemoSession()
-    const first = await readEvents(session.run(userInput('hitl-demo once')))
+    const first = await readEventsAndDecide(
+      session.run(userInput('hitl-demo once')),
+      id => expect(controller.approve(id, 'call')).toBe(true),
+    )
     const id = interruptions(first)[0].interruption.id
 
     expect(id).toBeDefined()
-    expect(controller.approve(id, 'call')).toBe(true)
-    await readEvents(session.run(userInput(createHitlResumeInput(id, 'approved'))))
 
-    const second = await readEvents(session.run(userInput('hitl-demo once')))
+    const second = await readEventsAndDecide(
+      session.run(userInput('hitl-demo once')),
+      id => expect(controller.reject(id)).toBe(true),
+    )
     expect(interruptions(second)).toHaveLength(1)
   })
 
   it('lets run-scope approval continue repeated same-key calls in one resumed turn only', async () => {
     const { controller, session } = createDemoSession()
-    const first = await readEvents(session.run(userInput('hitl-demo turn')))
+    const first = await readEventsAndDecide(
+      session.run(userInput('hitl-demo turn')),
+      id => expect(controller.approve(id, 'run')).toBe(true),
+    )
     const id = interruptions(first)[0].interruption.id
 
     expect(id).toBeDefined()
-    expect(controller.approve(id, 'run')).toBe(true)
 
-    const resumed = await readEvents(session.run(userInput(createHitlResumeInput(id, 'approved'))))
-    expect(interruptions(resumed)).toHaveLength(0)
-
-    const nextTurn = await readEvents(session.run(userInput('hitl-demo turn')))
+    const nextTurn = await readEventsAndDecide(
+      session.run(userInput('hitl-demo turn')),
+      id => expect(controller.reject(id)).toBe(true),
+    )
     expect(interruptions(nextTurn)).toHaveLength(1)
   })
 
   it('remembers conversation-scope approvals by exact key', async () => {
     const { controller, session } = createDemoSession()
-    const first = await readEvents(session.run(userInput('hitl-demo conversation')))
+    const first = await readEventsAndDecide(
+      session.run(userInput('hitl-demo conversation')),
+      id => expect(controller.approve(id, 'conversation')).toBe(true),
+    )
     const id = interruptions(first)[0].interruption.id
 
     expect(id).toBeDefined()
-    expect(controller.approve(id, 'conversation')).toBe(true)
-    await readEvents(session.run(userInput(createHitlResumeInput(id, 'approved'))))
 
     const sameKey = await readEvents(session.run(userInput('hitl-demo conversation')))
     expect(interruptions(sameKey)).toHaveLength(0)
   })
 
   it('keeps approval-key exact after a conversation approval', async () => {
     const { controller, session } = createDemoSession()
-    const first = await readEvents(session.run(userInput('hitl-demo approval-key')))
+    const first = await readEventsAndDecide(
+      session.run(userInput('hitl-demo approval-key')),
+      id => expect(controller.approve(id, 'conversation')).toBe(true),
+    )
     const id = interruptions(first)[0].interruption.id
 
     expect(id).toBeDefined()
-    expect(controller.approve(id, 'conversation')).toBe(true)
-    await readEvents(session.run(userInput(createHitlResumeInput(id, 'approved'))))
 
-    const dangerous = await readEvents(session.run(userInput('hitl-demo approval-key')))
+    const dangerous = await readEventsAndDecide(
+      session.run(userInput('hitl-demo approval-key')),
+      id => expect(controller.reject(id)).toBe(true),
+    )
     expect(JSON.stringify(dangerous)).toContain('rm -rf .')
     expect(interruptions(dangerous)).toHaveLength(1)
   })
 
   it('returns a model-visible rejection summary', async () => {
     const { controller, session } = createDemoSession()
-    const first = await readEvents(session.run(userInput('hitl-demo reject')))
-    const id = interruptions(first)[0].interruption.id
-
-    expect(id).toBeDefined()
-    expect(controller.reject(id, 'TOOL_HITL_REJECTED: denied in demo')).toBe(true)
+    const events = await readEventsAndDecide(
+      session.run(userInput('hitl-demo reject')),
+      id => expect(controller.reject(id, 'TOOL_HITL_REJECTED: denied in demo')).toBe(true),
+    )
 
-    const resumed = await readEvents(session.run(userInput(createHitlResumeInput(id, 'rejected'))))
-    expect(text(resumed)).toContain('用户拒绝')
+    expect(interruptions(events)[0].interruption.id).toBeDefined()
+    expect(text(events)).toContain('用户拒绝')
   })
 })

examples/pi-tui/src/app.ts

@@ -11,7 +11,6 @@ import c from 'tinyrainbow'
 import { formatSkillInvocation } from '@apeira/plugin-skills'
 import { Box, CombinedAutocompleteProvider, Container, Editor, Markdown, matchesKey, ProcessTerminal, Spacer, Text, TUI } from '@earendil-works/pi-tui'
 
-import { createHitlResumeInput } from '../../shared/hitl-demo'
 import { agent, hitlControl, hitlDemoEnabled, hitlDemoReplay, skillsDir, skillSet } from './utils/agent'
 import { model, workspaceRoot } from './utils/config'
 import { appendTranscriptEntry } from './utils/hitl-demo-transcript'
@@ -367,37 +366,25 @@ export const createPiTuiExampleApp = () => {
 
       case 'tool-interruption': {
         sawHitlInterruption = true
-        const hitlEvent = event as AgentEvent & {
-          interruption: {
-            id: string
-            reason?: string
-            toolCall: {
-              function: {
-                arguments?: string
-                name?: string
-              }
-            }
-          }
-        }
-        const toolName = hitlEvent.interruption.toolCall.function.name ?? 'tool'
-        const args = parseToolArguments(hitlEvent.interruption.toolCall.function.arguments ?? '{}')
+        const toolName = event.interruption.toolCall.toolName
+        const args = parseToolArguments(event.interruption.toolCall.args)
         const entry = pushEntry('tool', [
           formatToolCallSummary(toolName, args),
-          c.yellow(hitlEvent.interruption.reason ?? 'Human review required.'),
-          c.gray(`/approve ${hitlEvent.interruption.id} call|turn|conversation`),
-          c.gray(`/reject ${hitlEvent.interruption.id}`),
+          c.yellow(event.interruption.reason ?? 'Human review required.'),
+          c.gray(`/approve ${event.interruption.id} call|turn|conversation`),
+          c.gray(`/reject ${event.interruption.id}`),
         ].join('\n'), {
           state: 'pending',
           title: toolName,
         })
-        toolEntries.set(hitlEvent.interruption.id, entry)
+        toolEntries.set(event.interruption.id, entry)
         break
       }
 
       case 'tool-result.done': {
         if (hitlDemoEnabled && !sawHitlInterruption && !showedMissingHitlRuntimeWarning) {
           showedMissingHitlRuntimeWarning = true
-          pushSystem('HITL demo warning: the installed xsAI runtime did not emit tool-interruption before executing the tool. Run Apeira with xsAI HITL primitives installed.')
+          pushSystem('HITL demo warning: no HITL review event was emitted before the tool result. Check plugin-hitl and xsAI tool hook wiring.')
         }
 
         const existing = toolEntries.get(event.toolResult.id)
@@ -460,14 +447,6 @@ export const createPiTuiExampleApp = () => {
 
   const unsubscribe = agent.subscribe('apeira', onEvent)
 
-  const sendHiddenResume = (id: string, decision: 'approved' | 'rejected') => {
-    runningTurnId = agent.send({
-      content: createHitlResumeInput(id, decision),
-      role: 'user',
-      type: 'message',
-    })
-  }
-
   const sendDemoScenario = (action: HITLDemoAction) => {
     if (!hitlDemoEnabled) {
       pushSystem('Demo scenarios are only available when APEIRA_HITL_DEMO=1.')
@@ -521,8 +500,7 @@ export const createPiTuiExampleApp = () => {
         const normalizedScope = normalizeApprovalScope(scope) ?? { label: 'conversation', value: 'conversation' }
         const approved = hitlControl.approve(id, normalizedScope.value)
         if (approved) {
-          pushSystem(`Approved ${id} (${normalizedScope.label}); resuming...`)
-          sendHiddenResume(id, 'approved')
+          pushSystem(`Approved ${id} (${normalizedScope.label}); continuing current tool call...`)
         }
         else {
           pushSystem(`No pending HITL request: ${id}`)
@@ -643,8 +621,7 @@ export const createPiTuiExampleApp = () => {
 
         const rejected = hitlControl.reject(id, argument.slice(id.length).trim() || undefined)
         if (rejected) {
-          pushSystem(`Rejected ${id}; resuming...`)
-          sendHiddenResume(id, 'rejected')
+          pushSystem(`Rejected ${id}; continuing current tool call...`)
         }
         else {
           pushSystem(`No pending HITL request: ${id}`)

packages/core/src/index.ts

@@ -31,9 +31,6 @@ export type {
   ToolCallControl,
   ToolCallControlContext,
   ToolCallControlOptions,
-  ToolCallDecision,
-  ToolCallPostContext,
-  ToolCallStatus,
   ToolInterruption,
   TurnDoneOptions,
   TurnStartOptions,

packages/core/src/types/plugin.ts

@@ -1,9 +1,9 @@
 import type { ResponsesOptions } from '@xsai-ext/responses'
-import type { Tool, ToolCall } from '@xsai/shared-chat'
+import type { CompletionToolCall, CompletionToolResult, Message, Tool } from '@xsai/shared-chat'
 
 import type { Episodic } from '../episodic'
 import type { AgentContext, ItemParam, MaybePromise } from './base'
-import type { AgentEvent } from './event'
+import type { AgentEvent, ApeiraEvent } from './event'
 
 export interface AgentChannelMap {
   apeira: AgentEvent
@@ -103,39 +103,25 @@ export interface StorageLike {
 }
 
 export interface ToolCallControl {
-  postToolCall?: (context: ToolCallPostContext) => MaybePromise<unknown>
-  preToolCall?: (context: ToolCallControlContext) => MaybePromise<ToolCallDecision>
+  postToolCall?: (toolResult: CompletionToolResult, context: ToolCallControlContext) => MaybePromise<CompletionToolResult | void>
+  preToolCall?: (toolCall: CompletionToolCall, context: ToolCallControlContext) => MaybePromise<CompletionToolCall | CompletionToolResult | void>
 }
 
 export interface ToolCallControlContext {
   abortSignal?: AbortSignal
-  messages: unknown[]
-  parsedArgs: Record<string, unknown>
-  tool: Tool
-  toolCall: ToolCall
+  emit?: (event: ApeiraEvent) => void
+  messages: Message[]
+  sessionId?: string
+  turnId?: string
 }
 
 export interface ToolCallControlOptions<T = unknown> extends ResolveToolsOptions<T> {}
 
-export type ToolCallDecision
-  = | { interruption: ToolInterruption, type: 'interrupt' }
-    | { message?: string, result?: unknown, type: 'reject' }
-    | { message?: string, result?: unknown, type: 'skip' }
-    | { type: 'continue' }
-
-export interface ToolCallPostContext extends ToolCallControlContext {
-  error?: unknown
-  result?: unknown
-  status: ToolCallStatus
-}
-
-export type ToolCallStatus = 'error' | 'interrupted' | 'rejected' | 'skipped' | 'success'
-
 export interface ToolInterruption {
   data?: unknown
   id: string
   reason?: string
-  toolCall: ToolCall
+  toolCall: CompletionToolCall
 }
 
 export interface TurnDoneOptions<T = unknown> extends ResponseOptions<T> {

packages/core/src/utils/agent-runtime.ts

@@ -34,8 +34,8 @@ export interface AgentRuntimeOptions<T> {
   instructions: Instructions<T>
   loadSession: () => Promise<SessionState<T> | void> | SessionState<T> | void
   onTurnDone: (plugin: AgentPlugin<T>, options: TurnDoneOptions<T>) => Promise<void> | void
-  pluginStates?: Record<string, unknown>
   plugins: AgentPlugin<T>[]
+  pluginStates?: Record<string, unknown>
   ready: () => Promise<void>
   responseOptions: Omit<ResponsesOptions, 'abortSignal' | 'input' | 'instructions'>
   saveSession: (state: SessionState<T>) => Promise<void> | void
@@ -271,8 +271,8 @@ export const createAgentRuntime = <T>(options: AgentRuntimeOptions<T>): AgentRun
       episodic: workingEpisodic,
       getContext: options.getContext,
       instructions: options.instructions,
-      pluginState: workingPluginState,
       plugins: options.plugins,
+      pluginState: workingPluginState,
       ready: options.ready,
       responseOptions: options.responseOptions,
       sessionId: options.sessionId,