feat(provider): live usage events, available-commands subscription, and slash-command helpers

[DaniAkash]

Draft — depends on openclaw/acpx#345

The runtime fields this PR consumes (cost, breakdown, availableCommands on status events; usage/availableCommands on AcpRuntimeStatus; the four new exported types) land in acpx@0.11.0 via the upstream PR. This downstream PR is wired against that release line — peerDependencies.acpx is bumped to >=0.11.0 and the dev dep is intentionally omitted from package.json until the upstream release lands.

Local install path while the upstream is in review: clone openclaw/acpx#345 somewhere, run pnpm install && pnpm build there, then ln -s <path-to-upstream-worktree> node_modules/acpx in both the workspace root and packages/acpx-ai-provider/. CI will fail at install until acpx@0.11.0 is published — that's expected and the PR is marked draft accordingly.

Summary

Surfaces the new runtime channels to AI SDK consumers and adds the helpers Herbie (or any downstream chat UI) needs to render a live context-window bar and trigger agent-initiated compaction.

const provider = createAcpxProvider({ agent: 'claude' })

provider.events.on('usage', (snapshot) => {
  // { used, size, cost?, breakdown?, at, sessionKey }
  ui.renderContextBar(snapshot.used, snapshot.size)
})

provider.events.on('availableCommands', ({ commands }) => {
  ui.renderCommandPalette(commands) // [{ name, description?, hasInput }]
})

// Trigger /compact when the agent advertises it
if (provider.getAvailableCommands().some((c) => c.name.includes('compact'))) {
  await provider.compact()
}

What changed

AcpxProvider public surface

Addition	Purpose
provider.events: EventEmitter<AcpxProviderEvents>	Push subscription. 'usage' fires on every usage_update; 'availableCommands' fires on every available_commands_update.
provider.getUsage(sessionKey?)	Sync read of the latest AcpxUsageSnapshot for a session.
provider.getAvailableCommands(sessionKey?)	Sync read of the latest advertised slash-command list.
provider.runSlashCommand({ name, sessionKey?, agent?, timeoutMs?, signal? })	One-shot prompt whose text is a slash command. Drains the iterator so any follow-on events propagate.
provider.compact({ sessionKey?, agent? })	Resolves the /compact-style command from availableCommands and calls runSlashCommand. Throws when no compact-like command is advertised.
New types: AcpxUsageSnapshot, AcpxProviderEvents	Plus re-exports of the four new acpx/runtime types (AcpRuntimeAvailableCommand, AcpRuntimeUsageBreakdown, AcpRuntimeUsageCost, AcpRuntimeSessionUsage).

EventTranslator (in convert-events.ts)

• New onUsageUpdate(event) and onAvailableCommands(commands) callback hooks on the constructor. The language model wires them into provider.recordUsage / provider.recordAvailableCommands on each turn, which in turn updates the per-session maps and emits on provider.events.
• handleStatus now translates available_commands_update into a callback fire (previously it was a no-op).
• lastUsageEvent stores the full usage_update event so finish() can place the context-window ceiling and cost onto providerMetadata.acpx instead of mangling them through LanguageModelV2Usage.

accumulatedUsage() mapping fix

The provider previously transported size (context-window ceiling) through cachedInputTokens. That was a hack — cachedInputTokens is supposed to be the prompt-cache hit count. The new mapping:

Source	AI SDK V2 field
_meta.usage.inputTokens	inputTokens
_meta.usage.outputTokens	outputTokens
_meta.usage.totalTokens (or used fallback)	totalTokens
_meta.usage.cachedReadTokens	cachedInputTokens
_meta.usage.thoughtTokens	reasoningTokens
usage_update.size	providerMetadata.acpx.contextWindow
usage_update.cost	providerMetadata.acpx.cost

Behavior change for any consumer reading usage.cachedInputTokens to mean "context window size" — switch to providerMetadata.acpx.contextWindow. Documented in the new README section and the migration callout.

Other

• packages/acpx-ai-provider/package.json — version 0.0.6 → 0.1.0; peerDep acpx >=0.11.0; dev dep on acpx removed pending upstream release.
• biome.json — adds convert-events.ts to the noExcessiveLinesPerFile: off override list (existing pattern for orchestrator files).
• README — new "Live usage + slash commands" section with code examples and the migration callout; "Known limitations" updated to remove the "no streaming usage updates" caveat.

Test plan

• bun run typecheck clean across all three packages.
• bun run lint clean (one pre-existing warning unrelated to this PR).
• bun test packages/acpx-ai-provider/test/{unit,integration,contract} — 197 pass / 0 fail across 17 files.
• New test/unit/usage-events.test.ts covers: usage event emission with cost + breakdown, getUsage() sync read, availableCommands event emission, runSlashCommand happy path + failed-turn error, compact() throws when no compact command is advertised, compact() sends the advertised name as a slash command.
• test/integration/{do-stream,do-generate,with-stream-text,with-generate-text}.test.ts updated to assert the new providerMetadata.acpx.contextWindow shape instead of the old cachedInputTokens === size hack.
• CI green — expected to fail at install until acpx@0.11.0 ships from feat(runtime): surface cost, usage breakdown, and available commands on status events and getStatus openclaw/acpx#345.

Coordination with upstream

• Land sequence: feat(runtime): surface cost, usage breakdown, and available commands on status events and getStatus openclaw/acpx#345 → upstream releases acpx@0.11.0 → re-pin devDependencies.acpx = "^0.11.0" in this PR → un-draft and ship.
• If the upstream contract evolves in review (e.g. field name changes), the changes here are localized to convert-events.ts, provider.ts, and the type re-exports in types.ts / index.ts.

Out of scope (deliberate)

• Auto-compact at threshold. Pure UI logic on top of provider.events.on('usage', ...). Belongs in the consumer (Herbie or other), not here.
• MCP-style command discovery beyond name + description + hasInput. Matches the upstream PR's choice not to plumb AvailableCommandInput through.
• Per-agent command-name detection beyond compact / condense. compact() matches those two names; consumers wanting different commands can use runSlashCommand with the explicit name from getAvailableCommands().