xwork: agent orchestration
xllm handles "talking to the model" and xllm-session handles "remembering what was said" — xwork sits on top and handles "turning the model into an agent that gets work done": tool registration and execution, workspace policy, multi-turn orchestration, notifications and compaction scheduling.
Overview
49.1 The three-layer boundary
| Layer | Owns | Does not own |
|---|---|---|
| xllm (ch. 34) | request building, three dialects, SSE, proxies | tool execution, history |
| xllm-session (ch. 35) | context budget, compaction, journal | orchestration, tools |
| xwork | agent orchestration, tool registration/execution, workspace policy, artifacts, subagents, notifications, compaction scheduling | provider protocols, CLI |
49.2 The agent lifecycle
xwork_agent_config cfg;
xworkAgentConfigInit(&cfg); /* workspace root, mode, budget */
xwork_agent* agent = xworkAgentCreate(&cfg);
xworkAgentRegisterBuiltinTools(agent); /* built-in read/write/list etc. */
xworkAgentRegisterTool(agent, &myTool); /* custom tool */
xwork_agent_run run = xworkAgentRunBegin(agent, "analyze this directory for me");
while ( xworkAgentRun(agent, &run) ) {
xwork_task_notice notices[8];
uint32 n = xworkAgentTakeTaskNotices(agent, notices, 8);
for ( uint32 i = 0; i < n; i++ ) { /* tool call / result notices */ }
}
xworkAgentRunEnd(agent, &run);
xworkAgentDestroy(agent);The 42 public symbols group by lifecycle stage: config/create/destroy 5, run control 6 (incl. cancel/resume), tool registration 10, subagent types 5, notifications & queries 8, compaction 3, others 5. Everything is exported to scripts and to nested TCC.
49.3 Workspace policy & subagents
xwork's workspace is the agent's sandbox boundary: read/write exploration (in-process or delegated to external rg/fd), read markers with directory fallback, and budget wiring. The subagent type system (xworkAgentRegisterSubagentType) lets one agent spawn read-only children (RunReadOnlySubagent) or fully privileged ones, forming a multi-agent collaboration topology.
Compaction scheduling (xworkAgentCompact / MaybeCompact) works with xllm-session's compaction operators so long conversations converge automatically, while read markers keep tool artifacts from being lost.
49.4 In practice: agent-demo
The repo's release/agent-demo/ is the full-stack xwork showcase: xs single-file mode + the NativeHarness browser front end + a C-script turn engine (an HTTP polling wire protocol), accepted end-to-end in the browser — including the approval gate (tool calls need human sign-off), diff/plan panels and the execution-trace column. It is the complete worked example of the four-library stack: xwork + xllm + xllm-session + the site VFS.
class: "app" service node add a desktop shape to this stack: local HTTP + a WebView2 window, which combined with single-file deployment yields a double-click desktop agent application.Common mistakes
Exercises
Summary
xwork = the agent orchestration layer (42 symbols, the 15th extension) · three layers = xllm (calls) / session (memory) / work (orchestration) · tool registration + subagents + notifications = the complete agent shape · agent-demo = the four-library stack in practice