feat: add plan-based, budget-bounded transaction execution

[eddiearc]

Problem

aisa run executes an arbitrary single API call and --show-cost reports billing headers only after it completes. That is correct for direct, low-friction API use, but it cannot bound the cost of an Agent task: an Agent can dynamically change provider, call order, pagination, fan-out and retry behavior as its prompt, context or tool results change. A prompt such as "keep cost low" is advisory, not an enforceable execution contract.

Goal

Add a first-class plan-based transaction path to the CLI. An Agent may propose a plan, but the CLI executes only an approved, finite Transaction Manifest with a quoted cost ceiling. This is an execution artifact for a resource task, not a generic workflow/DAG-builder product.

Agent goal → candidate plan → validate/quote → user approval
→ server reserve + execution lease → CLI run → settle + receipt

P0 CLI surface

• aisa plan validate <manifest>: parse a versioned declarative manifest and reject undeclared capabilities, unbounded loops/pagination/fan-out, invalid dependencies, missing idempotency policy, or missing finite caps.
• aisa plan quote <manifest>: submit the complete manifest for a server quote; show expected cost and worst-case ceiling, resolved providers/prices, policy warnings and expiry.
• aisa plan run <manifest> --quote <id>: execute only the frozen, approved manifest; persist a task journal so interrupted runs resume without duplicating completed operations.
• aisa receipt <task-id>: render/export node-level provider, attempt/retry, status, actual cost, total cost and request/operation IDs.
• Preserve aisa run for simple direct calls. Multi-step, high-cost or fan-out work opts into plan; do not force every low-cost read through a human-visible plan.

Manifest constraints

Each node needs a resolved capability/provider version, declared data dependencies, finite max_calls, max_concurrency, timeout, output/page bounds, bounded retry policy, fallback allow-list, side-effect classification and stable operation_id. The manifest is restricted declarative data, not arbitrary shell/JS. Runtime data may choose among declared bounded branches; any new capability, entity expansion, higher-cost provider or enlarged bound requires replan → requote → approval.

Control-plane dependency (required; not client-only)

CLI must not become the authority for money or permission. AIsaServices needs corresponding endpoints/contract to:

1. validate policy and return expected + worst-case quote;
2. atomically reserve the ceiling before execution;
3. issue a short-lived execution lease carrying max_spend, call/concurrency ceilings and expiry;
4. settle actual provider costs and release unused reservation;
5. enforce operation_id idempotency and reject undeclared/expired/over-budget calls.

CLI handles plan UX, local scheduling, cancellation, cache and journal; service-side policy/ledger remains non-bypassable for CLI, SDK, MCP and direct API paths.

Acceptance criteria

• A malformed or unbounded manifest fails before any provider call.
• Quote displays expected cost, hard ceiling, pricing version and expiry.
• No execution begins if reservation cannot be obtained.
• A task cannot exceed the approved ceiling, max-call or concurrency limits, including retries/fan-out.
• Restart/retry with the same operation ID does not double-charge or repeat an external side effect.
• Receipt reconciles every executed node to an actual cost/status; unknown cost is explicit.
• Existing aisa run behavior remains compatible.

Non-goals

• A visual/no-code workflow builder.
• Arbitrary user scripts with unanalysable network effects.
• A CLI-local balance check as the authoritative guard.
• Auto-recharge as a runaway-cost remedy.

[eddiearc]

Docs stop-loss review: SimilarWeb pricing disclosure

Related docs PR: AIsa-team/docs#93

This PR is a documentation-only mitigation, not a replacement for the server-authoritative quote/reservation path proposed in this issue. A Sol/high review found that it should not merge unchanged:

1. P1 - endpoint-specific controls: Audience Overlap and Website Top Geographies have no limit parameter, but their new price text tells agents to minimize limit. These endpoints need explicit unavoidable-max exposure/confirmation guidance instead.
2. P2 - one pricing source: the human tables are duplicated manually from x-aisa-pricing; the checker only looks for keywords, so rate/formula/cap or EN/ZH drift can pass. Generate the guides from a canonical manifest or compare every row structurally.
3. P2 - exact inventory: the checker accepts any 20 operations even though this document has 23, so priced endpoints can disappear without failing validation.
4. P2 - PR gate: the validation runs only after pushes to main touching openapi/**; it does not protect guide/navigation/checker-only pull requests.

Suggested relation to #18: keep this documentation work as short-term disclosure, but make the eventual server Cost/Quote contract the pricing authority. Agents should use docs for formulas and scope controls, then consume the server quote for an executable ceiling.