feat: agent grants, the gateway error protocol, and grant summaries

[guyb1]

What

Aligns the SDK with the server's attach model. All additive — a minor release.

Agent grants (on OneCLI and AgentsClient)

await onecli.setConnectionGrant(agentId, connectionId, { access: "full" });
await onecli.setConnectionGrant(agentId, connectionId, { access: "custom", allow: [...], ask: [...] });
await onecli.removeConnectionGrant(agentId, connectionId);   // 204 → void
await onecli.attachSecret(agentId, secretId);                // no-body PUT
await onecli.detachSecret(agentId, secretId);
const grants  = await onecli.getAgentGrants(agentId);
const reverse = await onecli.getConnectionGrants(connectionId);
const agents  = await onecli.listAgentsWithGrants();         // ?include=grants-summary

ConnectionGrantInput is a discriminated union that encodes the server's contract exactly (a custom grant carries both arrays). Grant writes return the agent's fresh AgentGrants; the connection-side write twins are deliberately omitted (identical server operations).

Typed gateway protocol (src/gateway/types.ts)

Typed bodies for every error the gateway returns on proxied agent traffic — multiple_connections / multiple_providers (the 409 account-selection protocol), connection_not_found, access_restricted, blocked_by_policy, blocked_by_default_policy, credential_not_found — plus a parseGatewayError() narrowing helper and the CONNECTION_ID_HEADER / CONNECTIONS_HEADER constants. Pure types + one pure function; agent traffic itself rides the proxy, not this SDK.

Better errors

The agents request path now surfaces the server's error-envelope message — a 410's replacement pointer, a 422's validation constraint — instead of a bare OneCLI returned 410 Gone.

3.0.0 hygiene

Dead unexported OrgRule/CreateOrgRuleInput/UpdateOrgRuleInput deleted; live-but-unexported OrgRuleCondition/OrgRuleMethod/OrgRuleRateLimitWindow exported; PolicyRuleIdentity narrowed to what the server accepts (agent | user | group); stale parentIdentifier inheritance and EffectiveCredentials.mode prose fixed; the README's type-surface section rewritten so it actually compiles (verified mechanically).

Tests + typecheck

pnpm typecheck now covers test/ (dedicated tsconfig.test.json; the build tsconfig is untouched), which surfaced and fixed pre-existing constructor-arity bugs in two test files. New suites: per-method URL/method/body assertions, the double path-encoding idiom, 204-no-parse, parseGatewayError per body shape, error-envelope surfacing, and facade-delegation tests pinning every new method on OneCLI itself. 131 tests total.

Server dependency

The grants API is live on OneCLI Cloud today (shipped via onecli/onecli-cloud#743 and the preceding attach-model PRs). OSS servers gain the surface with the next OSS sync — until then the new methods 404 against OSS builds.

Siblings: CLI onecli/onecli-cli#102 · docs onecli/onecli-docs#11 (docs merges last).

Review

Full /review-change: hunk-by-hunk self-review, a 36-skill walk (10 applied incl. typescript-pro + typescript-advanced-types for the public type design and cloud-development for the public-repo sweep), a field-by-field contract check against the live routes, and an adversarial sweep. SDK-side fix from review: the OneCLI facade was missing the 8 new methods the README documents — wired + pinned by tests.

Gates: pnpm typecheck (src + tests) · 131 tests · pnpm build (CJS + ESM + DTS) — all green.

🤖 Generated with Claude Code