@openwop/openwop-conformance 1.6.1 → 1.11.0

package/api/openapi.yaml

@@ -51,6 +51,8 @@ tags:
     description: Workflow definition manifest.
   - name: runs
     description: Run lifecycle — create, read, stream, cancel, fork.
+  - name: agents
+    description: Manifest-agent inventory (RFC 0072 §A). Read-only; gated on capabilities.agents.manifestRuntime. Dispatch rides the run surface (WorkflowNode.agent + POST /v1/runs).
   - name: hitl
     description: Human-in-the-loop interrupts and approvals.
   - name: artifacts
@@ -61,6 +63,8 @@ tags:
     description: Audit-log integrity verification (gated on the `openwop-audit-log-integrity` profile).
   - name: prompts
     description: Prompt-template library — list, fetch, render, mutate (RFC 0028; gated on `capabilities.prompts.*`).
+  - name: host
+    description: Host-capability resources — e.g. the RFC 0059 agent workspace file store (gated on `capabilities.workspace.*`).
   - name: packs-test
     description: |
       RFC 0025 (`Draft`). Test-mode mirror of the production `/v1/packs/*` publish/get/delete/sig surface against
@@ -175,7 +179,6 @@ paths:
               # so callers see one unified body shape.
               allOf:
                 - type: object
-                  required: [workflowId]
                   properties:
                     workflowId: { type: string, minLength: 1 }
                     inputs:
@@ -191,7 +194,33 @@ paths:
                       type: string
                       format: uri
                       description: Signed-token HITL callback URL (see `interrupt.md`).
+                    mode:
+                      type: string
+                      enum: [eval]
+                      description: |
+                        RFC 0081 §B. When `eval`, this run is an eval-suite projection
+                        (not a workflow run): the host runs the `evalSuiteRef` against
+                        `agentId`, emits the content-free `eval.*` family, and terminates
+                        with an `EvalSummary` readable via `GET /v1/runs/{runId}/eval-summary`.
+                        Capability-gated on `capabilities.agents.evalSuite.supported`; a
+                        host that omits it rejects `mode: "eval"` with 501. Omit for a
+                        normal workflow run.
+                    evalSuiteRef:
+                      type: string
+                      minLength: 1
+                      description: RFC 0081 — URI of the `AgentEvalSuite` to run. Required when mode is `eval`.
+                    agentId:
+                      type: string
+                      minLength: 1
+                      description: RFC 0081 — the manifest agent the eval suite targets. Required when mode is `eval`.
                   additionalProperties: false
+                  if:
+                    properties: { mode: { const: eval } }
+                    required: [mode]
+                  then:
+                    required: [evalSuiteRef, agentId]
+                  else:
+                    required: [workflowId]
                 - $ref: '../schemas/run-options.schema.json'
       responses:
         '201':
@@ -427,6 +456,146 @@ paths:
               schema:
                 $ref: '../schemas/error-envelope.schema.json'
 
