@openwop/openwop 1.1.5 → 1.2.0

package/src/client.ts

@@ -51,6 +51,19 @@ import {
   type RunSnapshot,
   type AgentInventoryEntry,
   type AgentInventoryResponse,
+  type AgentRosterEntry,
+  type AgentRosterResponse,
+  type AgentOrgChart,
+  type OrgChartResponsibilityView,
+  type EvalSummary,
+  type ToolDescriptor,
+  type AgentDeployment,
+  type AgentDeploymentTransition,
+  type CreateUserAgentRequest,
+  type UserAgentRecord,
+  type AgentPackRegistryResponse,
+  type InstallAgentPackRequest,
+  type InstallAgentPackResponse,
 } from './types.js';
 
 export interface OpenwopClientOptions {
@@ -150,7 +163,7 @@ export class OpenwopClient {
       } catch (err) {
         // Host doesn't advertise the capability → 404. Surface as null so callers
         // can branch on capability discovery without try/catch.
-        if (err instanceof Error && /\b404\b/.test(err.message)) return null;
+        if (err instanceof WopError && err.status === 404) return null;
         throw err;
       }
     },
@@ -254,7 +267,7 @@ export class OpenwopClient {
         });
         return res.annotations;
       } catch (err) {
-        if (err instanceof Error && /\b(404|501)\b/.test(err.message)) return null;
+        if (err instanceof WopError && (err.status === 404 || err.status === 501)) return null;
         throw err;
       }
     },
@@ -277,7 +290,7 @@ export class OpenwopClient {
           path: `/v1/runs/${encodeURIComponent(runId)}/ancestry`,
         });
       } catch (err) {
-        if (err instanceof Error && /\b404\b/.test(err.message)) return null;
+        if (err instanceof WopError && err.status === 404) return null;
         throw err;
       }
     },
