Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,19 +41,19 @@ individual key provenance. Projects and keys are database-owned, with no static
business keys or configuration synchronization. Revocation affects one key;
archiving a Project revokes all its keys, retaining assets and admitted execution.
Do not add Core users, roles, memberships or cross-Project sharing. Management
provides safe reads, public deletion preconditions, explicit hosted Session archive,
independent copies and Project and key operations; it cannot execute or edit arbitrary assets. Keep administrator
target scope separate from caller principals. See [design principles](docs/design-principles.md) and the
provides safe reads, public deletion preconditions, explicit hosted Session archive
and Project and key operations; it cannot copy, execute or edit arbitrary assets.
Keep administrator target scope separate from caller principals. See
[design principles](docs/design-principles.md) and the
[administrator contract](contracts/agents-api/admin-api.md).

Administrator writes and their audit record share one PostgreSQL transaction.
Reuse existing resource deletion and serialization code. Copies rebind encrypted
content and rewrite included dependencies inside the same transaction, including
large objects, `admin_asset_copies` retry receipts and `admin_resource_owners`
creation anchors. Never call separately committing resource creators from a copy.
These anchors identify administrator copies even when API-key provenance is null;
unknown historical provenance remains unknown. No secrets or request bodies enter
logs. A forwarded console actor name is only a label, never an authorization input.
Reuse existing resource deletion and serialization code. Cross-Project copying was
removed. `admin_resource_owners` alone feeds the historical `source:"admin_copy"`
provenance read; `admin_asset_copies` is retained only because tables are not
dropped. Unknown historical provenance remains unknown. No secrets or request
bodies enter logs. A forwarded console actor name is only a label, never an
authorization input.

When requirements conflict, object ownership is unclear, or a design would need
parallel compatibility paths, raise the issue with a concrete recommendation and
Expand Down
2 changes: 1 addition & 1 deletion contracts/agents-api/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ compatibility.

| Extension | Operations | Current coverage |
| --- | --- | --- |
| Administration | `/core/v1/admin/**` | Deployment-authenticated Projects with shared keys, read/delete projections, atomic asset copies, summary, runtime observations and audit. Separate from caller authority; see [Administrator API](admin-api.md). |
| Administration | `/core/v1/admin/**` | Deployment-authenticated Projects with shared keys, read/delete projections, summary, runtime observations and audit. Separate from caller authority; see [Administrator API](admin-api.md). |
| API-key provenance | Project-scoped `/core/v1/admin/projects/{project_id}/resource-owners` and `/write-operations` | Batch ownership and retained cursor-paginated write history; see [write provenance](write-audit.md). |
| Runtime observations | `GET /v1/agents/runtime-observations`; `GET /v1/agents/sessions/{session_id}/runtime-observation` | Current, read-only, tenant-scoped Session contexts with stable Session-keyset pagination, bounded concurrent sampling, Docker and microsandbox metrics, explicit unsupported/unavailable states, strict `packages/agents-client` projection, and no lifecycle mutation. Kubernetes, E2B, self-hosted telemetry, and automatic idle policy remain unimplemented. See [Runtime observation API](runtime-observability-api.md). |
| Runtime history | `GET /v1/agents/runtime-history/capabilities`; `GET /v1/agents/sessions/{session_id}/runtime-history` | Optional backend-neutral capability and bounded tenant/Session-scoped history contract with allocation/incarnation fencing, explicit coverage and strict client projection. Disabled by default until a production Reader and qualified periodic collection are configured; Durable Web rendering remains pending. See [Runtime history API](runtime-history-api.md). |
Expand Down
53 changes: 12 additions & 41 deletions contracts/agents-api/admin-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,9 @@ must match those values. All keys share subject `service_account/project:<UUID>`
Rotate by issuing a new key in the same Project and revoking the old one. Revoking
one key leaves other keys, assets and admitted work intact. Archive atomically
marks the Project archived, revokes all its keys and records audit. Archived
Projects cannot issue keys or receive copies; their assets remain available for
administrator inspection, deletion and copying to another active Project. There
is no Project deletion, unarchive, key reset or automatic write retry operation.
Projects cannot issue keys; their assets remain available for administrator
inspection and deletion. There is no Project deletion, unarchive, key reset or
automatic write retry operation.
After an uncertain issuance response, inspect metadata and explicitly revoke any
unusable key before issuing another; plaintext cannot be recovered.

