feat!: retire the legacy org rules API, expose the policy reflections

README.md

@@ -231,6 +231,44 @@ for (const agent of agents) {
 
 **Returns** `Array<{ id, name, identifier, isDefault, createdAt }>`
 
+#### `onecli.getEffectiveCredentials(agentId, options?)`
+
+Which credentials the agent can actually use, and what each one can do under the
+published policy. Read-only.
+
+```ts
+const { mode, secrets, connections } =
+  await onecli.getEffectiveCredentials("agent-id");
+```
+
+Replaces the retired `GET /v1/agents/{id}/secrets` and `/connections` reads.
+Those returned a stored assignment list; this returns the **effective** set, so a
+credential granted by a policy rule appears here even though no assignment row
+exists for it.
+
+#### `onecli.getEffectiveAppPermissions({ provider, agentId? }, options?)`
+
+What the project's published policy allows for an app, per tool. Omit `agentId`
+for the all-agents baseline. The project-scope twin of
+`onecli.org.getEffectiveAppPermissions`, and the replacement for the retired
+`GET /v1/rules/permissions/{provider}`.
+
+```ts
+const { groups, variesByIdentity } = await onecli.getEffectiveAppPermissions({
+  provider: "gmail",
+});
+```
+
+#### `onecli.getConnectionAgentAccess(connectionId, options?)`
+
+Which agents can reach a connection, and what each can do with it. Replaces the
+retired `GET /v1/connections/{id}/agents`.
+
+#### `onecli.listAppPermissionDefinitions(options?)`
+
+Every provider's public tool catalog — the tool ids an `app`-target policy rule
+can name.
+
 #### `onecli.ensureAgent(input, options?)`
 
 Ensure an agent exists. Creates it if missing, returns normally if it already exists.
@@ -416,9 +454,10 @@ await onecli.org.updatePolicyRule(created.id, { enabled: false });
 await onecli.org.deletePolicyRule(created.id);
 await onecli.org.publishPolicy(); // publish anything still staged
 
-// Legacy org rules (deprecated): cloud deployments reject these writes with
-// 410 Gone; pre-cutover self-hosted servers still accept them.
-const legacyRules = await onecli.org.listRules();
+// What the published policy actually allows for an app, per tool — read-only.
+const effective = await onecli.org.getEffectiveAppPermissions({
+  provider: "gmail",
+});
 
 // Watch manual-approval requests across every project in the org. Each request
 // carries its own `projectId`, and the decision is routed back to that project.
@@ -457,11 +496,7 @@ identified by `metadata.provider` + `metadata.toolId`.
 | `getPolicyDefault(status?)` / `setPolicyDefault(action, opts?)` | `GET`/`PATCH /v1/org/policy/default` | `OrgPolicyRule` / `PolicyWriteResult<OrgPolicyRule>` |
 | `publishPolicy()` | `POST /v1/org/policy/publish` | `PolicyPublishResult` |
 | `getPolicyLastPublish()` | `GET /v1/org/policy/last-publish` | `PolicyLastPublish \| null` |
-| `listRules()` *(legacy)* | `GET /v1/org/rules` | `OrgRule[]` |
-| `getRule(id)` *(legacy)* | `GET /v1/org/rules/{id}` | `OrgRule` |
-| `createRule(input)` *(deprecated — 410 on cloud)* | `POST /v1/org/rules` | `OrgRule` |
-| `updateRule(id, input)` *(deprecated — 410 on cloud)* | `PATCH /v1/org/rules/{id}` | `{ success: boolean }` |
-| `deleteRule(id)` *(deprecated — 410 on cloud)* | `DELETE /v1/org/rules/{id}` | `void` |
+| `getEffectiveAppPermissions({provider})` | `GET /v1/org/policy/effective-app-permissions` | `EffectiveAppPermissions` |
 | `configureManualApproval(cb, options?)` | `GET /v1/org/approvals/pending` (long-poll) | `ManualApprovalHandle` |
 
 ---

src/agents/index.ts

@@ -5,8 +5,12 @@ import {
 } from "../errors.js";
 import type {
   Agent,
+  AppPermissionDefinition,
+  ConnectionAgentAccess,
+  EffectiveAppPermissions,
   CreateAgentInput,
   CreateAgentResponse,
+  EffectiveCredentials,
   EnsureAgentResponse,
 } from "./types.js";
 import type { RequestOptions } from "../request-options.js";
@@ -111,6 +115,105 @@ export class AgentsClient {
     }
   };
 
