# Agent9 Auto-oncall Tool packages

This directory contains three reviewed evidence Tool packages submitted to
Agent9. It does not contain a generic provider Tool or a Jira Tool.

Jira issue lookup, comments, attachments, and writes remain in the Auto-oncall
orchestration boundary. Auto-oncall resolves the exact authorized ticket before
starting the Agent and supplies only that ticket's bounded workspace. Allowing
the model to choose an arbitrary Jira issue key would reintroduce cross-ticket
data access that a project allowlist cannot prevent.

Tool package mapping:

| Agent-visible Tool package | Internal connector | Agent9 network mode | Boundary |
| --- | --- | --- | --- |
| `managed_auto_oncall_clinic` | Clinic with bounded DevOps CloudConfig fallback | `restricted` | A separate Tool Sandbox reaches only Clinic and the production DevOps CloudConfig host. Agent9 injects separate Clinic and DevOps Auth values. The Tool validates ticket shape, exact org/cluster arguments, supported operations, configuration selectors, and bounded time ranges. Clinic metadata remains the authority for whether that org owns the cluster. |
| `managed_auto_oncall_manus` | Manus | `restricted` | A separate Tool Sandbox may reach only the exact Manus Grafana, Prometheus, and Dashboard hosts and receives only the Manus Auth. |
| `managed_auto_oncall_wetech` | Wetech | `restricted` by default; Workspace Admin grants `unrestricted` on the installation | A separate browser-capable Tool Sandbox uses unrestricted outbound internet only through the Agent9 installation authorization needed for the P81 browser handshake. Static Wetech credentials and the dedicated Drive9 owner key come from the installation Auth; refreshed browser state remains in Drive9. |
| Jira and Investibook | none | no Agent Tool | Auto-oncall loads them before the Agent run and applies authorization itself. |

`managed-clinic/`, `managed-wetech/`, and `managed-manus/` are owned and
reviewed here, not in Agent9. Agent9 owns only their generic package
registration and isolated execution.

AOS also owns the immutable internal-production bundle/catalog pins and the
`agent9-managed-tool-loader` ConfigMap under
`deploy/agent9-managed-tools/prod-internal-us-west-2-pingcap/`. Publish and
reload that configuration with:

```bash
npm run deploy:agent9-tools -- --context agent9-pingcap-prod-us-west-2-eks
```

The command updates only the AOS-owned ConfigMap and rollout annotation, checks
that the Agent9 image is unchanged, and waits for the generic loader to finish.
New Auto-oncall package versions must not be copied into Agent9 or require an
Agent9 pull request. Exact Tool installation and Auth binding still go through
Agent9's authorized API and are separate from catalog publication.

The Wetech manifest only declares that its reviewed package is eligible for a
Workspace Admin unrestricted-network grant. Publication cannot activate that
grant, and neither the Evidence Agent nor a Tool call can request it. The AOS
release command explicitly sets the Wetech installation to `unrestricted` and
keeps Clinic `restricted`; Agent9 persists and audits the Workspace Admin
choice independently from the Tool's invocation policy.

The three package identities are independent Agent Tools. Clinic, Wetech, and
Manus remain implementation connectors inside their respective packages. No
manifest accepts a `provider` property, and the Agent cannot use one Tool to
select or obtain another connector's credentials. Installation must use three
separate Auth bindings; do not combine their environment keys into one Auth.

The packages do not depend on installation-level per-ticket policy. Auto-oncall
freezes the ticket, target, and absolute incident window in the Evidence Agent
Turn; each Tool script validates its own ticket shape, bundled target or
provider target, operation set, and maximum query window before network use.
An old test-ticket policy stored on an Agent9 installation is therefore not an
authorization input and cannot block a later ticket.

Clinic, Manus, and Wetech use one model-visible result envelope. For every
success, failure, and batch result, `details` owns the compact structured
result and `text` contains the exact JSON serialization of that same object.
Failures expose their safe Provider or validation detail as `detail_error`;
successes expose compact evidence without that field. Provider helpers do not
replace a Provider rejection with a separate prose diagnosis or summary.

