# AGS Embedding Boundary

> Canonical path: `specs/ags/embedding-boundary.md`
> Status: living architecture spec
> Scope: ownership boundaries between the vendored Agent Git Service (AGS) and
> the MeshX product control plane.

## 1. Purpose

AgentTeam embeds AGS to provide repositories and GitHub-compatible repository APIs.
AGS is a repository execution plane, not the owner of AgentTeam workspace, member,
agent, asset, or automation product policy.

This boundary keeps the vendored AGS tree close to its canonical upstream and
prevents product-specific lifecycle code from accumulating inside the subtree.

## 2. AGS responsibilities

AGS owns repository primitives:

- repository and Git object storage;
- Git Smart HTTP;
- GitHub-compatible repository, pull request, issue, wiki, search, webhook, and
  collaborator APIs;
- embedded identity materialization;
- repository permission evaluation and direct collaborator primitives;
- repository archive creation;
- AGS schema and deployment lifecycle primitives.

An AGS embedding extension is allowed only when all of these are true:

1. it is required to operate or authorize an AGS repository;
2. the canonical HTTP or GraphQL API cannot preserve the required contract;
3. the extension contains no workspace, member, agent, asset, or automation
   policy;
4. the extension has focused behavior tests and a clear path to deletion when
   canonical AGS provides the primitive.

## 3. MeshX responsibilities

MeshX owns product policy and lifecycle:

- mapping workspace, member, user, and agent authority to repository access;
- repository access intents, reconciliation state, and audit projection;
- Repository Access Token issuance, hashing, metadata, scope, capabilities,
  revocation, suppression, expiration, and audit events;
- Memory, Skill, KB, Role, and automation lifecycle;
- automation triggering and resource activity projection from repository
  events;
- internal callback authentication, queueing, retry, and failure policy.

MeshX may call canonical AGS APIs or a narrow repository primitive after it has
made the product authorization decision. AGS must not import or duplicate MeshX
product models.

## 4. Authentication and authorization flow

Management-plane requests use AgentTeam identity and are authorized by MeshX.
Repository data-plane requests use either:

- a trusted in-process MeshX identity for server-owned materialization; or
- a MeshX-issued Repository Access Token whose repository scope and capability
  are verified before AGS receives a trusted request identity.

Repository Access Tokens never become generic AGS personal tokens. A verified
token authorizes only the repository and operation encoded by the current
request. Invalid, expired, revoked, out-of-scope, or under-capability tokens
fail closed.

MeshX-owned repository work uses one stable AGS workload identity:

- provider: `agentteam`;
- subject and login: `meshx-internal`.

This shared identity covers server-owned repository operations for Memory, KB,
Role, Skill, Automation, source mirrors, repository status, and resource
activity. Product actors remain separate attribution data. In particular,
`agentteam-automation-eventer` may own or create repository-triggered automation run
records, but it is not an AGS login and must not replace the shared workload
identity in the AGS authenticator.

A separate AGS workload identity is justified only when the caller needs an
independent authorization scope, credential lifecycle, operational owner, or
failure-isolation boundary. A product resource type or actor label alone is not
a reason to create another AGS account.

Embedded identity resolution must continue to fail closed when a new provider
and subject tuple collides with an existing human login. MeshX must not resolve
such collisions by silently rebinding the login or by rewriting a product
actor into a different AGS identity.

Direct collaborator materialization remains an AGS repository primitive.
MeshX owns the durable intent and decides when to grant, update, or revoke it.

## 5. Repository events

AGS owns production of repository events. MeshX owns their product effects.

A narrow embedding event adapter may forward the canonical event name, action,
repository identity, and payload. It must not decide which automation to run,
which activity row to write, or how to retry product work. Those decisions and
queues remain in MeshX.

## 6. Vendored upstream discipline

The authoritative AGS source is:

`https://github.com/pingcap/agent-git-service`

Every vendored update must:

- pin an immutable upstream commit;
- record the upstream source and commit in repository-owned provenance;
- replace the canonical subtree before applying the narrow AgentTeam embedding
  overlay;
- classify every remaining overlay as a repository primitive or remove it;
- run AGS tests plus MeshX and AgentTeam consumer tests.

Features removed upstream are not restored by default. Product features move to
MeshX when they are not repository primitives.

## 7. Current capability classification

| Capability | Owner | Integration |
| --- | --- | --- |
| Embedded AgentTeam identity | AGS primitive + MeshX identity source | canonical `WithAuthenticator` |
| MeshX-owned repository workload identity | MeshX | shared `agentteam / meshx-internal` identity; product actors remain attribution only |
| Direct collaborator grant/revoke | AGS primitive | narrow embedded repository API |
| Repository archive at commit | AGS primitive | narrow embedded archive API |
| Exact-commit search/list/read | AGS primitive | narrow in-process local Git CLI primitive; product authorization remains in MeshX; remove the overlay when canonical AGS exposes an equivalent exact-commit, streaming, bounded local-object primitive |
| Startup without DDL and explicit migration | AGS deployment primitive | narrow embedded lifecycle API |
| Repository Access Tokens | MeshX | MeshX persistence and request-scoped AGS identity |
| Workspace/member/agent permission mapping | MeshX | access intents and reconciliation |
| Automation branch updates | MeshX | canonical repository event adapter |
| Resource activity projection | MeshX | canonical repository event adapter |
| Attachment, presence, typing, and read state | AgentTeam/MeshX product surfaces | no AGS overlay |
| Ready-for-review | canonical AGS | `PATCH pull_request` with `draft=false` |
| Wiki and code search | canonical AGS | canonical API |

## 8. Review checklist

- Does every AGS overlay line implement a repository or deployment primitive?
- Is all workspace/member/agent policy in MeshX?
- Do token checks fail closed for repository, capability, status, and expiry?
- Are repository events policy-free when they leave AGS?
- Can the upstream subtree be replaced again without reconstructing product
  lifecycle code inside AGS?