@@ -297,7 +310,44 @@ export class OpenwopClient {
           path: `/v1/runs/${encodeURIComponent(runId)}:diff?against=${encodeURIComponent(against)}`,
         });
       } catch (err) {
-        if (err instanceof Error && /\b404\b/.test(err.message)) return null;
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0081 §C — the `EvalSummary` scorecard for a terminal eval run (one
+     * started via `runs.create({ mode: 'eval', evalSuiteRef, agentId })`):
+     * aggregate + per-task scores, cost, latency, schema-validity, and
+     * redaction-safe safety findings. Returns `null` when the host doesn't
+     * advertise `capabilities.agents.evalSuite` or the run isn't an eval run
+     * (404). Throws `409` while the run is still in progress.
+     */
+    evalSummary: async (runId: string): Promise<EvalSummary | null> => {
+      try {
+        return await this.#request<EvalSummary>({
+          method: 'GET',
+          path: `/v1/runs/${encodeURIComponent(runId)}/eval-summary`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * Read a run-produced artifact by id (`GET /v1/runs/{runId}/artifacts/{artifactId}`).
+     * The artifact body is implementation-defined per the host. Returns `null`
+     * on 404 (no such artifact, or the host doesn't store artifacts).
+     */
+    getArtifact: async (runId: string, artifactId: string): Promise<Record<string, unknown> | null> => {
+      try {
+        return await this.#request<Record<string, unknown>>({
+          method: 'GET',
+          path: `/v1/runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(artifactId)}`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
         throw err;
       }
     },
@@ -339,7 +389,7 @@ export class OpenwopClient {
       try {
         return await this.#request<AgentInventoryResponse>({ method: 'GET', path: '/v1/agents' });
       } catch (err) {
-        if (err instanceof Error && /\b404\b/.test(err.message)) return null;
+        if (err instanceof WopError && err.status === 404) return null;
         throw err;
       }
     },
@@ -351,12 +401,204 @@ export class OpenwopClient {
           path: `/v1/agents/${encodeURIComponent(agentId)}`,
         });
       } catch (err) {
-        if (err instanceof Error && /\b404\b/.test(err.message)) return null;
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0082 §C/§E — list a manifest agent's deployment records (per-(agentId,
+     * version) lifecycle state + channels + canary + rollback pointer). Returns
+     * `null` when the host doesn't advertise `capabilities.agents.deployment`
+     * (the endpoint 404s).
+     */
+    listDeployments: async (agentId: string): Promise<readonly AgentDeployment[] | null> => {
+      try {
+        return await this.#request<AgentDeployment[]>({
+          method: 'GET',
+          path: `/v1/agents/${encodeURIComponent(agentId)}/deployments`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0082 §E — request a deployment state transition (promote / pause /
+     * deprecate / rollback / adjust-canary). The host authorizes fail-closed
+     * against the RFC 0049 `deploy:*` scope, runs any RFC 0051 approvalGate, and
+     * enforces RFC 0081 `requiredEval` before emitting `deployment.promoted`.
+     * Returns the updated deployment record. Throws on non-2xx (`403` fail-closed
+     * / `eval_gate_unmet`; `400` `no_active_deployment` / unsupported state).
+     */
+    transitionDeployment: (
+      agentId: string,
+      body: AgentDeploymentTransition,
+      opts: MutationOptions = {},
+    ): Promise<AgentDeployment> =>
+      this.#request<AgentDeployment>({
+        method: 'POST',
+        path: `/v1/agents/${encodeURIComponent(agentId)}/deployments`,
+        body,
+        headers: this.#mutationHeaders(opts),
+      }),
+
+    /**
+     * RFC 0086 §B — list the standing agent roster (named instances + their
+     * workflow portfolios) visible to the caller. Returns `null` when the host
+     * doesn't advertise `capabilities.agents.roster` (the endpoint 404s).
+     */
+    listRoster: async (): Promise<AgentRosterResponse | null> => {
+      try {
+        return await this.#request<AgentRosterResponse>({ method: 'GET', path: '/v1/agents/roster' });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0086 §B — return one standing roster entry. Returns `null` on 404
+     * (no such entry, cross-tenant, or the capability is unadvertised).
+     */
+    getRosterEntry: async (rosterId: string): Promise<AgentRosterEntry | null> => {
+      try {
+        return await this.#request<AgentRosterEntry>({
+          method: 'GET',
+          path: `/v1/agents/roster/${encodeURIComponent(rosterId)}`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0087 §C — return the caller's agent org-chart (departments + roles +
+     * `reportsTo` over roster members; descriptive — confers no authority).
+     * Returns `null` when the host doesn't advertise `capabilities.agents.orgChart`.
+     */
+    getOrgChart: async (): Promise<AgentOrgChart | null> => {
+      try {
+        return await this.#request<AgentOrgChart>({ method: 'GET', path: '/v1/agents/org-chart' });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0087 §D — one department's subtree + responsibility roll-up (the
+     * union of its members' RFC 0086 portfolios). `recursive: false` scopes the
+     * roll-up to direct members. Returns `null` on 404 (unknown/cross-tenant
+     * department, or the capability is unadvertised).
+     */
+    getOrgChartDepartment: async (
+      departmentId: string,
+      opts: { recursive?: boolean } = {},
+    ): Promise<OrgChartResponsibilityView | null> => {
+      const qs = opts.recursive === false ? '?recursive=false' : '';
+      try {
+        return await this.#request<OrgChartResponsibilityView>({
+          method: 'GET',
+          path: `/v1/agents/org-chart/${encodeURIComponent(departmentId)}${qs}`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
         throw err;
       }
     },
   };
 
+  // RFC 0078 — portable tool catalog (spec/v1/tool-catalog.md). The host
+  // projects every node-pack / workflow / mcp / connector / host-extension
+  // tool visible to the caller onto a uniform `ToolDescriptor`.
+  readonly tools = {
+    /**
+     * RFC 0078 §B — list the portable `ToolDescriptor`s visible to the caller.
+     * Returns `null` when the host doesn't advertise `capabilities.toolCatalog`
+     * (the endpoint 404s), so callers can branch on capability discovery.
+     */
+    list: async (): Promise<readonly ToolDescriptor[] | null> => {
+      try {
+        return await this.#request<ToolDescriptor[]>({ method: 'GET', path: '/v1/tools' });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0078 §B — return one `ToolDescriptor` by its stable `toolId`. Returns
+     * `null` on 404 (no such tool, or the capability is unadvertised).
+     */
+    get: async (toolId: string): Promise<ToolDescriptor | null> => {
+      try {
+        return await this.#request<ToolDescriptor>({
+          method: 'GET',
+          path: `/v1/tools/${encodeURIComponent(toolId)}`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+  };
+
+  // ── User-authored agents (sample-extension; non-normative) ───────────
+  // Backs the workflow-engine sample app's Agents tab. Pack-installed
+  // agents come through the `.agents` inventory above (RFC 0072 §A).
+  // These methods wrap the `POST/DELETE /v1/host/sample/agents` +
+  // `GET/POST /v1/host/sample/registry/agent-packs` host extensions.
+  // Returns `null` on 404 (capability absent — matches the `.agents`
+  // surface pattern); throws on other failures.
+  readonly userAgents = {
+    create: async (body: CreateUserAgentRequest, opts: MutationOptions = {}): Promise<UserAgentRecord> => {
+      return await this.#request<UserAgentRecord>({
+        method: 'POST',
+        path: '/v1/host/sample/agents',
+        body,
+        ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
+      });
+    },
+
+    delete: async (agentId: string): Promise<boolean> => {
+      try {
+        await this.#request<void>({
+          method: 'DELETE',
+          path: `/v1/host/sample/agents/${encodeURIComponent(agentId)}`,
+        });
+        return true;
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return false;
+        throw err;
+      }
+    },
+
+    listAvailablePacks: async (): Promise<AgentPackRegistryResponse | null> => {
+      try {
+        return await this.#request<AgentPackRegistryResponse>({
+          method: 'GET',
+          path: '/v1/host/sample/registry/agent-packs',
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    installPack: async (
+      body: InstallAgentPackRequest,
+    ): Promise<InstallAgentPackResponse> => {
+      return await this.#request<InstallAgentPackResponse>({
+        method: 'POST',
+        path: '/v1/host/sample/registry/agent-packs/install',
+        body,
+      });
+    },
+  };
+
   // ── HITL interrupts (run-scoped + signed-token) ──────────────────────
   readonly interrupts = {
     resolveByRun: (
@@ -484,15 +726,24 @@ export class OpenwopClient {
      * `version`; supply `libraryId` to disambiguate when multiple installed
      * packs ship the same templateId.
      */
-    get: (req: GetPromptRequest): Promise<PromptTemplate> => {
+    get: async (req: GetPromptRequest): Promise<PromptTemplate | null> => {
       const search = new URLSearchParams();
       if (req.version) search.set('version', req.version);
       if (req.libraryId) search.set('libraryId', req.libraryId);
       const query = search.toString();
-      return this.#request<PromptTemplate>({
-        method: 'GET',
-        path: `/v1/prompts/${encodeURIComponent(req.templateId)}${query ? `?${query}` : ''}`,
-      });
+      try {
+        return await this.#request<PromptTemplate>({
+          method: 'GET',
+          path: `/v1/prompts/${encodeURIComponent(req.templateId)}${query ? `?${query}` : ''}`,
+        });
+      } catch (err) {
+        // Return null on 404 (no such template), consistent with the other
+        // get-by-id methods (`agents.get`, `tools.get`, …) and the Python/Go
+        // SDKs; a `400 prompt_ref_ambiguous` and other errors still throw so
+        // callers can distinguish "not found" from "ambiguous reference".
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
     },
 
     /**
@@ -606,7 +857,7 @@ export class OpenwopClient {
         });
         return res.files;
       } catch (err) {
-        if (err instanceof Error && /\b501\b/.test(err.message)) return null;
+        if (err instanceof WopError && err.status === 501) return null;
         throw err;
       }
     },
@@ -627,7 +878,7 @@ export class OpenwopClient {
           path: `/v1/host/workspace/files/${encodeURIComponent(path)}${qs ? `?${qs}` : ''}`,
         });
       } catch (err) {
-        if (err instanceof Error && /\b(404|501)\b/.test(err.message)) return null;
+        if (err instanceof WopError && (err.status === 404 || err.status === 501)) return null;
         throw err;
       }
     },
@@ -668,7 +919,7 @@ export class OpenwopClient {
         });
         return true;
       } catch (err) {
-        if (err instanceof Error && /\b(404|501)\b/.test(err.message)) return false;
+        if (err instanceof WopError && (err.status === 404 || err.status === 501)) return false;
         throw err;
       }
     },

package/src/index.ts

@@ -69,6 +69,36 @@ export type {
   PromptVariable,
   RenderPromptRequest,
   RenderPromptResponse,
+  // RFC 0072 §A — Manifest-agent inventory (GET /v1/agents).
+  // Consumed by the workflow-engine sample app's Agents tab + chat
+  // `@` mention picker (2026-05-28 mention-symbol swap).
+  AgentInventoryEntry,
+  AgentInventoryResponse,
+  // RFC 0081 — Agent evaluation (spec/v1/agent-evaluation.md). EvalSummary
+  // scorecard read via `client.runs.evalSummary(runId)` for a `mode:'eval'` run.
+  AgentModelClass,
+  EvalSafetyFinding,
+  EvalTaskResult,
+  EvalRegression,
+  EvalSummary,
+  // RFC 0078 — Portable tool catalog (spec/v1/tool-catalog.md).
+  // `client.tools.list` / `client.tools.get`.
+  ToolDescriptor,
+  // RFC 0082 — Agent deployment lifecycle (spec/v1/agent-deployment.md).
+  // `client.agents.listDeployments` / `transitionDeployment`.
+  DeploymentState,
+  AgentDeployment,
+  AgentDeploymentTransition,
+  // Sample-extension surface — user-authored agents
+  // (`POST /v1/host/sample/agents`) + agent-pack registry browser
+  // (`GET/POST /v1/host/sample/registry/agent-packs`). Non-normative;
+  // wraps host-extension routes the sample app authors against.
+  CreateUserAgentRequest,
+  UserAgentRecord,
+  AgentPackSummary,
+  AgentPackRegistryResponse,
+  InstallAgentPackRequest,
+  InstallAgentPackResponse,
 } from './types.js';
 export { streamEvents } from './sse.js';
 export type { EventsStreamContext, EventsStreamOptions } from './sse.js';

package/src/types.ts

@@ -125,7 +125,12 @@ export interface RunConfigurable {
 }
 
 export interface CreateRunRequest {
-  workflowId: string;
+  /**
+   * The workflow to run. Required for a normal run; OMITTED for an eval run
+   * (`mode: 'eval'`), which targets `agentId` + `evalSuiteRef` instead
+   * (RFC 0081 §B). The server enforces the conditional requirement.
+   */
+  workflowId?: string;
   inputs?: Record<string, unknown>;
   tenantId?: string;
   scopeId?: string;
@@ -133,6 +138,12 @@ export interface CreateRunRequest {
   configurable?: RunConfigurable;
   tags?: readonly string[];
   metadata?: Record<string, unknown>;
+  /** RFC 0081 §B. `'eval'` makes this run an eval-suite projection (see `evalSuiteRef` + `agentId`). Omit for a normal workflow run. */
+  mode?: 'eval';
+  /** RFC 0081. URI of the `AgentEvalSuite` to run. Required when `mode === 'eval'`. */
+  evalSuiteRef?: string;
+  /** RFC 0081. The manifest agent the eval suite targets. Required when `mode === 'eval'`. */
+  agentId?: string;
 }
 
 export interface CreateRunResponse {
@@ -1054,3 +1065,266 @@ export interface AgentInventoryResponse {
   agents: AgentInventoryEntry[];
   total: number;
 }
+
+/* ── Standing agent roster + org-chart (RFC 0086 / 0087) ──────────────── */
+
+/** RFC 0086 §A — a standing agent INSTANCE: a `host:<id>` AgentRef that
+ *  references a manifest/deployment and owns a workflow portfolio. */
+export interface AgentRosterEntry {
+  rosterId: string;
+  persona: string;
+  agentRef: { agentId: string; version?: string; channel?: string };
+  workflows?: string[];
+  owner: { tenantId: string; workspaceId?: string };
+  enabled?: boolean;
+  label?: string;
+  description?: string;
+}
+
+/** Response for `GET /v1/agents/roster` (RFC 0086 §B). */
+export interface AgentRosterResponse {
+  roster: AgentRosterEntry[];
+  total: number;
+}
+
+/** RFC 0087 §A — an org-chart department (a tree node via `parentDepartmentId`). */
+export interface OrgChartDepartment {
+  departmentId: string;
+  name: string;
+  parentDepartmentId: string | null;
+  roles: { roleId: string; name: string }[];
+}
+
+/** RFC 0087 §A — an org-chart member (a roster instance placed in a dept/role). */
+export interface OrgChartMember {
+  rosterId: string;
+  departmentId: string;
+  roleId: string;
+  reportsTo: string | null;
+}
+
+/** RFC 0087 §A — the descriptive org-chart over roster members. Carries no
+ *  authority-bearing field by design (§B `org-position-no-authority-escalation`). */
+export interface AgentOrgChart {
+  owner: { tenantId: string; workspaceId?: string };
+  departments: OrgChartDepartment[];
+  members: OrgChartMember[];
+}
+
+/** Response for `GET /v1/agents/org-chart/{departmentId}` (RFC 0087 §D) — the
+ *  department subtree + the responsibility roll-up (union of member portfolios). */
+export interface OrgChartResponsibilityView {
+  department: OrgChartDepartment;
+  members: OrgChartMember[];
+  responsibilities: string[];
+}
+
+/* ── User-authored agents (sample-extension; non-normative) ─────────────
+ * Backs the workflow-engine sample app's Agents tab. Pack-installed
+ * agents come through `AgentInventoryEntry` above (RFC 0072 §A
+ * normative inventory). The types below mirror the sample-host
+ * `POST /v1/host/sample/agents` create surface — they're scoped to
+ * the sample-extension and may evolve independently of the
+ * normative agent surface. Future RFC promotion would migrate these
+ * to the normative wire shape.
+ */
+
+/** Body for `POST /v1/host/sample/agents`. The server synthesises
+ *  the agentId as `user.<tenantId>.<persona-slug>`. */
+export interface CreateUserAgentRequest {
+  /** Short name; becomes the `@`-mention slug and chat panel label.
+   *  Required, ≤64 chars. */
+  persona: string;
+  /** Longer display name; defaults to the persona when omitted. */
+  label?: string;
+  description?: string;
+  /** One of: `chat`, `reasoning`, `coding`, `extraction`. */
+  modelClass: string;
+  /** Inline system prompt body; ≤16 000 chars. The sample-host stores
+   *  it directly (no pack-file ref). */
+  systemPrompt: string;
+  /** Capability ids the agent is allowed to call; ≤32 entries. */
+  toolAllowlist?: string[];
+  memoryShape?: {
+    scratchpad?: boolean;
+    conversation?: boolean;
+    longTerm?: boolean;
+  };
+  /** 0.0-1.0; decisions below this are surfaced as low-confidence. */
+  confidenceThreshold?: number;
+}
+
+/** Response body for `POST /v1/host/sample/agents` — shaped to
+ *  match `AgentInventoryEntry` minus normative-only fields, so a
+ *  follow-up `GET /v1/agents` returns a row of the same shape. */
+export interface UserAgentRecord {
+  agentId: string;
+  persona: string;
+  label: string;
+  description?: string;
+  modelClass: string;
+  packName: string;
+  packVersion: string;
+  toolAllowlist: string[];
+  memoryShape: {
+    scratchpad: boolean;
+    conversation: boolean;
+    longTerm: boolean;
+  };
+  confidenceThreshold?: number;
+  hasHandoffSchemas: false;
+}
+
+/** One installable agent-pack summary from the sample host's local
+ *  registry mirror (`GET /v1/host/sample/registry/agent-packs`). */
+export interface AgentPackSummary {
+  /** Pack name, e.g. `core.openwop.agents.code-reviewer`. */
+  name: string;
+  version: string;
+  description?: string;
+  /** Personas declared by the pack's `agents[]` (per RFC 0003). */
+  personas: string[];
+  /** True when at least one of the pack's agents is registered in
+   *  this host's in-process AgentRegistry. */
+  installed: boolean;
+}
+
+export interface AgentPackRegistryResponse {
+  packs: AgentPackSummary[];
+  total: number;
+}
+
+export interface InstallAgentPackRequest {
+  /** Must start with `core.openwop.agents.` — the sample's install
+   *  route filters to that namespace. */
+  name: string;
+  /** Defaults to `1.0.0` when omitted. */
+  version?: string;
+}
+
+export interface InstallAgentPackResponse {
+  name: string;
+  version: string;
+  /** True when the pack was newly installed; false when it was
+   *  already present in the registry. */
+  installed: boolean;
+  alreadyInstalled: boolean;
+}
+
+// ── RFC 0081 — Agent evaluation (eval-summary.schema.json) ─────────────
+
+/** Abstract model class (RFC 0002 / RFC 0003 manifest vocabulary). */
+export type AgentModelClass =
+  | 'reasoning'
+  | 'writing'
+  | 'coding'
+  | 'research'
+  | 'classification'
+  | 'general';
+
+/** A redaction-safe safety finding ({kind, severity} descriptor — never excerpted content). */
+export interface EvalSafetyFinding {
+  kind: string;
+  severity: 'low' | 'medium' | 'high' | 'critical';
+}
+
+/** Per-task result on an `EvalSummary` (content-free: scores + scalars + ids). */
+export interface EvalTaskResult {
+  taskId: string;
+  score: number;
+  passed: boolean;
+  costUsd?: number;
+  latencyMs?: number;
+  schemaValid?: boolean;
+  safetyFindings?: readonly EvalSafetyFinding[];
+}
+
+/** The regression block on an `EvalSummary` (RFC 0081 §D `regression` mode). */
+export interface EvalRegression {
+  baselineRunId: string;
+  scoreDelta: number;
+  diffRef?: string;
+}
+
+/**
+ * RFC 0081 §C — the terminal scorecard of an eval run, read via
+ * `client.runs.evalSummary(runId)`. Content-free: scores, scalars, ids, and
+ * redaction-safe safety descriptors only (`eval-summary-no-content-leak`).
+ */
+export interface EvalSummary {
+  suiteId: string;
+  suiteVersion: string;
+  evaluatedModelClass?: AgentModelClass;
+  aggregateScore: number;
+  passed: boolean;
+  taskCount: number;
+  passedCount: number;
+  totalCostUsd?: number;
+  tasks: readonly EvalTaskResult[];
+  regression?: EvalRegression;
+}
+
+// ── RFC 0082 — Agent deployment lifecycle ─────────────────────────────
+
+/** The seven-state deployment lifecycle (RFC 0082 §C). */
+export type DeploymentState =
+  | 'draft'
+  | 'test'
+  | 'staged'
+  | 'active'
+  | 'paused'
+  | 'deprecated'
+  | 'rolled-back';
+
+/**
+ * RFC 0078 §B — a portable tool descriptor as projected onto the host's
+ * `GET /v1/tools` catalog. Source-agnostic (node-pack / workflow / mcp /
+ * connector / host-extension); `safetyTier`, `egress`, and `approval` let a
+ * caller reason about a tool's blast radius before invoking it.
+ */
+export interface ToolDescriptor {
+  toolId: string;
+  source: 'node-pack' | 'workflow' | 'mcp' | 'connector' | 'host-extension';
+  title?: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+  auth?: Record<string, unknown>;
+  egress?: 'none' | 'safe-fetch' | 'host-mediated' | 'host-owned';
+  approval?: 'never' | 'conditional' | 'always';
+  replayPolicy?: 'deterministic' | 'idempotent' | 'non-deterministic';
+  safetyTier: 'pure' | 'read' | 'write' | 'exec';
+  costHint?: string;
+  latencyHint?: string;
+}
+
+/**
+ * RFC 0082 §C — a per-(agentId, version) deployment record, returned by
+ * `client.agents.listDeployments` / `transitionDeployment`. Host-runtime state
+ * distinct from the immutable manifest and the registry's published tags.
+ */
+export interface AgentDeployment {
+  agentId: string;
+  version: string;
+  state: DeploymentState;
+  canaryPercent?: number;
+  rollbackPointer?: string;
+  channels?: readonly string[];
+  evalRunId?: string;
+  approvalGateId?: string;
+}
+
+/**
+ * RFC 0082 §E — the `transitionDeployment` request body. The host authorizes it
+ * fail-closed (RFC 0049 `deploy:*`), runs any RFC 0051 approvalGate, and enforces
+ * RFC 0081 `requiredEval` before emitting `deployment.promoted`.
+ */
+export interface AgentDeploymentTransition {
+  version: string;
+  transition: 'promote' | 'pause' | 'deprecate' | 'rollback' | 'adjust-canary';
+  toState?: DeploymentState;
+  channel?: string;
+  canaryPercent?: number;
+  evalRunId?: string;
+  reason?: string;
+}