Agent Runtime Tools
This page documents the committed source. Treat revision-sensitive RuneLite UI, packet, or in-game outcomes as pending live-client verification unless the page records direct evidence.
A source read or passing test fails to substitute for observing a revision-sensitive flow in RuneLite. Use live-client observations.
Current Offline Tools
| Tool | Use | Notes |
|---|---|---|
| CodeGraph | Find source symbols, callers, and file structure before editing | Treat index output as navigation, then verify changed files after edits |
rg | Search docs and source text | Use targeted patterns; skip broad scans after finding the symbol |
| Gradle focused suites | Compile and test narrow areas | Start focused, then broaden when shared code changes |
git diff | Review exact edits before final notes | Check docs and prompt changes for stale paths |
docs-site/sidebars.js | Confirm published navigation | Canonical pages belong in the sidebar or need an intentional inbound link |
Current Runtime Inspection Surfaces
| Surface | Package | Use |
|---|---|---|
SuiteRuntimeStatus | Api.debug | Snapshot revision, bootstrap, pacer, walker, and health status |
WalkerTelemetry | sdk.walker | Read bounded decision history and the terminal status, structured failure, request, lifecycle, position, target, and decision retained after active-path cleanup |
WidgetExplorer | Api.debug | Inspect widgets by visibility, text, and action |
PacketTrace | Api.debug | Capture bounded packet events with packet identity, arguments, result, and semantic actionType |
NativeActionTrace | PacketUtils.logging | Capture exact native, RuneLite menu, and opt-in client telemetry actions in one bounded buffer; normal dispatched actions can forward to the optional clipboard sink, while telemetry bypasses it |
IssuedActionClipboard | PacketUtils.logging | Best-effort, disabled-by-default copy of dispatched SDK/menu actions; walker NPC rows include definition ID and live scene index |
RevisionHealthCheck | Api.debug | Probe revision-sensitive packet reflection surfaces |
| Plugin overlays and panels | plugin packages and com.n3plugins.ui | Read live plugin status and user-facing state |
| RuneLite logs | local RuneLite runtime | Correlate plugin errors with live client state |
| API Tester | com.n3plugins.apitester | Run curated, user-visible SDK/API probes inside RuneLite |
| Agent Server | com.n3plugins.agentserver | Expose allowlisted runtime reads, one-call debug context, bounded scene queries, and observed action results to a local client |
The menu-action cache provides a runtime compatibility artifact rather than a diagnostic log. It lives at ~/.runelite/cache/menu-action-plan.json. Deleting it forces resolution on the next native menu action. See menu-action-dispatch.md.
Use these as evidence helpers. They do not replace source review or live observation.
Agent Server lastInteractions returns the bounded packet stream in interactions and the bounded client/menu stream in nativeActions. Packet records include packetName, packetType, and actionType. Native records include source, action, and the captured arguments. This allows live audits to distinguish a synthetic MOUSE_CLICK from its following CC_OP, item, player, NPC, object, or other supported action.
Clipboard output offers a local debugging convenience, not an Agent Server postcondition. Enable it through Packet Utils copyIssuedActionsToClipboard. Agent Server interaction history remains the authoritative bounded machine-readable capture.
n3_get_debug_context returns player, modal, inventory, nearby entity,
navigation, latest native action, and latest buffered error state in one atomic
client-thread snapshot. CONFIRMED action responses have an observed declared
postcondition. An inline native trace on DISPATCHED proves transport only.
Offline Agent Loop Available Now
- Read
AGENTS.md, SOT, and relevant docs. - Map the requested workflow to existing SDK/actions.
- Inspect live source with CodeGraph or
rg. - Patch only scoped files.
- Run focused compile/tests.
- Inspect
git diff. - Update docs, SOT, and sidebar/cross-links when public behavior changes.
Runtime Evidence Guardrails
- Local-only by default. Limit network listeners to localhost.
- Omit account credentials, session tokens, or personal paths in artifacts.
- Omit hidden screenshots or logs. State output paths before writing.
- Prefer read-only probes. Skip diagnostic endpoints for risky, destructive, costly, or account-specific gameplay actions.
- Skip committing generated artifacts unless the user requests them.
- Record client revision, setup, action or probe, expected result, observed result, and an evidence reference for every required live scenario.
Runtime Tool Review Checklist
- Does the tool read or write files? State paths before running it.
- Does it rely on the live client? Record client revision and account state.
- Does it expose screenshots or logs? Redact sensitive content.
- Does it only inspect state? Keep diagnostics separate from action dispatch.
- Does it prove live behavior? If not, mark live verification pending.