The Clinic package exposes only one bounded batch of at most twelve Agent-authored
PromQL or read-only SQL operations. It executes independent entries with a
concurrency limit of six in one Tool Sandbox and returns one compact result or
safe error per stable query id. A later correction batch may contain only
changed failed entries; the auto-oncall materializer folds an unchanged
duplicate attempt into bounded metadata for that query without dropping its
first error or peer evidence. The 108-second execution budget is divided by
concurrency waves and starts when each query is scheduled, preventing a slow
first wave from starving later entries under the outer 120-second Tool timeout.
The canonical custom SQL field is `sql`. For compatibility, `sql_query`
normalizes `query` only when `sql` is absent; both fields together remain an
actionable error. Supplemental query errors remain visible per query but are
not corrected and do not degrade primary acquisition.
The package also owns canonical TopSQL, tier-aware Slow Query,
Loki range, activity, cluster metadata, and component operations. It releases
only compact summaries, safe labels, opaque entity or digest references,
component counts, and minimal non-commercial cluster metadata. It never returns
cost, billing, SKU, machine type, internal address, raw SQL text, or a raw
provider response. A Loki range query selects summary or event detail. Event
detail is limited to allowlisted typed lifecycle groups, timestamps, safe source
locations, booleans, and numeric execution fields; it never returns raw log
lines, connection IDs, full Digests, SQL, or arbitrary messages. Each Clinic
request retries the identical read-only request
at most twice after an HTTP 5xx with bounded delays; HTTP 4xx responses remain
request corrections and are not retried unchanged. A Clinic metrics range or Activities request may span the
Router's full 30-day diagnostic window. TopSQL, Slow Query, exported SQL, and
logs remain capped at 24 hours. Evidence planning treats these as ceilings and
starts from the narrowest incident-aligned window rather than defaulting to the
maximum.

The configuration operation accepts only one to sixteen exact non-secret PD,
TiKV, TiDB, or TiDB-variable selector objects in one batch entry. It calls the
canonical Clinic Dashboard configuration endpoint first with the resolved org
and cluster headers, then uses DevOps CloudConfig only for a Clinic 4xx
rejection or an exact key that Clinic omitted. It never omits the org header,
returns the full configuration, or exposes a mutation operation. The Evidence
Agent cannot select CloudConfig as a separate operation; fallback and its
credential remain inside the helper. An explicit cluster value precedes the
exact cluster-version default.

The Wetech package accepts bounded Agent-authored PromQL and owns the TiDB
Dashboard TopSQL, Statements, and Slow Query operations. The ticket must be an
APID key, the region/cluster pair must exist in the canonical Skill inventory,
and the absolute time range must be at most six hours before browser startup;
TopSQL is further capped
at fifteen minutes and requires one exact metric-selected TiDB instance. Its
manifest declares only secret names. P81, Grafana, Dashboard, the reviewed
Drive9 origin, and the dedicated Drive9 owner key are digest-bound installation
secrets. Every execution reads
the latest Playwright storage state from `/wetech/auth/storage-state.json` in
that Tool-only Drive9 workspace and writes a refreshed state back with revision
CAS; browser state does not pass through Tool arguments or results.
Grafana and Prometheus query rejections expose their complete
credential-redacted provider text as `detail_error`; the helper does not
replace query syntax, label matching, or duplicate-series context with a
helper-authored diagnosis.

The package build generates its digest-bound runtime target map and target host
allowlist from `skills/wetech-op-grafana/data/clusters.json`; the generated
`managed-wetech/clusters.json` is not a separately maintained target inventory.
The trusted target selects the credential profile: Asia production uses its
regional Grafana password, Asia SaaS01/SaaS02 use their Dashboard password, and
other targets use the default passwords. The Agent cannot select a credential
profile or supply a URL, datasource UID, Dashboard cluster name, or secret.

The Manus package supports exact `vida` or `monica` targets and allows the
Agent to author PromQL freely. The security boundary is the authorized ticket,
exact target, operation, time range, fixed `query_range` endpoint, bounded
output, and result sanitization rather than a metric allowlist. Provider
instance addresses are returned as encrypted opaque references so a later
bounded Tool call can select the same instance without exposing its address to
the Agent.

Build its immutable manifest with:

```bash
npm run build:agent9-tools
```

The earlier fixed-query Wetech package was validated locally through Agent9/E2B
against historical case `APID-29213`. The expanded package and the Manus
package currently have local contract coverage but require live Agent9 provider
smoke. Package publication, catalog loading, Agent-scoped installation with the
matching Auth, and provider-specific case replay are separate rollout evidence.