+  /**
+   * Shared GET for the read-only reflections. Mirrors `listAgents`' error
+   * handling so every method on this client fails the same way.
+   */
+  private getJson = async <T>(
+    path: string,
+    options?: RequestOptions,
+  ): Promise<T> => {
+    const url = `${this.baseUrl}${path}`;
+
+    try {
+      const res = await fetch(url, {
+        method: "GET",
+        headers: this.buildHeaders(options),
+        signal: AbortSignal.timeout(this.timeout),
+      });
+
+      if (!res.ok) {
+        throw new OneCLIRequestError(
+          `OneCLI returned ${res.status} ${res.statusText}`,
+          { url, statusCode: res.status },
+        );
+      }
+
+      return (await res.json()) as T;
+    } catch (error) {
+      if (
+        error instanceof OneCLIError ||
+        error instanceof OneCLIRequestError
+      ) {
+        throw error;
+      }
+      throw toOneCLIError(error);
+    }
+  };
+
+  /**
+   * Which credentials this agent can actually use, and what each one can do
+   * under the published policy.
+   *
+   * Replaces the retired `GET /v1/agents/:id/{secrets,connections}` reads. Those
+   * returned a stored assignment list; this returns the EFFECTIVE set, so a
+   * credential granted by a policy rule appears here even though no assignment
+   * row exists for it.
+   */
+  getEffectiveCredentials = async (
+    agentId: string,
+    options?: RequestOptions,
+  ): Promise<EffectiveCredentials> =>
+    this.getJson<EffectiveCredentials>(
+      `/v1/agents/${encodeURIComponent(agentId)}/effective-credentials`,
+      options,
+    );
+
+  /**
+   * What the project's published policy allows for an app, per tool. Omit
+   * `agentId` for the all-agents baseline.
+   *
+   * The project-scope twin of `org.getEffectiveAppPermissions`, and the
+   * replacement for the retired `/v1/rules/permissions/:provider`.
+   */
+  getEffectiveAppPermissions = async (
+    input: { provider: string; agentId?: string },
+    options?: RequestOptions,
+  ): Promise<EffectiveAppPermissions> => {
+    const query = new URLSearchParams({ provider: input.provider });
+    if (input.agentId) query.set("agentId", input.agentId);
+    return this.getJson<EffectiveAppPermissions>(
+      `/v1/policy/effective-app-permissions?${query.toString()}`,
+      options,
+    );
+  };
+
+  /**
+   * Which agents can reach a connection, and what each can do with it.
+   *
+   * Replaces the retired `GET /v1/connections/:id/agents`.
+   */
+  getConnectionAgentAccess = async (
+    connectionId: string,
+    options?: RequestOptions,
+  ): Promise<ConnectionAgentAccess> =>
+    this.getJson<ConnectionAgentAccess>(
+      `/v1/connections/${encodeURIComponent(connectionId)}/effective-agents`,
+      options,
+    );
+
+  /**
+   * Every provider's public tool catalog — the tool ids an app-target policy
+   * rule can name. Global data; no project context required.
+   */
+  listAppPermissionDefinitions = async (
+    options?: RequestOptions,
+  ): Promise<AppPermissionDefinition[]> =>
+    this.getJson<AppPermissionDefinition[]>(
+      "/v1/apps/permission-definitions",
+      options,
+    );
+
   /**
    * Whether an agent with the given identifier already exists in the project.
    * Swallows lookup failures and returns `false` so callers can fall back to

src/agents/types.ts

@@ -31,3 +31,107 @@ export interface EnsureAgentResponse {
   /** Whether the agent was newly created. `false` if it already existed. */
   created: boolean;
 }