+  # ── Agent workspace files (RFC 0059) ─────────────────────────────────
+  # Gated on `capabilities.workspace.supported: true`. A versioned,
+  # tenant·workspace-scoped (RFC 0048) ground-truth file store with atomic,
+  # optimistically-concurrent (`If-Match`) writes. A successful PUT/DELETE
+  # emits a content-free `workspace.updated` event. Hosts without the
+  # advertised capability return `501 capability_not_provided`.
+  /v1/host/workspace/files:
+    get:
+      tags: [host]
+      summary: List workspace file metadata for the caller's tenant·workspace (RFC 0059).
+      description: |
+        Returns file metadata (no bodies) for the caller's `{tenant,
+        workspace}` per RFC 0059 §C. Optional `?prefix=` filters the flat
+        `path` namespace to entries starting with the given prefix.
+      operationId: listWorkspaceFiles
+      parameters:
+        - $ref: '#/components/parameters/WorkspacePrefix'
+      responses:
+        '200':
+          description: Workspace file metadata (tenant·workspace-scoped; bodies omitted).
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [files]
+                properties:
+                  files:
+                    type: array
+                    items:
+                      $ref: '../schemas/workspace-file.schema.json'
+                additionalProperties: false
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '501':
+          description: 'Host does not advertise capabilities.workspace.supported (RFC 0059).'
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/error-envelope.schema.json'
+
+  /v1/host/workspace/files/{path}:
+    get:
+      tags: [host]
+      summary: Read one workspace file (RFC 0059).
+      description: |
+        Returns the `WorkspaceFile` at `path` for the caller's `{tenant,
+        workspace}`. When `capabilities.workspace.versioned: true`, an
+        optional `?version=N` returns the historical snapshot at version N.
+      operationId: getWorkspaceFile
+      parameters:
+        - $ref: '#/components/parameters/WorkspacePath'
+        - $ref: '#/components/parameters/WorkspaceVersion'
+      responses:
+        '200':
+          description: The workspace file (current version, or `?version=N` when versioned).
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/workspace-file.schema.json'
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501':
+          description: 'Host does not advertise capabilities.workspace.supported (RFC 0059).'
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/error-envelope.schema.json'
+    put:
+      tags: [host]
+      summary: Atomic create/replace of a workspace file (RFC 0059).
+      description: |
+        Atomically creates or replaces the file at `path` per RFC 0059 §C.
+        MUST honor `If-Match: <etag>` — a stale token returns `409
+        workspace_conflict` (`details.currentVersion` carries the live
+        version). On success the host bumps `version`, recomputes `etag`,
+        and emits a `workspace.updated` event. A `content` exceeding
+        `capabilities.workspace.maxFileBytes` returns `workspace_too_large`.
+      operationId: putWorkspaceFile
+      parameters:
+        - $ref: '#/components/parameters/WorkspacePath'
+        - $ref: '#/components/parameters/IfMatch'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../schemas/workspace-file-create.schema.json'
+      responses:
+        '200':
+          description: File created or replaced. Returns the persisted WorkspaceFile.
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/workspace-file.schema.json'
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '409':
+          description: 'Stale `If-Match` — the file changed since the supplied etag (`workspace_conflict`).'
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/error-envelope.schema.json'
+        '413':
+          description: 'Content exceeds `capabilities.workspace.maxFileBytes` (`workspace_too_large`).'
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/error-envelope.schema.json'
+        '501':
+          description: 'Host does not advertise capabilities.workspace.supported (RFC 0059).'
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/error-envelope.schema.json'
+    delete:
+      tags: [host]
+      summary: Delete a workspace file (RFC 0059).
+      description: |
+        Removes the file at `path` (and, when `versioned: true`, writes a
+        tombstone). Emits a `workspace.updated` event on success.
+      operationId: deleteWorkspaceFile
+      parameters:
+        - $ref: '#/components/parameters/WorkspacePath'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      responses:
+        '204':
+          description: File deleted.
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501':
+          description: 'Host does not advertise capabilities.workspace.supported (RFC 0059).'
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/error-envelope.schema.json'
+
   /v1/runs:bulk-cancel:
     post:
       tags: [runs]
@@ -575,6 +744,317 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/Error' }
 
+  /v1/agents:
+    get:
+      tags: [agents]
+      summary: |
+        RFC 0072 §A — list the manifest agents this host has installed into its
+        AgentRegistry (RFC 0070). Capability-gated on
+        `capabilities.agents.manifestRuntime.supported: true`; hosts that don't
+        advertise it return 404. Read-only projection — never carries the
+        system-prompt body, resolved handoff schemas, or credential material (SR-1).
+        Dispatch is not a bespoke endpoint: a manifest agent is invoked as a run
+        whose node pins it via `WorkflowNode.agent` + `POST /v1/runs` (RFC 0072 §B).
+        RFC 0074 — the result is scoped to the authenticated principal's owner
+        triple (RFC 0048). When `capabilities.agents.manifestRuntime.installScope`
+        is `'tenant'`, only the agents available to the caller's tenant·workspace
+        are returned (an agent another workspace installed is absent, never
+        disclosed); when `'host'` (default) the inventory is host-global as in
+        RFC 0072. A `'tenant'`-scoped host MUST reject unauthenticated/unscoped
+        requests per its standard auth contract rather than fall back to a global list.
+      operationId: listAgents
+      responses:
+        '200':
+          description: Installed manifest agents (agentId-sorted).
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/agent-inventory-response.schema.json'
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404':
+          description: |
+            Host does not advertise `capabilities.agents.manifestRuntime` and
+            treats the endpoint as absent.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+
+  /v1/agents/{agentId}:
+    get:
+      tags: [agents]
+      summary: |
+        RFC 0072 §A — return one installed manifest agent's inventory entry, or
+        404 when no such agent is installed (or the host doesn't advertise
+        `capabilities.agents.manifestRuntime`). RFC 0074 — resolved within the
+        authenticated principal's owner triple (RFC 0048): on an
+        `installScope: 'tenant'` host an agent the caller's workspace has not
+        approved 404s identically to "not installed", so the surface never
+        discloses another tenant's inventory.
+      operationId: getAgent
+      parameters:
+        - in: path
+          name: agentId
+          required: true
+          schema: { type: string }
+          description: The manifest agentId.
+      responses:
+        '200':
+          description: The agent's inventory entry.
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/agent-inventory-response.schema.json#/$defs/AgentInventoryEntry'
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404':
+          description: No such agent, or the host doesn't advertise the capability.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+
+  /v1/agents/{agentId}/deployments:
+    get:
+      tags: [agents]
+      summary: |
+        RFC 0082 §C/§E — list the deployment records (per-(agentId, version)) for
+        a manifest agent: the lifecycle `state`, the named `channels`, the canary
+        share, the rollback pointer, and the last-transition provenance. Read-only,
+        content-free of any manifest body or credential (SR-1). Capability-gated on
+        `capabilities.agents.deployment.supported: true`; hosts that don't advertise
+        it return 404. Tenant-scoped to the caller's owner triple (RFC 0048/0074)
+        when `installScope: 'tenant'`.
+      operationId: listAgentDeployments
+      parameters:
+        - in: path
+          name: agentId
+          required: true
+          schema: { type: string }
+          description: The manifest agentId.
+      responses:
+        '200':
+          description: The agent's deployment records (version-sorted).
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: '../schemas/agent-deployment.schema.json' }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404':
+          description: No such agent, or the host doesn't advertise `capabilities.agents.deployment`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+    post:
+      tags: [agents]
+      summary: |
+        RFC 0082 §E — request a deployment state transition (promote / pause /
+        deprecate / rollback / adjust-canary). The host MUST authorize fail-closed
+        against the RFC 0049 `deploy:*` scope (absent/unseeded role denies), run any
+        configured RFC 0051 approvalGate, and — when the gate carries `requiredEval`
+        — verify the referenced RFC 0081 eval run is terminal and `EvalSummary.passed`
+        BEFORE emitting `deployment.promoted`. On success returns the updated
+        deployment record and emits the matching content-free `deployment.*` event.
+      operationId: transitionAgentDeployment
+      parameters:
+        - in: path
+          name: agentId
+          required: true
+          schema: { type: string }
+          description: The manifest agentId.
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '../schemas/agent-deployment-transition.schema.json'
+      responses:
+        '200':
+          description: The deployment record after the applied transition.
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/agent-deployment.schema.json'
+        '400':
+          description: |
+            Validation error, or a transition that the host's advertised
+            `states`/`canary` cannot satisfy, or `no_active_deployment` when a
+            referenced channel resolves to no active version.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403':
+          description: |
+            Fail-closed authorization denial (the principal lacks the required
+            `deploy:*` scope — RFC 0049), or `eval_gate_unmet` when a `requiredEval`
+            gate's referenced eval run is not terminal-and-passed (RFC 0081).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+        '404':
+          description: No such agent, or the host doesn't advertise `capabilities.agents.deployment`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+
+  /v1/agents/roster:
+    get:
+      tags: [agents]
+      summary: |
+        RFC 0086 §B — list the standing agent roster (named "digital-twin
+        employee" instances + their workflow portfolios) visible to the
+        caller. Capability-gated on `capabilities.agents.roster.supported:
+        true`; hosts that don't advertise it return 404. Tenant-scoped per
+        RFC 0074 — on an `installScope: 'tenant'` host only the caller's
+        owner-triple entries are returned. Read-only; content-free (SR-1).
+      operationId: listAgentRoster
+      responses:
+        '200':
+          description: The caller's standing roster (rosterId-sorted).
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/agent-roster-response.schema.json'
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404':
+          description: Host does not advertise `capabilities.agents.roster`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+
+  /v1/agents/roster/{rosterId}:
+    get:
+      tags: [agents]
+      summary: |
+        RFC 0086 §B — return one standing roster entry, or 404 when no such
+        entry exists, the host doesn't advertise `capabilities.agents.roster`,
+        or (on an `installScope: 'tenant'` host) the entry is outside the
+        caller's owner triple — a cross-tenant entry 404s identically to
+        "not found", never disclosing another tenant's roster.
+      operationId: getAgentRosterEntry
+      parameters:
+        - in: path
+          name: rosterId
+          required: true
+          schema: { type: string }
+          description: The standing instance id (a `host:<id>` AgentRef agentId).
+      responses:
+        '200':
+          description: The roster entry.
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/agent-roster-entry.schema.json'
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404':
+          description: No such entry, cross-tenant, or capability unadvertised.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+
+  /v1/agents/org-chart:
+    get:
+      tags: [agents]
+      summary: |
+        RFC 0087 §C — return the caller's agent org-chart (departments + roles
+        + `reportsTo` edges over roster members). Capability-gated on
+        `capabilities.agents.orgChart.supported: true`; hosts that don't
+        advertise it return 404. Tenant-scoped per RFC 0074. DESCRIPTIVE only:
+        an org edge confers no authority (§B `org-position-no-authority-escalation`).
+      operationId: getAgentOrgChart
+      responses:
+        '200':
+          description: The caller's org-chart.
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/agent-org-chart.schema.json'
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404':
+          description: Host does not advertise `capabilities.agents.orgChart`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+
+  /v1/agents/org-chart/{departmentId}:
+    get:
+      tags: [agents]
+      summary: |
+        RFC 0087 §D — one department's subtree + responsibility roll-up (the
+        union of its members' RFC 0086 portfolios). `?recursive=false` narrows
+        the roll-up to direct members without changing the response shape.
+        404 when the department is unknown, cross-tenant, or the host doesn't
+        advertise `capabilities.agents.orgChart`. The roll-up grants nothing (§B).
+      operationId: getAgentOrgChartDepartment
+      parameters:
+        - in: path
+          name: departmentId
+          required: true
+          schema: { type: string }
+          description: The department id to root the subtree + roll-up at.
+        - in: query
+          name: recursive
+          required: false
+          schema: { type: boolean, default: true }
+          description: When `false`, the roll-up scopes to direct members only.
+      responses:
+        '200':
+          description: The department subtree + responsibility roll-up.
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/org-chart-responsibility-view.schema.json'
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404':
+          description: Unknown/cross-tenant department, or capability unadvertised.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+
+  /v1/runs/{runId}/eval-summary:
+    get:
+      tags: [runs]
+      summary: |
+        RFC 0081 §C — return the `EvalSummary` scorecard for a terminal eval run
+        (a run started with `mode: "eval"`): aggregate + per-task scores, cost,
+        latency, schema-validity, and redaction-safe safety findings, plus the
+        suite provenance and (regression mode) the score delta vs a baseline.
+        Content-free of task output / rubric prose / credentials (SR-1; the
+        `eval-summary-no-content-leak` invariant). Capability-gated on
+        `capabilities.agents.evalSuite.supported: true`; hosts that don't advertise
+        it return 404. 409 when the run is not yet terminal.
+      operationId: getEvalSummary
+      parameters:
+        - $ref: '#/components/parameters/RunId'
+      responses:
+        '200':
+          description: The eval run's scorecard.
+          content:
+            application/json:
+              schema:
+                $ref: '../schemas/eval-summary.schema.json'
+        '401': { $ref: '#/components/responses/Unauthenticated' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404':
+          description: |
+            No such run, the run is not an eval run, or the host doesn't advertise
+            `capabilities.agents.evalSuite`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+        '409':
+          description: The eval run is still running; the summary is not yet final.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+
   /v1/runs/{runId}:diff:
     get:
       tags: [runs]
@@ -1513,6 +1993,43 @@ components:
         Duplicate requests return the cached response with header
         `openwop-Idempotent-Replay: true`.
 
+    WorkspacePath:
+      in: path
+      name: path
+      required: true
+      schema:
+        type: string
+        pattern: '^[A-Za-z0-9][A-Za-z0-9._/-]{0,255}$'
+      description: |
+        RFC 0059 workspace-relative file path. Flat namespace with
+        `/`-in-names; no `..`, no leading `/`. Matches
+        `workspace-file.schema.json#path`.
+
+    WorkspacePrefix:
+      in: query
+      name: prefix
+      required: false
+      schema: { type: string, maxLength: 256 }
+      description: RFC 0059. Optional prefix filter over the flat `path` namespace for `listWorkspaceFiles`.
+
+    WorkspaceVersion:
+      in: query
+      name: version
+      required: false
+      schema: { type: integer, minimum: 1 }
+      description: |
+        RFC 0059. When `capabilities.workspace.versioned: true`, request the
+        historical snapshot at this version. Absent = latest.
+
+    IfMatch:
+      in: header
+      name: If-Match
+      required: false
+      schema: { type: string, maxLength: 255 }
+      description: |
+        RFC 0059 optimistic-concurrency token — the file's current `etag`.
+        A `PUT` carrying a stale `If-Match` returns `409 workspace_conflict`.
+
     PackName:
       in: path
       name: name