Home/Book/xwork
42 functions · Agent orchestration · MIT

xwork Function Reference

The agent/tool-loop boundary (v2.3.1, 15th extension): build.bat xwork compiles it in (auto-pulls xllm + xllm-session). xwork owns orchestration, workspace policy, tool execution, artifacts and compaction scheduling; it does not own provider protocols or conversation history.

Agent lifecycle (5 functions)

xworkAgentConfigInit / Create / Destroy lifecycle

Zero the config (workspace root, explore mode, budget) → create an opaque agent handle → destroy releases everything. The explore mode picks internal implementations (zero external deps) or delegates to rg/fd.

void xworkAgentConfigInit(xwork_agent_config* pConfig); xwork_agent* xworkAgentCreate(const xwork_agent_config* pConfig); void xworkAgentDestroy(xwork_agent* pAgent);

xworkAgentWorkspaceRoot query

Returns the agent's workspace root path (borrowed pointer) — the read/write sandbox boundary.

Run control (6 functions)

xworkAgentRunBegin / Run / RunEnd turn

Three-phase turns: Begin starts a task, Run drives until it returns false (turn complete), RunEnd frees turn state. Run internally calls xllm, parses tool invocations, executes tools and feeds results back.

xwork_agent_run xworkAgentRunBegin(xwork_agent* p, const char* sPrompt); bool xworkAgentRun(xwork_agent* p, xwork_agent_run* pRun); void xworkAgentRunEnd(xwork_agent* p, xwork_agent_run* pRun);

xworkAgentCancel / Resume control

Cancel an in-flight turn (tool execution interrupted, state saved); resume a cancelled turn.

Tool registration (10 functions)

xworkAgentRegisterBuiltinTools / RegisterBuiltinReadOnlyTools built-ins

One-call registration of the built-in tool set (file read/write, directory listing, glob); the ReadOnly variant includes the read-only subset only (subagent / exploration scenarios).

xworkAgentRegisterTool / UnregisterTool / UnregisterToolsBySource custom

Register a custom tool (name, description, parameter schema, callback); unregister by handle or in bulk by source. The registry has a generation number (ToolRegistryGeneration) — hot-updating the tool set never interrupts an in-flight turn.

bool xworkAgentRegisterTool(xwork_agent* p, const xwork_tool_def* pTool); bool xworkAgentUnregisterTool(xwork_agent* p, const char* sName);

xworkAgentToolAt / ToolCount / ToolRegistryGeneration query

Enumerate registered tools (for approval UIs); the generation number detects hot updates.

Subagent types (5 functions)

xworkAgentRegisterSubagentType / UnregisterSubagentType / SubagentTypeCount type system

Register / unregister / enumerate subagent types — each type binds its own tool set and permission tier. Combine with RunReadOnlySubagent to form multi-agent topologies.

xworkAgentRunReadOnlySubagent spawn

Spawn a read-only subagent of the given type and run a single turn (exploration / retrieval).

Notices & queries (8 functions)

xworkAgentTakeTaskNotices notices

Drain accumulated task notices (tool call start/end, artifact creation, state changes) — the data source for approval UIs and front-end trails; up to N per batch.

uint32 xworkAgentTakeTaskNotices(xwork_agent* p, xwork_task_notice* pNotices, uint32 iCapacity);

Compaction (3 functions)

xworkAgentCompact / MaybeCompact / CommitCompaction context

Manual or automatic (MaybeCompact on budget thresholds) context compaction, integrated with xllm-session operators; Commit confirms the result (read markers preserve tool artifacts).

xworkAgentDefaultCompactionOps config

Get the default compaction configuration (75%/95% two-tier thresholds).

Production proof at release/agent-demo/ (xwork + xllm + xllm-session + site VFS). Full source at lib/xwork.