# agentteam-maas Integration Boundary

> Canonical path: `specs/maas/agentteam-maas-integration.md`
> Status: living-spec
> Scope: AgentTeam-owned control-plane and daemon integration responsibilities for
> hosted MaaS.
> Related specs: [`specs/billing/hosted-credits-payment.md`](../billing/hosted-credits-payment.md);
> [`specs/billing/hosted-model-onboarding.md`](../billing/hosted-model-onboarding.md);
> `agentteam-maas/specs/maas/messages-feature-support.md`

`agentteam-maas` is the dedicated service for hosted MaaS runtime execution. AgentTeam
must keep only the control-plane responsibilities that are native to AgentTeam's
agent runtime authority model.

## AgentTeam Responsibilities

AgentTeam owns:

- runtime authority source of truth, including `agentAuthToken`, agent runtime
  session identity, machine binding, workspace attribution, and authority
  invalidation;
- runtime MaaS capability issue and refresh through
  `POST /api/v1/workspaces/:workspaceId/agents/:agentId/runtime/llm-proxy-session`
  and
  `POST /api/v1/workspaces/:workspaceId/agents/:agentId/runtime/llm-proxy-session/refresh`
  when the daemon
  requests `credentialKind=maas_capability`;
- authority projection push to `agentteam-maas`
  `/internal/maas/v1/authority-projections/{projection_id}` before issuing a
  direct MaaS runtime capability;
- daemon config projection for daemons that advertise `agent:maas-direct`,
  including the `agentteam-maas` runtime base URL and `credentialKind`;
- desktop daemon loopback proxy behavior that keeps the MaaS capability in the
  daemon process and exposes only a local loopback credential to the runtime;
- consuming hosted model feature metadata from `agentteam-maas` model discovery and
  billing/pricing projections when runtime or browser model selection depends
  on `/messages` feature support;
- preserving hosted `/messages` request bodies through the desktop loopback
  bridge. AgentTeam may inject the MaaS capability at the upstream boundary, but it
  must not strip or rewrite feature fields such as `output_config` or
  `context_management` to work around `agentteam-maas` admission;
- browser-facing hosted credit billing APIs, organization billing
  authorization, and Alipay callbacks, as specified by
  [`specs/billing/hosted-credits-payment.md`](../billing/hosted-credits-payment.md);
- system-admin hosted credit grant authorization and forwarding. AgentTeam verifies
  the platform operator, supplies the operator user reference, and forwards the
  idempotent grant request to `agentteam-maas`; AgentTeam does not write hosted credit
  grants, batches, ledger facts, or duplicate balance state;
- hosted availability resolution, explicit hosted entitlement fact
  consumption, optional eligibility sync requests when a AgentTeam policy is
  configured, workspace authorization, and selectable model composition for
  organization-admin onboarding, as specified by
  [`specs/billing/hosted-model-onboarding.md`](../billing/hosted-model-onboarding.md).

## agentteam-maas Responsibilities

AgentTeam must not be the canonical owner or active writer for:

- hosted runtime data-plane routes such as `/maas/v1/models`,
  `/maas/v1/messages`, or hosted request-status lookup;
- hosted model catalog, pricing, upstream routes, platform credential metadata,
  organization hosted entitlements, preflight records, usage events,
  reservations, credit grants, ledger transactions, payment order/event
  storage, or reconciliation state;
- hosted provider credential plaintext materialization;
- hosted request normalization, deterministic metering, resolver decisions,
  route-scoped `/messages` feature admission, settlement, or recovery-status
  classification.

Those contracts belong in `agentteam-maas` specs and implementation. AgentTeam may keep
compatibility integration code only when it forwards to `agentteam-maas` without
becoming the writer or service-internal source of truth.

## Runtime Credential Boundary

Runtimes authenticate to AgentTeam with existing runtime authority. AgentTeam may issue a
short-lived MaaS capability for `agentteam-maas`, but runtimes must not send
`agentAuthToken` to `agentteam-maas`, and AgentTeam must not forward `agentAuthToken` to
`agentteam-maas`.

Direct MaaS daemons receive:

- `baseURL`: the configured `agentteam-maas` runtime base URL;
- `credentialKind`: `maas_capability`;
- no long-lived public AgentTeam proxy key for hosted MaaS execution.

The desktop daemon is responsible for translating that server projection into a
local loopback endpoint, obtaining the MaaS capability from AgentTeam, and injecting
the capability only on the upstream request to `agentteam-maas`.