Expand Down Expand Up @@ -106,39 +106,12 @@ and pending counts are zero before changing provider, resources or Runtime.
Snapshots and uncertain cleanup remain blockers. This is not a deployment-wide
bulk operation, Session migration or public Session deletion.

## Copies

`POST /copies` takes `source_project_id`, `target_project_id`, `resource_type`, `resource_id`,
`include_dependencies`, and optional `target_vault_id` for a standalone Credential.
Different source and target Projects are required. An archived target returns 409,
including retries of an earlier copy; an archived source remains readable. `Idempotency-Key` makes identical
retries return the committed result; a changed request conflicts. Without the
header a separate request may create another copy; clients must not retry an
uncertain copy automatically.

Response: `{mappings: [{type, source_id, target_id}], skipped: [{type, source_id,
reason}]}`. Supported types are `agent`, `skill`, `environment_template`, `file`,
`vault`, and `credential`.

- Agent configuration and model credentials are copied with new encryption
bindings. Included referenced Vaults and supported Credentials receive new IDs.
Uncopied/skipped MCP Credential references become null. Runtime matching still
requires explicitly attached target Vaults.
- Skills retain every existing version number and their default/latest pointers;
encrypted bundles are rebound to the new tenant and identifiers.
- Templates retain confidential env/setup, files, packages, inline Skills/Plugins,
network and directory settings. Referenced files/Skills require
`include_dependencies=true` and are rewritten to copied IDs.
- Files copy actual PostgreSQL large-object bytes, up to the existing 512 MiB limit.
- A Vault copies its allowed Credentials. `static_bearer` and non-refreshing
`mcp_oauth` values are decrypted/re-encrypted internally. Refreshable OAuth
credentials appear in `skipped`, with no usable copied token.
- Sessions and Artifacts are not copyable.

One transaction owns all mutations, the idempotency receipt and administrator
log. A failure rolls back every dependency and large object. Copies have
`api_key:null`, `source:"admin_copy"`, and `admin_audit_id` in resource ownership;
historical unknown resources have null source and audit ID.
## Historical copy provenance

Cross-Project asset copying has been removed; no route creates copies. Resources
copied before the removal keep `api_key:null`, `source:"admin_copy"` and their
`admin_audit_id` in resource ownership, and their `copy` audit entries keep their
`result_ids` mappings. Historical unknown resources have null source and audit ID.

## Monitoring and audit

Expand All @@ -165,18 +138,16 @@ Each `observation` is the project Runtime observation plus `disk:
reported disk usage and capacity, Docker returns null, and microsandbox returns
null until its disk semantics are designed. The project-scoped observation
routes, including the per-Session administrator read, keep their shape.
`GET /runtime-history/capabilities` and `GET /startup-configuration` reuse the
existing non-secret project projections.

`GET /audit-log` lists administrator writes newest first with `project_id`,
`resource_type`, `resource_id`, `action`, inclusive `created_after`, exclusive
`created_before`, `limit=1..100` (default 50), and opaque `after` filters. Response
is `{data, has_more, next_cursor}`. Each row has `id`, `created_at`,
`admin_credential_id` (credential digest prefix), `actor_label`, `action`,
`project_id`, `resource_type`, `resource_id`, `result_ids`, `request_id`,
`trace_id`. Non-copy mappings are an empty array. No credential values or request
bodies are recorded. Logs and copy ownership do not cascade away on resource
removal or key revocation.
`trace_id`. `result_ids` is an empty array except on historical `copy` entries.
No credential values or request bodies are recorded. Logs and historical copy
ownership do not cascade away on resource removal or key revocation.

## Private installation transition

Expand Down
7 changes: 4 additions & 3 deletions contracts/agents-api/runtime-history-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,9 +125,10 @@ public Session usage, which is null while a root Turn runs or after one ends
unmeasured ([item serialization](history-events-usage.md#item-serialization-2026-09-23)). These counters
are measured model usage, not price, cost, or billing records.

Core Web queries each current managed Session through this boundary with bounded
concurrency and an all-or-nothing target budget. It offers 1h, 6h, and 24h History
ranges only after capability discovery succeeds. Reloading Web reconstructs the
Core Web queries each current managed Session through the administrator Session
route with bounded concurrency and an all-or-nothing target budget, offering 1h,
6h, and 24h History ranges. Capability discovery exists only on the application
route above; the administrator API has none. Reloading Web reconstructs the
charts from the backend; Live browser samples and Durable buckets remain explicit
separate sources and are never silently merged.

Expand Down
Loading
Loading