The all-in-one local AI studio for your desktop: chat, image and video generation and a coding agent in one free, open source app. Windows and Linux. No Docker, no terminal, no cloud required.
TypeScript agentai-chatai-studioall-in-onecoding-agentdesktop-appfluximage-generationlinuxllmlocal-ailocal-llmopen-sourceprivacyself-hostedstable-diffusionuncensoreduncensored-aivideo-generationwindows
/**
* Phase 5 (v2.4.0) — Parallel tool executor.
*
* Replaces the serial for-loop in useAgentChat / useCodex / mobile ReAct
* with a scheduler that:
*
* 1. Validates args via args-validator (Phase 4).
* 2. Records dispatch to toolAuditStore (Phase 2).
* 3. Groups calls by sideEffectKey (Phase 5) — same key serial, different
* keys parallel. Pure reads (no key) run fully in parallel.
* 4. Uses Promise.allSettled so one failure does not abort siblings.
* 5. Reports per-call completion back to the caller via onComplete.
*
* The executor is deliberately framework-agnostic — no React, no Zustand
* calls (stores are plumbed in via dependency injection). This keeps it
* testable in node-env vitest and keeps the hook integration thin.
*/
import type { AgentToolCall } from '../../types/agent-mode'
import { toolResultIsFailure } from '../../lib/tool-result-failure'
import { markRunTaint } from '../../lib/run-taint'
import { runForCall } from '../agent-context'
import type { AgentRunContext } from '../agent-context'
import { deriveSideEffectKey } from './side-effect-key'
import { validateToolArgs, formatValidationErrors, type JsonSchema } from './args-validator'
import { stableArgsHash } from './block-helpers'
import type { ToolArgs } from '../mcp/types'
import { isGenericCallName } from '../../lib/loose-tool-parse'
export interface ExecutorToolDef {
name: string
inputSchema?: JsonSchema
}
export interface ExecutionRequest {
/** Unique id for this tool call, matches AgentToolCall.id. */
id: string
/** Tool name — must be registered in the executor's runtime. */
toolName: string
/** Raw args from the LLM. */
args: ToolArgs
/** Optional parent id for sub-agent lineage. */
parentToolCallId?: string
/**
* The run this call belongs to (plan 2.6.6 C1, ERZWINGUNG). Carries the
* conversation id and the coding-agent mode down to the executor gates, so
* they check against THIS run instead of a process-wide global that a second,
* interleaving run can overwrite. Undefined on surfaces that do not thread
* yet; those keep the singleton behaviour.
*/
run?: AgentRunContext
}
export interface ExecutionResult {
id: string
toolName: string
status: 'completed' | 'failed' | 'rejected' | 'cached'
/** String result (executor outputs). */
result?: string
error?: string
/** Human-readable retry hint (filled by Phase 7 error-hints module). */
errorHint?: string
/** Validated + coerced args that were actually dispatched. */
dispatchedArgs: ToolArgs
argsHash: string
sideEffectKey?: string
startedAt: number
completedAt: number
durationMs: number
cacheHit: boolean
/** True when args-validator accepted the args (or no schema was provided). */
schemaValidated: boolean
/** When validation failed, the error text sent to the next LLM turn. */
validationError?: string
}
/**
* Dispatch one registered tool. The third argument is the run the call belongs
* to (see ExecutionRequest.run); the fourth is the run's Stop.
*
* The signal used to stop at this boundary: executeParallel checked it before
* DISPATCHING a call and never again, so Stop only kept the not-yet-started
* calls of a batch from firing. A shell command that was already running kept
* mutating the repository for up to its full timeout (615 s) after the user
* pressed the one brake the product offers for an unattended agent with full
* shell access. A tool that can be cancelled needs the signal in its own hands;
* a runtime that does not care simply declares fewer parameters.
*/
export type ExecutorFn = (
name: string,
args: ToolArgs,
run?: AgentRunContext,
signal?: AbortSignal,
) => Promise<string>
/**
* Pre-dispatch approval gate. Resolves true to let the call run, false to
* mark it 'rejected' without ever reaching the executor.
*/
export type ApprovalGate = (req: ExecutionRequest, tool: ExecutorToolDef) => Promise<boolean>
/** Audit sink (Phase 2). Called once at dispatch and once at completion. */
export type AuditRecorder = (entry: AuditHook) => void
/**
* The one gate that is NOT optional: every caller must say, in writing, what
* happens before a tool runs.
*
* It used to be optional, and the omission was invisible — a runtime that
* simply left the field out ran shell_execute / file_write / file_edit
* unattended even though all three default to 'confirm'. That is exactly how
* the sub-agent's nested ReAct loop ended up with no approval prompt at all
* (audit AGT-1): nobody wrote `awaitApproval`, so nobody saw it missing.
* Making it required turns that silent hole into a compile error. A surface
* that genuinely runs unattended passes APPROVE_ALL and thereby says so.
*/
export const APPROVE_ALL: ApprovalGate = async () => true
export interface ExecutorRuntime {
/** Resolve a tool by name — returns undefined for unknown tools. */
getTool: (name: string) => ExecutorToolDef | undefined
/** Execute a registered tool against args; returns string result. */
execute: ExecutorFn
/**
* REQUIRED — called before dispatch to gate on user approval. Pass
* APPROVE_ALL to opt out explicitly; there is no implicit opt-out.
*/
awaitApproval: ApprovalGate
/** Optional — cache lookup pre-dispatch (Phase 6). Returns a cached result or undefined. */
lookupCache?: (
req: ExecutionRequest,
argsHash: string
) => string | undefined
/** Optional — audit recorder (Phase 2). Called at dispatch + completion. */
recordAudit?: AuditRecorder
/** Optional — error hint mapper (Phase 7). */
explainError?: (toolName: string, error: string) => string | undefined
}
export type AuditHook =
| {
kind: 'start'
id: string
toolName: string
args: ToolArgs
argsHash: string
parentToolCallId?: string
startedAt: number
}
| {
kind: 'complete'
id: string
status: ExecutionResult['status']
completedAt: number
durationMs: number
cacheHit: boolean
resultPreview?: string
error?: string
errorHint?: string
}
export interface ExecutorOptions {
/** Fires when a call transitions to running. */
onStart?: (req: ExecutionRequest) => void
/** Fires when a call settles. */
onComplete?: (res: ExecutionResult) => void
/** Aborts remaining not-yet-started calls when flipped true. */
abortSignal?: AbortSignal
}
/**
* Run a batch of tool calls. Returns ordered results matching the input order.
*
* Scheduling:
* - A batch with a shell call (key 'exec') runs serially, in input order.
* - Calls with no sideEffectKey run in parallel.
* - Calls sharing a key run serially within their group.
* - Groups with different keys run in parallel with each other and with the
* no-key pool.
*/
export async function executeParallel(
requests: ExecutionRequest[],
runtime: ExecutorRuntime,
opts: ExecutorOptions = {}
): Promise<ExecutionResult[]> {
if (requests.length === 0) return []
// Tag each request with its side-effect key up front so tests can inspect
// the schedule and the audit recorder sees consistent keys.
const tagged = requests.map((req) => ({
req,
key: deriveSideEffectKey(req.toolName, req.args),
}))
// Index → result slot so we can preserve input order.
const results: (ExecutionResult | undefined)[] = Array(requests.length).fill(undefined)
// Group by key. `undefined` means "no shared key" — each goes to its own
// solo group so it runs concurrently with everything else.
const groups = new Map<string, number[]>()
const soloIndices: number[] = []
tagged.forEach((t, i) => {
if (!t.key) {
soloIndices.push(i)
} else {
const list = groups.get(t.key) ?? []
list.push(i)
groups.set(t.key, list)
}
})
const runOne = async (index: number): Promise<void> => {
if (opts.abortSignal?.aborted) {
results[index] = abortedResult(tagged[index])
opts.onComplete?.(results[index]!)
return
}
const res = await runSingle(tagged[index].req, tagged[index].key, runtime, opts)
results[index] = res
opts.onComplete?.(res)
}
// A shell command can read or change any file, so a batch that holds one
// runs in the order the model wrote it. Measured (C59 bench, 9B): in one
// turn `cp config.json config.json.bak` and an edit of config.json ran on
// two queues, the edit won, and the backup held the new port.
if (tagged.some((t) => t.key === 'exec')) {
for (let i = 0; i < tagged.length; i++) await runOne(i)
return results.map((r, i) => r ?? abortedResult(tagged[i]))
}
const solo = soloIndices.map(runOne)
const grouped = [...groups.values()].map(async (indices) => {
for (const i of indices) {
await runOne(i)
}
})
await Promise.all([...solo, ...grouped])
return results.map((r, i) => r ?? abortedResult(tagged[i]))
}
async function runSingle(
req: ExecutionRequest,
sideEffectKey: string | undefined,
runtime: ExecutorRuntime,
opts: ExecutorOptions
): Promise<ExecutionResult> {
const startedAt = Date.now()
// What the duration counts from. Moves to the end of the approval wait: the
// time a call sat on the user's card is not the tool's time, and a 20 ms
// file_write read "21.6s" next to its tick (Gegenprobe 01.10.2026).
let clockFrom = startedAt
const argsHash = stableArgsHash(req.args ?? {})
opts.onStart?.(req)
runtime.recordAudit?.({
kind: 'start',
id: req.id,
toolName: req.toolName,
args: req.args,
argsHash,
parentToolCallId: req.parentToolCallId,
startedAt,
})
const finalize = (partial: Omit<ExecutionResult, 'completedAt' | 'durationMs'>): ExecutionResult => {
const completedAt = Date.now()
const durationMs = completedAt - clockFrom
const result: ExecutionResult = { ...partial, completedAt, durationMs }
runtime.recordAudit?.({
kind: 'complete',
id: req.id,
status: result.status,
completedAt,
durationMs,
cacheHit: result.cacheHit,
resultPreview: result.result,
error: result.error,
errorHint: result.errorHint,
})
return result
}
const tool = runtime.getTool(req.toolName)
if (!tool) {
return finalize({
id: req.id,
toolName: req.toolName,
status: 'failed',
error: isGenericCallName(req.toolName)
? `Unknown tool: ${req.toolName}. "${req.toolName}" is not a tool name. Send the call again with the tool's own name, for example file_list or file_read, in the name field.`
: `Unknown tool: ${req.toolName}`,
dispatchedArgs: req.args,
argsHash,
sideEffectKey,
startedAt,
cacheHit: false,
schemaValidated: false,
})
}
// Schema validate (Phase 4).
let dispatchedArgs = req.args ?? {}
let schemaValidated = true
let validationError: string | undefined
if (tool.inputSchema) {
const v = validateToolArgs(req.args ?? {}, tool.inputSchema)
if (!v.valid) {
schemaValidated = false
validationError = formatValidationErrors(v.errors)
// Build a concrete retry hint from the tool's schema: list required
// fields with their types + show what the model actually sent. Small
// models self-correct MUCH better when they see the shape expected,
// not just "matching the tool schema". Example output:
// "file_write requires {path: string, content: string}. You sent
// {command}. Retry with both required fields."
const required = Array.isArray(tool.inputSchema.required) ? tool.inputSchema.required : []
const props = tool.inputSchema.properties ?? {}
const schemaStr = required.length
? required
.map((k) => {
const s = props[k]
const typ = s && typeof s === 'object' ? (s.type || 'any') : 'any'
return `${k}: ${typ}`
})
.join(', ')
: '(no required fields)'
const sentKeys = Object.keys(req.args ?? {})
const sentStr = sentKeys.length ? sentKeys.join(', ') : '(empty)'
const hint = `${req.toolName} requires {${schemaStr}}. You sent {${sentStr}}. Retry with all required fields present.`
return finalize({
id: req.id,
toolName: req.toolName,
status: 'failed',
error: `Invalid arguments: ${validationError}`,
errorHint: hint,
dispatchedArgs: req.args,
argsHash,
sideEffectKey,
startedAt,
cacheHit: false,
schemaValidated: false,
validationError,
})
}
if (v.coerced) dispatchedArgs = v.coerced
}
// Cache lookup (Phase 6 integration point).
const cached = runtime.lookupCache?.(req, argsHash)
if (typeof cached === 'string') {
return finalize({
id: req.id,
toolName: req.toolName,
status: 'cached',
result: cached,
dispatchedArgs,
argsHash,
sideEffectKey,
startedAt,
cacheHit: true,
schemaValidated,
})
}
// User approval. Unconditional: a runtime that does not want a prompt says
// so with APPROVE_ALL, it does not get there by forgetting the field.
const approved = await runtime.awaitApproval(req, tool)
clockFrom = Date.now()
if (!approved) {
return finalize({
id: req.id,
toolName: req.toolName,
status: 'rejected',
error: 'User rejected tool call',
dispatchedArgs,
argsHash,
sideEffectKey,
startedAt,
cacheHit: false,
schemaValidated,
})
}
// The run's Stop. `opts.abortSignal` is what the hook passes; `req.run` is
// what a nested loop (delegate_task's sub-agent) carries — take whichever
// exists so no surface silently runs uncancellable.
const signal = opts.abortSignal ?? req.run?.abortSignal
// Approval can sit open for minutes. The abort check at schedule time is long
// stale by the time the user finally answers, so ask again here: a call the
// user approved before pressing Stop must not still be dispatched afterwards.
if (signal?.aborted) {
return finalize({
id: req.id,
toolName: req.toolName,
status: 'rejected',
error: 'Aborted before dispatch',
dispatchedArgs,
argsHash,
sideEffectKey,
startedAt,
cacheHit: false,
schemaValidated,
})
}
// Dispatch.
try {
const result = await raceAbort(
runtime.execute(req.toolName, dispatchedArgs, req.run && runForCall(req.run, req.id), signal),
signal,
)
// C60 S3: output from outside LU marks the run, before anything reads it.
markRunTaint(req.run, req.toolName)
if (result === ABORTED) {
// The tool got the signal and is expected to wind itself down; what this
// guarantees is that the RUN stops waiting. Without it, Stop was still a
// lie for the user even when the tool cooperated: the loop sat on the
// pending promise for the rest of the tool's own timeout, the typing dots
// stayed on, and nothing downstream (VRAM restore, staged-change review)
// could proceed.
return finalize({
id: req.id,
toolName: req.toolName,
status: 'rejected',
error: 'Aborted while running',
dispatchedArgs,
argsHash,
sideEffectKey,
startedAt,
cacheHit: false,
schemaValidated,
})
}
return finalize({
id: req.id,
toolName: req.toolName,
status: 'completed',
result,
dispatchedArgs,
argsHash,
sideEffectKey,
startedAt,
cacheHit: false,
schemaValidated,
})
} catch (err) {
// An error text can carry foreign content too (a page's body in a fetch error).
markRunTaint(req.run, req.toolName)
const errorText = err instanceof Error ? err.message : String(err)
const hint = runtime.explainError?.(req.toolName, errorText)
return finalize({
id: req.id,
toolName: req.toolName,
status: 'failed',
error: errorText,
errorHint: hint,
dispatchedArgs,
argsHash,
sideEffectKey,
startedAt,
cacheHit: false,
schemaValidated,
})
}
}
/** Sentinel for "the run was stopped while this tool was still in flight". */
const ABORTED = Symbol('aborted')
/**
* Resolve as soon as EITHER the tool finishes or the run is stopped.
*
* The abandoned tool promise is swallowed, not left dangling: a rejection with
* no handler takes the whole webview down in Tauri, and the tool result of a
* stopped run is worthless anyway.
*/
function raceAbort<T>(p: Promise<T>, signal?: AbortSignal): Promise<T | typeof ABORTED> {
if (!signal) return p
if (signal.aborted) {
p.catch(() => {})
return Promise.resolve(ABORTED)
}
return new Promise<T | typeof ABORTED>((resolve, reject) => {
const onAbort = () => resolve(ABORTED)
signal.addEventListener('abort', onAbort, { once: true })
p.then(
(v) => {
signal.removeEventListener('abort', onAbort)
resolve(v)
},
(e) => {
signal.removeEventListener('abort', onAbort)
reject(e)
},
)
})
}
function abortedResult(tagged: { req: ExecutionRequest; key?: string }): ExecutionResult {
const now = Date.now()
const argsHash = stableArgsHash(tagged.req.args ?? {})
return {
id: tagged.req.id,
toolName: tagged.req.toolName,
status: 'rejected',
error: 'Aborted before dispatch',
dispatchedArgs: tagged.req.args,
argsHash,
sideEffectKey: tagged.key,
startedAt: now,
completedAt: now,
durationMs: 0,
cacheHit: false,
schemaValidated: false,
}
}
/**
* What the loop guard needs to know about one result: did it fail. A tool that
* reports its failure as text (`Error (1): …`, `Web search failed: …`) comes
* back `completed`, and the guard fed `status === 'failed'` never saw it: a
* command failing over and over read as progress and even cleared the failure
* streaks (bug hunt 01.10.2026), so the run went on to the 200-round budget.
*/
export function resultFailed(r: Pick<ExecutionResult, 'status' | 'result'>): boolean {
if (r.status === 'failed') return true
return (r.status === 'completed' || r.status === 'cached') && toolResultIsFailure(r.result)
}
/** Convenience: attach ExecutionResult fields back onto an AgentToolCall. */
export function applyResultToToolCall(call: AgentToolCall, result: ExecutionResult): AgentToolCall {
call.status =
result.status === 'completed'
? 'completed'
: result.status === 'cached'
? 'cached'
: result.status === 'rejected'
? 'rejected'
: 'failed'
if (result.result !== undefined) call.result = result.result
// Ein Werkzeug, das seinen Fehler als Text zurueckgibt, wirft nicht — und
// galt damit als erledigt. Ein gruener Haken ueber „Web search failed" ist
// die eine Auskunft, die der Kunde nicht nachpruefen kann (Testlauf
// 03.09.2026: drei Haken, dreimal nichts gefunden, und eine erfundene
// Tabelle als Ergebnis). Siehe `lib/tool-result-failure.ts`, warum das nur
// am Anfang der Antwort greift.
if (call.status === 'completed' && toolResultIsFailure(result.result)) {
call.status = 'failed'
if (call.error === undefined) call.error = String(result.result).split('\n')[0].slice(0, 300)
}
if (result.error !== undefined) call.error = result.error
if (result.errorHint !== undefined) call.errorHint = result.errorHint
call.duration = result.durationMs
call.startedAt = result.startedAt
call.completedAt = result.completedAt
call.cacheHit = result.cacheHit
call.schemaValidated = result.schemaValidated
call.sideEffectKey = result.sideEffectKey
return call
}