feat(providers): provider observation surface — identity, placement, resource use, account usage, and interactive terminal attach

[drewstone]

Problem

agent-interface, the CLI Bridge provider, and the Tangle provider do not expose one normalized execution observation.

Braid can observe per-turn model usage, but it cannot consistently identify the provider location, effective resources, account usage, or subscription limits.

The CLI Bridge usage capability means response usage only.

It does not expose plan, quota, or remaining subscription usage.

The Tangle provider narrows the sandbox SDK and drops safe identity, placement, resource, and billing methods.

Required contract

Add optional typed observation surfaces for:

• provider environment and provider session identity;
• lifecycle, cleanup, continuity, and persistence;
• configured endpoint location without credentials;
• requested and verified placement;
• requested and effective CPU, RAM, disk, and accelerator resources;
• current and peak resource use;
• per-execution model usage and cost provenance;
• per-environment compute billing when available;
• account usage, credits, plan, quota, and period;
• known, stale, unavailable, redacted, and unknown states.

Providers must never expose API keys, bearer tokens, SSH credentials, secret values, credential-bearing URLs, or internal listener addresses.

Acceptance

• A fake CLI Bridge reports response usage and marks subscription quota unavailable.
• A capable bridge reports plan, quota, remaining amount, period, and freshness.
• A Tangle sandbox reports safe provider identity, resolved placement, requested resources, current CPU and RAM use, and account usage.
• Missing values remain absent or explicitly unavailable.
• No missing numeric field becomes measured zero.
• Live and replayed observations preserve the same identifiers and provenance.
• Provider contract tests reject credential-bearing observation payloads.

Evidence

Braid audited agent-interface@0.46.1, CLI Bridge provider 0.4.3, and Tangle provider 0.6.1.

Braid currently needs a narrow local adapter to retain data already available in @tangle-network/sandbox@0.19.4.

[drewstone]

Consolidating #138 (attachable interactive terminal sessions) into this issue. Both have one root cause: the neutral agent-interface environment contract exposes only coarse capability bits (placement/usage/confidential booleans), so the Tangle provider drops sandbox-SDK methods that have no contract slot — this issue's identity/placement/resource/billing methods, and #138's terminal/PTY surface. They share the same security invariants (no credentials in durable state, explicit unavailable/redacted/stale states so "missing ≠ measured zero", live==replay identity parity).

Current state on main (0.47.0 / provider 0.7.0): ~1 of ~10 surfaces exists. AgentEnvironment.placement() + PlacementInfo (environment-runtime.ts:259) and per-turn TokenUsage.reasoningTokens+cost (execution-types.ts:13-20) are present; the 0.7.0 provider re-exposed the placement bit. Missing entirely: endpoint, accelerator, quota, credits, subscription, peak, effective-vs-requested resources, per-env compute billing, and any terminal identity/input/resize/attach-lifecycle. Not superseded by the retained-control work; GET /capabilities reports run-control facts, not resource/billing metrics.

Shape: one contract design (observation + terminal, same file, same fail-closed freshness discriminator), then two provider fast-follows mirroring #146→#154 — a usage/placement/resource readout, and a terminal bridge to the already-live sandbox transport (webTerminalEnabled + sidecar pty-manager + terminal-ws on agent-dev-container). #138's transport is NOT server-blocked — only the interface contract and the provider bridge are owed.

[drewstone]

Contract phase 1 shipped in #158 (squash-merged to main): the optional observation surface (with the required known/stale/unavailable/redacted/unknown freshness discriminator so a missing value is never a measured zero, and a credential-free SafeEndpointSchema) and the optional interactive-terminal capability + typed refs are now in @tangle-network/agent-interface. Additive, no breaking change; adversarially reviewed; artifact + control gates green.

Remaining (phase 2, provider wiring): a CLI-bridge readout for plan/quota/period/freshness usage, and a Tangle provider bridge that maps the terminal refs to the already-live sandbox transport (webTerminalEnabled + sidecar pty-manager + terminal-ws) and the observation payloads to the sandbox SDK's identity/placement/resource/billing methods. Same phasing as #146 → #154. Keeping this issue open for that.