+
+// ── Read-only policy reflections (project scope) ────────────────────────────
+//
+// These replace the retired per-agent equipment reads
+// (`/v1/agents/:id/{secrets,connections}`, `/v1/agents/granular-access`,
+// `/v1/connections/:id/agents`). They report what the PUBLISHED policy actually
+// allows — not a stored assignment list, which no longer exists.
+
+/** What a credential can do under the rules, once attached. */
+export type CredentialAccessStatus =
+  | "usable"
+  | "limited"
+  | "blocked"
+  | "unknown";
+
+/** Why a credential reaches this agent. An org rule's name is visible only to
+ * org admins; other viewers get `redacted: true`. */
+export type CredentialProvenance =
+  | { kind: "rule"; scope: "organization"; redacted: true }
+  | {
+      kind: "rule";
+      scope: "organization" | "project";
+      rule: { logicalId: string; name: string };
+    };
+
+export type EffectiveCredential =
+  | {
+      kind: "secret";
+      id: string;
+      name: string;
+      host: string;
+      status: CredentialAccessStatus;
+      provenance: CredentialProvenance[];
+    }
+  | {
+      kind: "connection";
+      id: string;
+      label: string | null;
+      provider: string;
+      status: CredentialAccessStatus;
+      provenance: CredentialProvenance[];
+    };
+
+export interface EffectiveCredentials {
+  agentId: string;
+  /** `all` draws the whole fenced pool; `selective` gets only what rules grant. */
+  mode: "all" | "selective";
+  secrets: EffectiveCredential[];
+  connections: EffectiveCredential[];
+}
+
+/** The headline for one agent against one connection. */
+export type AgentAccessStatus =
+  | "usable"
+  | "limited"
+  | "blocked"
+  | "none"
+  | "unknown";
+
+/** How the credential attaches — the secondary detail under `access`. */
+export type AgentCredentialStatus =
+  | { status: "full" }
+  | { status: "viaRule"; provenance: CredentialProvenance[] }
+  | { status: "none" };
+
+export interface ConnectionAgent {
+  agentId: string;
+  name: string;
+  access: AgentAccessStatus;
+  credential: AgentCredentialStatus;
+  /** Null when the provider has no tool catalog to evaluate. */
+  decisions: {
+    allowedTools: number;
+    totalTools: number;
+    anyApproval: boolean;
+    anyRateLimit: boolean;
+  } | null;
+}
+
+export interface ConnectionAgentAccess {
+  connectionId: string;
+  provider: string;
+  /** False = no permission catalog, so `decisions` is absent by honesty. */
+  catalog: boolean;
+  agents: ConnectionAgent[];
+}
+
+/** One provider's public tool catalog — ids and labels only; the endpoint
+ * mapping never leaves the server. */
+export interface AppPermissionDefinition {
+  provider: string;
+  groups: {
+    category: "read" | "write";
+    tools: { id: string; name: string; description?: string }[];
+  }[];
+}
+
+export type {
+  EffectiveAppPermissions,
+  EffectiveProvenance,
+  EffectiveTool,
+  EffectiveToolGroup,
+  EffectiveToolVerdict,
+} from "../org/types.js";

src/client.ts

@@ -12,8 +12,12 @@ import type {
 } from "./container/types.js";
 import type {
   Agent,
+  AppPermissionDefinition,
+  ConnectionAgentAccess,
   CreateAgentInput,
+  EffectiveAppPermissions,
   CreateAgentResponse,
+  EffectiveCredentials,
   EnsureAgentResponse,
 } from "./agents/types.js";
 import type {
@@ -123,6 +127,52 @@ export class OneCLI {
   /**
    * Ensure an agent exists. Creates it if missing, returns normally if it already exists.
    */
+  /**
+   * Which credentials this agent can actually use, and what each one can do
+   * under the published policy. Read-only.
+   *
+   * Replaces the retired `GET /v1/agents/:id/{secrets,connections}` reads —
+   * those returned a stored assignment list, this returns the EFFECTIVE set.
+   */
+  getEffectiveCredentials = (
+    agentId: string,
+    options?: RequestOptions,
+  ): Promise<EffectiveCredentials> => {
+    return this.agentsClient.getEffectiveCredentials(agentId, options);
+  };
+
+  /**
+   * What the project's published policy allows for an app, per tool.
+   * Replaces the retired `GET /v1/rules/permissions/:provider`.
+   */
+  getEffectiveAppPermissions = (
+    input: { provider: string; agentId?: string },
+    options?: RequestOptions,
+  ): Promise<EffectiveAppPermissions> => {
+    return this.agentsClient.getEffectiveAppPermissions(input, options);
+  };
+
+  /**
+   * Which agents can reach a connection, and what each can do with it.
+   * Replaces the retired `GET /v1/connections/:id/agents`.
+   */
+  getConnectionAgentAccess = (
+    connectionId: string,
+    options?: RequestOptions,
+  ): Promise<ConnectionAgentAccess> => {
+    return this.agentsClient.getConnectionAgentAccess(connectionId, options);
+  };
+
+  /**
+   * Every provider's public tool catalog — the tool ids an `app`-target policy
+   * rule can name.
+   */
+  listAppPermissionDefinitions = (
+    options?: RequestOptions,
+  ): Promise<AppPermissionDefinition[]> => {
+    return this.agentsClient.listAppPermissionDefinitions(options);
+  };
+
   ensureAgent = (
     input: CreateAgentInput,
     options?: RequestOptions,