diff --git a/.agents/skills/sync-openapi-spec/references/sync-policy.md b/.agents/skills/sync-openapi-spec/references/sync-policy.md
index a4fb5d3ed..9d9b02b48 100644
--- a/.agents/skills/sync-openapi-spec/references/sync-policy.md
+++ b/.agents/skills/sync-openapi-spec/references/sync-policy.md
@@ -8,7 +8,7 @@ This document records what `developers/agent-api-openapi.yaml` keeps from `warp-
 
 1. Drop every tag listed in `EXCLUDED_TAGS`.
 2. Drop every path whose tags are a subset of `EXCLUDED_TAGS`, plus every path listed explicitly in `EXCLUDED_PATHS`.
-3. Keep every surviving path verbatim, including any `x-internal: true` markers on its operations.
+3. Strip any individual operation marked `x-internal: true` from surviving paths. A path whose every HTTP operation is marked internal is dropped entirely.
 4. Keep top-level `openapi`, `info`, `servers`, and `components.securitySchemes` verbatim.
 5. Keep only the `components.schemas` entries that are reachable from the surviving paths via `$ref` walking (recursive over `allOf`/`oneOf`/`anyOf`/`items`/`additionalProperties`/etc.).
 
@@ -20,20 +20,34 @@ Memory stores are gated as `x-internal: true` server-side. They are not part of
 ### `harness-support`
 The `/harness-support/*` endpoints form the worker-to-server contract used by Oz workers (transcripts, snapshots, finish-task signaling, etc.). They are not part of the public API contract — customers should not call them directly. Excluded permanently.
 
+### `factory`
+The `/factory/*` endpoints are the internal agent-orchestration API used by the factory pipeline (task management, Linear integrations, syncs, etc.). Not a public API surface; excluded until further notice.
+
+### `memory`
+The `/memory_stores` path is tagged `memory` in the server spec (renamed from the former `memory_stores` tag). Same rationale as `memory_stores` above: memory stores are gated and not a stable public API yet.
+
 ## Excluded paths (within otherwise-public tags)
 
-These four `agent`-tag paths are excluded individually because the `agent` tag itself remains public:
+These paths under otherwise-public tags are excluded individually:
 
 - `/agent/runs/{runId}/handoff/attachments` — handoff plumbing tied to local-to-cloud session handoff.
 - `/agent/handoff/upload-snapshot` — handoff plumbing (snapshot upload from a local worker).
 - `/agent/conversations/{conversation_id}/fork` — conversation-forking primitive used by the harness, not stable public API.
 - `/agent/conversations/{conversationId}/redirect` — internal redirect endpoint.
+- `/factory/scorers` — factory-internal scorer creation endpoint; carries the `agent` tag but is not a public API surface.
+- `/factory/scorers/{scorer_id}/results` — factory-internal scorer results endpoint; carries the `agent` tag but is not a public API surface.
+- `/agent/sessions/{sessionUuid}/redirect` — session redirect plumbing (mirrors the excluded `/agent/conversations/{conversationId}/redirect`).
+- `/agent/runs/{runId}/client-events` — internal telemetry endpoint for recording run client events; not a stable public API contract.
 
 If any of these become stable public surfaces, remove them from `EXCLUDED_PATHS` and update this list.
 
-## What we deliberately KEEP that you might expect to be hidden
+## What the script filters that you might expect to be public
+
+The script now strips individual operations marked `x-internal: true`, even when the operation lives under an otherwise-public path. This prevents internal inter-agent plumbing (the `/agent/messages/*` and `/agent/events/*` inter-agent messaging and event-polling operations, `/agent/conversations/{conversation_id}/rename`, etc.) from appearing in the public docs reference and `public/openapi.json`. These operations exist server-side but are not part of the stable customer-facing API contract. If an operation is promoted to public, remove its `x-internal: true` marker in `warp-server/public_api/openapi.yaml` and the next sync will include it automatically.
+
+The script also strips parameters and schema properties individually marked `x-internal: true`. This removes internal fields (such as `factory_uid` on `GET /agent/identities` and factory-specific fields on agent request/response schemas) without hiding the entire endpoint or schema. Schemas that were only reachable via stripped properties are also pruned by the existing `$ref` reachability pass.
 
-The script keeps `x-internal: true` operations under public paths. Today this means the `/agent/messages/*` and `/agent/events/*` operations are present in the docs file even though they're flagged `x-internal` in the source. This matches the pre-existing state of `developers/agent-api-openapi.yaml` and the way Scalar already renders the reference. If we want to start stripping `x-internal` operations from the docs spec, change the policy here and update `_should_keep_path`/the operation-level filter in `scripts/sync_openapi.py`.
+> **Merge-ordering note (delete once warp-server#13429 lands):** Running `--mode diff` or `--mode apply` against `warp-server develop` will report drift on the `computer_use_enabled` description until warp-server#13429 merges. Always source from that branch (or from `develop` after it merges) to keep the published description in sync.
 
 ## Adding a new exclusion
 
diff --git a/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py b/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py
index 345ee5dcc..638a52655 100644
--- a/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py
+++ b/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py
@@ -8,10 +8,15 @@
 This script generates the docs subset deterministically:
   * tags listed in EXCLUDED_TAGS are removed (and their paths/schemas)
   * paths listed in EXCLUDED_PATHS are removed
-  * surviving paths and operations are kept verbatim, including any
-    ``x-internal: true`` markers
+  * individual operations marked ``x-internal: true`` are stripped;
+    a path whose every operation is internal is removed entirely
+  * parameters marked ``x-internal: true`` are stripped from path-level
+    and operation-level parameter lists
+  * schema properties marked ``x-internal: true`` are stripped from every
+    surviving schema's ``properties`` map (and removed from ``required``)
   * components/schemas is pruned to only schemas reachable from the
-    surviving paths via $ref walking
+    surviving paths via $ref walking (using the stripped schemas, so
+    schemas only referenced via stripped properties are also pruned)
   * the regenerated spec is validated for unresolved $refs before
     being written; apply will refuse to write a broken spec
 
@@ -38,10 +43,17 @@
 
 import yaml
 
+# HTTP methods that identify operations within an OpenAPI path item.
+_HTTP_METHODS: frozenset[str] = frozenset(
+    {"get", "put", "post", "delete", "options", "head", "patch", "trace"}
+)
+
 # Tags whose paths and tag entry should be removed entirely.
 # `memory_stores` is gated as `x-internal` server-side.
 # `harness-support` is the worker-to-server contract — not a public API.
-EXCLUDED_TAGS: frozenset[str] = frozenset({"memory_stores", "harness-support"})
+# `factory` is the internal agent-orchestration API — not a public API.
+# `memory` is the memory-stores tag (renamed from `memory_stores`) — not public yet.
+EXCLUDED_TAGS: frozenset[str] = frozenset({"memory_stores", "harness-support", "factory", "memory"})
 
 # Specific paths under otherwise-public tags that should be hidden from
 # the public API reference. Keep in sync with references/sync-policy.md.
@@ -51,6 +63,12 @@
         "/agent/handoff/upload-snapshot",
         "/agent/conversations/{conversation_id}/fork",
         "/agent/conversations/{conversationId}/redirect",
+        # factory-scorer paths are factory-internal but carry the `agent` tag
+        "/factory/scorers",
+        "/factory/scorers/{scorer_id}/results",
+        # internal agent plumbing not part of the stable public API contract
+        "/agent/sessions/{sessionUuid}/redirect",
+        "/agent/runs/{runId}/client-events",
     }
 )
 
@@ -133,6 +151,82 @@ def _should_keep_path(path: str, path_item: dict[str, Any]) -> bool:
     return True
 
 
+def _strip_internal_parameters(parameters: Any) -> list[Any]:
+    """Return a copy of *parameters* with any ``x-internal: true`` entries removed.
+
+    ``parameters`` is expected to be an OpenAPI ``parameters`` list (each
+    entry is either a parameter object or a ``$ref``). Non-list inputs are
+    returned as-is so callers can unconditionally reassign the key.
+    """
+    if not isinstance(parameters, list):
+        return parameters
+    return [p for p in parameters if not (isinstance(p, dict) and p.get("x-internal"))]
+
+
+def _strip_internal_properties(schema: dict[str, Any]) -> dict[str, Any]:
+    """Return a copy of *schema* with any ``x-internal: true`` properties removed.
+
+    Also removes the corresponding entries from the ``required`` list so the
+    schema remains internally consistent. When no properties are stripped the
+    original dict is returned unchanged (no copy).
+    """
+    props = schema.get("properties")
+    if not isinstance(props, dict):
+        return schema
+    stripped_keys = {
+        k for k, v in props.items() if isinstance(v, dict) and v.get("x-internal")
+    }
+    if not stripped_keys:
+        return schema
+    out = dict(schema)
+    out["properties"] = {k: v for k, v in props.items() if k not in stripped_keys}
+    if "required" in schema and isinstance(schema["required"], list):
+        new_required = [r for r in schema["required"] if r not in stripped_keys]
+        out["required"] = new_required  # may be empty — valid OpenAPI
+    return out
+
+
+def _filter_internal_operations(path_item: dict[str, Any]) -> dict[str, Any]:
+    """Return a copy of *path_item* with any ``x-internal: true`` operations removed.
+
+    Also strips ``x-internal: true`` entries from the path-level
+    ``parameters`` list and from each operation's own ``parameters`` list.
+    Non-operation, non-parameters keys (``summary``, ``description``, etc.)
+    are preserved verbatim. Returns a dict that may have zero operations if
+    every HTTP method was marked internal; callers should check
+    ``_has_operations`` before including the result.
+    """
+    out: dict[str, Any] = {}
+    for key, value in path_item.items():
+        if key in _HTTP_METHODS:
+            # Drop this operation if it carries x-internal: true.
+            if isinstance(value, dict) and value.get("x-internal"):
+                continue
+            # Strip x-internal parameters from operation-level parameters list.
+            if isinstance(value, dict) and "parameters" in value:
+                stripped = _strip_internal_parameters(value["parameters"])
+                if stripped != value["parameters"]:
+                    value = dict(value)
+                    if stripped:
+                        value["parameters"] = stripped
+                    else:
+                        del value["parameters"]
+            out[key] = value
+        elif key == "parameters":
+            # Strip x-internal parameters from the path-level parameters list.
+            stripped = _strip_internal_parameters(value)
+            if stripped:  # omit the key entirely when all parameters are stripped
+                out[key] = stripped
+        else:
+            out[key] = value
+    return out
+
+
+def _has_operations(path_item: dict[str, Any]) -> bool:
+    """Return True if *path_item* contains at least one HTTP operation."""
+    return any(key in _HTTP_METHODS for key in path_item)
+
+
 def _collect_refs(node: Any, refs: set[str]) -> None:
     """Recursively collect every component schema name referenced from ``node``.
 
@@ -239,11 +333,13 @@ def transform(source: dict[str, Any]) -> dict[str, Any]:
         out["tags"] = out_tags
 
     src_paths = source.get("paths") or {}
-    kept_paths = {
-        path: item
-        for path, item in src_paths.items()
-        if isinstance(item, dict) and _should_keep_path(path, item)
-    }
+    kept_paths: dict[str, Any] = {}
+    for path, item in src_paths.items():
+        if not isinstance(item, dict) or not _should_keep_path(path, item):
+            continue
+        filtered = _filter_internal_operations(item)
+        if _has_operations(filtered):
+            kept_paths[path] = filtered
     out["paths"] = kept_paths
 
     seed_refs: set[str] = set()
@@ -251,14 +347,24 @@ def transform(source: dict[str, Any]) -> dict[str, Any]:
 
     src_components = source.get("components") or {}
     src_schemas = src_components.get("schemas") or {}
-    reachable = _transitive_schemas(seed_refs, src_schemas)
+
+    # Preprocess schemas to strip x-internal properties before $ref-walking.
+    # This ensures schemas that are only referenced from stripped properties
+    # (e.g. an enum type exclusively used by an internal field) are not pulled
+    # into the output by the transitive reachability pass.
+    processed_schemas: dict[str, Any] = {
+        name: _strip_internal_properties(schema)
+        for name, schema in src_schemas.items()
+    }
+
+    reachable = _transitive_schemas(seed_refs, processed_schemas)
 
     out_components: dict[str, Any] = {}
     for ck, cv in src_components.items():
         if ck == "schemas":
             out_components["schemas"] = {
-                name: src_schemas[name]
-                for name in src_schemas
+                name: processed_schemas[name]
+                for name in processed_schemas
                 if name in reachable
             }
         else:
@@ -379,9 +485,18 @@ def _self_test() -> int:
         ],
         "paths": {
             "/agent/run": {
+                # Path-level x-internal parameter (should be stripped).
+                "parameters": [
+                    {"name": "factory_uid", "in": "query", "x-internal": True},
+                    {"name": "trace", "in": "query"},
+                ],
                 "post": {
                     "tags": ["agent"],
                     "operationId": "runAgent",
+                    # Operation-level x-internal parameter (should be stripped).
+                    "parameters": [
+                        {"name": "_internal", "in": "header", "x-internal": True},
+                    ],
                     "requestBody": {
                         "content": {
                             "application/json": {
@@ -430,7 +545,13 @@ def _self_test() -> int:
                 "RunReq": {
                     "type": "object",
                     "properties": {
-                        "config": {"$ref": "#/components/schemas/Config"}
+                        "config": {"$ref": "#/components/schemas/Config"},
+                        # x-internal property referencing InternalOnly schema;
+                        # both the property and InternalOnly should be pruned.
+                        "_internal_ref": {
+                            "x-internal": True,
+                            "$ref": "#/components/schemas/InternalOnly",
+                        },
                     },
                 },
                 "Config": {
@@ -452,6 +573,8 @@ def _self_test() -> int:
                 "RunResp": {"type": "object"},
                 "MSItem": {"type": "object"},  # only referenced by dropped path
                 "Followup": {"type": "object"},
+                # Only reachable via the stripped _internal_ref property.
+                "InternalOnly": {"type": "object"},
             },
         },
     }
@@ -464,14 +587,30 @@ def _self_test() -> int:
     }, f"unexpected paths: {paths}"
 
     schemas = set(out["components"]["schemas"].keys())
-    # Config and Mode are reachable transitively (allOf, items)
+    # Config and Mode are reachable transitively (allOf, items).
+    # InternalOnly is only referenced from the stripped x-internal property and must be absent.
     assert schemas == {"RunReq", "Config", "Mode", "RunResp"}, f"unexpected schemas: {schemas}"
 
+    # RunReq should not contain the stripped x-internal property.
+    run_req_props = set(out["components"]["schemas"]["RunReq"]["properties"].keys())
+    assert "_internal_ref" not in run_req_props, f"x-internal property survived: {run_req_props}"
+
     tag_names = [t["name"] for t in out.get("tags") or []]
     assert tag_names == ["agent"], f"unexpected tags: {tag_names}"
 
     assert out["components"].get("securitySchemes"), "securitySchemes should be preserved"
 
+    # Path-level x-internal parameter must be stripped; public one must survive.
+    run_path_params = out["paths"]["/agent/run"].get("parameters", [])
+    param_names = [p.get("name") for p in run_path_params if isinstance(p, dict)]
+    assert "factory_uid" not in param_names, f"x-internal path param survived: {param_names}"
+    assert "trace" in param_names, f"public path param was stripped: {param_names}"
+
+    # Operation-level x-internal parameter must be stripped; the parameters key
+    # should be absent because all its entries were internal.
+    run_op_params = out["paths"]["/agent/run"]["post"].get("parameters")
+    assert run_op_params is None, f"stripped-only op parameters key should be absent: {run_op_params}"
+
     ref_errors = _validate_output(out)
     assert not ref_errors, f"unexpected unresolved refs: {ref_errors}"
 
diff --git a/developers/agent-api-openapi.yaml b/developers/agent-api-openapi.yaml
index 870bee047..a64d08d12 100644
--- a/developers/agent-api-openapi.yaml
+++ b/developers/agent-api-openapi.yaml
@@ -2,25 +2,21 @@ openapi: 3.0.0
 info:
   title: Oz Agent API
   version: 1.0.0
-  description: |
-    API for creating, managing, and querying Oz cloud agent runs.
-
-    These endpoints allow users to programmatically spawn agents, list runs, 
-    and retrieve detailed run information.
+  description: "API for creating, managing, and querying Oz cloud agent runs.\n\nThese endpoints allow users to programmatically spawn agents, list runs, \nand retrieve detailed run information.\n"
   contact:
     name: Warp Support
-    url: 'https://docs.warp.dev'
+    url: https://docs.warp.dev
     email: support@warp.dev
   license:
     name: Proprietary
 servers:
-  - url: 'https://app.warp.dev/api/v1'
-    description: Warp Server
+- url: https://app.warp.dev/api/v1
+  description: Warp Server
 tags:
-  - name: agent
-    description: Operations for running and managing cloud agents
-  - name: schedules
-    description: Operations for creating and managing scheduled agents
+- name: agent
+  description: Operations for running and managing cloud agents
+- name: schedules
+  description: Operations for creating and managing scheduled agents
 paths:
   /agent:
     get:
@@ -30,49 +26,49 @@ paths:
         Agents are discovered from environments or a specific repository.
       operationId: listAgents
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: repo
-          in: query
-          description: |
-            Optional repository specification to list agents from (format: "owner/repo").
-            If not provided, lists agents from all accessible environments.
-          required: false
-          schema:
-            type: string
-        - name: refresh
-          in: query
-          description: |
-            When true, clears the agent list cache before fetching.
-            Use this to force a refresh of the available agents.
-          required: false
-          schema:
-            type: boolean
-            default: false
-        - name: sort_by
-          in: query
-          description: |
-            Sort order for the returned agents.
-            - "name": Sort alphabetically by name (default)
-            - "last_run": Sort by most recently used
-          required: false
-          schema:
-            type: string
-            enum:
-              - name
-              - last_run
-        - name: include_malformed_skills
-          in: query
-          description: |
-            When true, includes skills whose SKILL.md file exists but is
-            malformed. These variants will have a non-empty `error` field
-            describing the parse failure. Defaults to false.
-          required: false
-          schema:
-            type: boolean
-            default: false
+      - name: repo
+        in: query
+        description: |
+          Optional repository specification to list agents from (format: "owner/repo").
+          If not provided, lists agents from all accessible environments.
+        required: false
+        schema:
+          type: string
+      - name: refresh
+        in: query
+        description: |
+          When true, clears the agent list cache before fetching.
+          Use this to force a refresh of the available agents.
+        required: false
+        schema:
+          type: boolean
+          default: false
+      - name: sort_by
+        in: query
+        description: |
+          Sort order for the returned agents.
+          - "name": Sort alphabetically by name (default)
+          - "last_run": Sort by most recently used
+        required: false
+        schema:
+          type: string
+          enum:
+          - name
+          - last_run
+      - name: include_malformed_skills
+        in: query
+        description: |
+          When true, includes skills whose SKILL.md file exists but is
+          malformed. These variants will have a non-empty `error` field
+          describing the parse failure. Defaults to false.
+        required: false
+        schema:
+          type: boolean
+          default: false
       responses:
         '200':
           description: List of available agents
@@ -94,9 +90,9 @@ paths:
         Worker presence is derived from worker websocket heartbeats and may be briefly stale.
       operationId: listConnectedSelfHostedWorkers
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       responses:
         '200':
           description: List of currently connected self-hosted workers
@@ -116,7 +112,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/runs/{runId}/transcript':
+  /agent/runs/{runId}/transcript:
     get:
       summary: Get run transcript
       description: |
@@ -124,16 +120,16 @@ paths:
         Returns a 302 redirect to a time-limited download URL for the transcript.
       operationId: getRunTranscript
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: runId
-          in: path
-          description: The unique identifier of the run
-          required: true
-          schema:
-            type: string
+      - name: runId
+        in: path
+        description: The unique identifier of the run
+        required: true
+        schema:
+          type: string
       responses:
         '302':
           description: Redirect to a download URL for the transcript
@@ -182,9 +178,9 @@ paths:
       operationId: runAgent
       deprecated: true
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       requestBody:
         required: true
         content:
@@ -213,7 +209,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/RunAgentResponse'
         '400':
-          description: 'Invalid request (missing prompt, invalid config)'
+          description: Invalid request (missing prompt, invalid config)
           content:
             application/json:
               schema:
@@ -225,7 +221,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error'
         '403':
-          description: 'No permission to access referenced resources (environment, MCP servers)'
+          description: No permission to access referenced resources (environment, MCP servers)
           content:
             application/json:
               schema:
@@ -238,9 +234,9 @@ paths:
         The agent will be queued for execution and assigned a unique run ID.
       operationId: createRun
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       requestBody:
         required: true
         content:
@@ -255,7 +251,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/RunAgentResponse'
         '400':
-          description: 'Invalid request (missing prompt, invalid config)'
+          description: Invalid request (missing prompt, invalid config)
           content:
             application/json:
               schema:
@@ -267,7 +263,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error'
         '403':
-          description: 'No permission to access referenced resources (environment, MCP servers)'
+          description: No permission to access referenced resources (environment, MCP servers)
           content:
             application/json:
               schema:
@@ -279,171 +275,187 @@ paths:
         Results default to `sort_by=updated_at` and `sort_order=desc`.
       operationId: listRuns
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: limit
-          in: query
-          description: Maximum number of runs to return
-          required: false
-          schema:
-            type: integer
-            minimum: 1
-            maximum: 500
-            default: 20
-        - name: cursor
-          in: query
-          description: Pagination cursor from previous response
-          required: false
-          schema:
-            type: string
-        - name: sort_by
-          in: query
-          description: |
-            Sort field for results.
-            - `updated_at`: Sort by last update timestamp (default)
-            - `created_at`: Sort by creation timestamp
-            - `title`: Sort alphabetically by run title
-            - `agent`: Sort alphabetically by skill. Runs without a skill are grouped last.
-          required: false
-          schema:
-            type: string
-            enum:
-              - updated_at
-              - created_at
-              - title
-              - agent
-            default: updated_at
-        - name: sort_order
-          in: query
-          description: Sort direction
-          required: false
-          schema:
-            type: string
-            enum:
-              - asc
-              - desc
-            default: desc
-        - name: state
-          in: query
-          description: |
-            Filter by run state. Can be specified multiple times to match any of the given states.
-          required: false
-          schema:
-            type: array
-            items:
-              $ref: '#/components/schemas/RunState'
-          style: form
-          explode: true
-        - name: name
-          in: query
-          description: Filter by agent config name
-          required: false
-          schema:
-            type: string
-        - name: model_id
-          in: query
-          description: Filter by model ID
-          required: false
-          schema:
-            type: string
-        - name: creator
-          in: query
-          description: Filter by creator UID (user or service account)
-          required: false
-          schema:
-            type: string
-        - name: executor
-          in: query
-          description: |
-            Filter by the user or agent that executed the run. This will often be the
-            same as the creator, but not always: users may delegate tasks to agents.
-          required: false
-          schema:
-            type: string
-        - name: source
-          in: query
-          description: Filter by run source type
-          required: false
-          schema:
-            $ref: '#/components/schemas/RunSourceType'
-        - name: execution_location
-          in: query
-          description: Filter by where the run executed
-          required: false
-          schema:
-            $ref: '#/components/schemas/RunExecutionLocation'
-        - name: created_after
-          in: query
-          description: Filter runs created after this timestamp (RFC3339 format)
-          required: false
-          schema:
-            type: string
-            format: date-time
-        - name: created_before
-          in: query
-          description: Filter runs created before this timestamp (RFC3339 format)
-          required: false
-          schema:
-            type: string
-            format: date-time
-        - name: updated_after
-          in: query
-          description: Filter runs updated after this timestamp (RFC3339 format)
-          required: false
-          schema:
-            type: string
-            format: date-time
-        - name: environment_id
-          in: query
-          description: Filter runs by environment ID
-          required: false
-          schema:
-            type: string
-        - name: skill
-          in: query
-          description: |
-            Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md").
-            Alias for skill_spec.
-          required: false
-          schema:
-            type: string
-        - name: skill_spec
-          in: query
-          description: 'Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")'
-          required: false
-          schema:
-            type: string
-        - name: schedule_id
-          in: query
-          description: Filter runs by the scheduled agent ID that created them
-          required: false
-          schema:
-            type: string
-        - name: ancestor_run_id
-          in: query
-          description: Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller.
-          required: false
-          schema:
-            type: string
-        - name: artifact_type
-          in: query
-          description: Filter runs by artifact type
-          required: false
-          schema:
-            type: string
-            enum:
-              - PLAN
-              - PULL_REQUEST
-              - SCREENSHOT
-              - FILE
-        - name: q
-          in: query
-          description: 'Fuzzy search query across run title, prompt, and skill_spec'
-          required: false
-          schema:
+      - name: limit
+        in: query
+        description: Maximum number of runs to return
+        required: false
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 500
+          default: 20
+      - name: cursor
+        in: query
+        description: Pagination cursor from previous response
+        required: false
+        schema:
+          type: string
+      - name: sort_by
+        in: query
+        description: |
+          Sort field for results.
+          - `updated_at`: Sort by last update timestamp (default)
+          - `created_at`: Sort by creation timestamp
+          - `title`: Sort alphabetically by run title
+          - `agent`: Sort alphabetically by skill. Runs without a skill are grouped last.
+        required: false
+        schema:
+          type: string
+          enum:
+          - updated_at
+          - created_at
+          - title
+          - agent
+          default: updated_at
+      - name: sort_order
+        in: query
+        description: Sort direction
+        required: false
+        schema:
+          type: string
+          enum:
+          - asc
+          - desc
+          default: desc
+      - name: state
+        in: query
+        description: |
+          Filter by run state. Can be specified multiple times to match any of the given states.
+        required: false
+        schema:
+          type: array
+          items:
+            $ref: '#/components/schemas/RunState'
+        style: form
+        explode: true
+      - name: name
+        in: query
+        description: Filter by agent config name
+        required: false
+        schema:
+          type: string
+      - name: model_id
+        in: query
+        description: Filter by model ID
+        required: false
+        schema:
+          type: string
+      - name: creator
+        in: query
+        description: Filter by creator UID (user or service account)
+        required: false
+        schema:
+          type: string
+      - name: executor
+        in: query
+        description: |
+          Filter by the user or agent that executed the run. This will often be the
+          same as the creator, but not always: users may delegate tasks to agents.
+        required: false
+        schema:
+          type: string
+      - name: source
+        in: query
+        description: Filter by run source type
+        required: false
+        schema:
+          $ref: '#/components/schemas/RunSourceType'
+      - name: execution_location
+        in: query
+        description: Filter by where the run executed
+        required: false
+        schema:
+          $ref: '#/components/schemas/RunExecutionLocation'
+      - name: created_after
+        in: query
+        description: Filter runs created after this timestamp (RFC3339 format)
+        required: false
+        schema:
+          type: string
+          format: date-time
+      - name: created_before
+        in: query
+        description: Filter runs created before this timestamp (RFC3339 format)
+        required: false
+        schema:
+          type: string
+          format: date-time
+      - name: updated_after
+        in: query
+        description: Filter runs updated after this timestamp (RFC3339 format)
+        required: false
+        schema:
+          type: string
+          format: date-time
+      - name: environment_id
+        in: query
+        description: Filter runs by environment ID
+        required: false
+        schema:
+          type: string
+      - name: skill
+        in: query
+        description: |
+          Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md").
+          Alias for skill_spec.
+        required: false
+        schema:
+          type: string
+      - name: skill_spec
+        in: query
+        description: Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")
+        required: false
+        schema:
+          type: string
+      - name: schedule_id
+        in: query
+        description: Filter runs by the scheduled agent ID that created them
+        required: false
+        schema:
+          type: string
+      - name: ancestor_run_id
+        in: query
+        description: Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller.
+        required: false
+        schema:
+          type: string
+      - name: metadata
+        in: query
+        description: |
+          Filter by exact metadata key/value pairs using object notation (e.g.
+          `metadata[ticket_id]=VIS-238`). Multiple pairs combine with AND semantics.
+          At most 5 pairs per request. Returns `feature_not_available` when metadata
+          filtering is not enabled.
+        required: false
+        schema:
+          type: object
+          maxProperties: 5
+          additionalProperties:
             type: string
+        style: deepObject
+        explode: true
+      - name: artifact_type
+        in: query
+        description: Filter runs by artifact type
+        required: false
+        schema:
+          type: string
+          enum:
+          - PLAN
+          - PULL_REQUEST
+          - SCREENSHOT
+          - FILE
+          - EXTERNAL_REFERENCE
+      - name: q
+        in: query
+        description: Fuzzy search query across run title, prompt, and skill_spec
+        required: false
+        schema:
+          type: string
       responses:
         '200':
           description: List of runs
@@ -463,24 +475,81 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/runs/{runId}':
+        '403':
+          description: Metadata filtering is not enabled for this environment
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /agent/run-by-external-reference:
     get:
-      summary: Get run details
+      summary: Find the run that produced a given external reference URL
       description: |
-        Retrieve detailed information about a specific agent run, 
-        including the full prompt, session link, and resolved configuration.
+        Reverse-looks up the agent run that created an EXTERNAL_REFERENCE artifact
+        with the given URL. The URL is matched against the canonical locator stored
+        when the artifact was reported via POST /harness-support/report-artifact
+        with artifact_type EXTERNAL_REFERENCE. Returns 404 when no matching run
+        exists or when the caller lacks access, to avoid leaking run existence.
+      operationId: getRunByExternalReferenceURL
+      tags:
+      - agent
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: url
+        in: query
+        required: true
+        description: The canonical URL of the external reference artifact to look up.
+        schema:
+          type: string
+          maxLength: 2048
+      responses:
+        '200':
+          description: Run found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RunByExternalReferenceResponse'
+        '400':
+          description: url query parameter is missing
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: No run found with the given external reference URL, or caller lacks access
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /agent/runs/{runId}:
+    get:
+      summary: Get run details
+      description: "Retrieve detailed information about a specific agent run, \nincluding the full prompt, session link, and resolved configuration.\n"
       operationId: getRun
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: runId
-          in: path
-          description: The unique identifier of the run
-          required: true
-          schema:
-            type: string
+      - name: runId
+        in: path
+        description: The unique identifier of the run
+        required: true
+        schema:
+          type: string
       responses:
         '200':
           description: Run details
@@ -512,23 +581,23 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/runs/{runId}/timeline':
+  /agent/runs/{runId}/timeline:
     get:
       summary: Get run timeline
       description: |
         Retrieve chronological setup and lifecycle timeline events for an agent run.
       operationId: getRunTimeline
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: runId
-          in: path
-          description: The unique identifier of the run
-          required: true
-          schema:
-            type: string
+      - name: runId
+        in: path
+        description: The unique identifier of the run
+        required: true
+        schema:
+          type: string
       responses:
         '200':
           description: Run timeline events
@@ -560,7 +629,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/runs/{runId}/conversation':
+  /agent/runs/{runId}/conversation:
     get:
       summary: Get normalized run conversation
       description: |
@@ -570,16 +639,16 @@ paths:
         structured blocks.
       operationId: getRunConversation
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: runId
-          in: path
-          description: The unique identifier of the run
-          required: true
-          schema:
-            type: string
+      - name: runId
+        in: path
+        description: The unique identifier of the run
+        required: true
+        schema:
+          type: string
       responses:
         '200':
           description: Normalized conversation
@@ -606,7 +675,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error'
         '404':
-          description: 'Run not found, or the run has no conversation'
+          description: Run not found, or the run has no conversation
           content:
             application/json:
               schema:
@@ -619,7 +688,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/runs/{runId}/cancel':
+  /agent/runs/{runId}/cancel:
     post:
       summary: Cancel a run
       description: |
@@ -632,16 +701,16 @@ paths:
         and GitHub Action runs return 422.
       operationId: cancelRun
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: runId
-          in: path
-          description: The unique identifier of the run to cancel
-          required: true
-          schema:
-            type: string
+      - name: runId
+        in: path
+        description: The unique identifier of the run to cancel
+        required: true
+        schema:
+          type: string
       responses:
         '200':
           description: Run cancelled successfully
@@ -693,7 +762,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/runs/{runId}/followups':
+  /agent/runs/{runId}/followups:
     post:
       summary: Submit a follow-up message for a run
       description: |
@@ -704,16 +773,16 @@ paths:
         `GET /agent/runs/{runId}`.
       operationId: submitRunFollowup
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: runId
-          in: path
-          description: The unique identifier of the run
-          required: true
-          schema:
-            type: string
+      - name: runId
+        in: path
+        description: The unique identifier of the run
+        required: true
+        schema:
+          type: string
       requestBody:
         required: true
         content:
@@ -760,7 +829,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/conversations/{conversation_id}':
+  /agent/conversations/{conversation_id}:
     get:
       summary: Get normalized conversation
       description: |
@@ -768,16 +837,16 @@ paths:
         normalized task/message format.
       operationId: getConversation
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: conversation_id
-          in: path
-          description: The unique identifier of the conversation
-          required: true
-          schema:
-            type: string
+      - name: conversation_id
+        in: path
+        description: The unique identifier of the conversation
+        required: true
+        schema:
+          type: string
       responses:
         '200':
           description: Normalized conversation
@@ -825,9 +894,9 @@ paths:
         The agent will be triggered automatically based on the cron expression.
       operationId: createScheduledAgent
       tags:
-        - schedules
+      - schedules
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       requestBody:
         required: true
         content:
@@ -859,7 +928,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/ScheduledAgentItem'
         '400':
-          description: 'Invalid request (missing required fields, invalid cron expression)'
+          description: Invalid request (missing required fields, invalid cron expression)
           content:
             application/json:
               schema:
@@ -883,9 +952,9 @@ paths:
         Results are sorted alphabetically by name.
       operationId: listScheduledAgents
       tags:
-        - schedules
+      - schedules
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       responses:
         '200':
           description: List of scheduled agents
@@ -905,7 +974,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/schedules/{scheduleId}':
+  /agent/schedules/{scheduleId}:
     get:
       summary: Get scheduled agent details
       description: |
@@ -913,16 +982,16 @@ paths:
         including its configuration, history, and next scheduled run time.
       operationId: getScheduledAgent
       tags:
-        - schedules
+      - schedules
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: scheduleId
-          in: path
-          description: The unique identifier of the scheduled agent
-          required: true
-          schema:
-            type: string
+      - name: scheduleId
+        in: path
+        description: The unique identifier of the scheduled agent
+        required: true
+        schema:
+          type: string
       responses:
         '200':
           description: Scheduled agent details
@@ -961,16 +1030,16 @@ paths:
         All fields except agent_config are required.
       operationId: updateScheduledAgent
       tags:
-        - schedules
+      - schedules
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: scheduleId
-          in: path
-          description: The unique identifier of the scheduled agent
-          required: true
-          schema:
-            type: string
+      - name: scheduleId
+        in: path
+        description: The unique identifier of the scheduled agent
+        required: true
+        schema:
+          type: string
       requestBody:
         required: true
         content:
@@ -1014,16 +1083,16 @@ paths:
         Delete a scheduled agent. This will stop all future scheduled runs.
       operationId: deleteScheduledAgent
       tags:
-        - schedules
+      - schedules
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: scheduleId
-          in: path
-          description: The unique identifier of the scheduled agent
-          required: true
-          schema:
-            type: string
+      - name: scheduleId
+        in: path
+        description: The unique identifier of the scheduled agent
+        required: true
+        schema:
+          type: string
       responses:
         '200':
           description: Scheduled agent deleted successfully
@@ -1055,23 +1124,23 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/schedules/{scheduleId}/pause':
+  /agent/schedules/{scheduleId}/pause:
     post:
       summary: Pause a scheduled agent
       description: |
         Pause a scheduled agent. The agent will not run until resumed.
       operationId: pauseScheduledAgent
       tags:
-        - schedules
+      - schedules
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: scheduleId
-          in: path
-          description: The unique identifier of the scheduled agent
-          required: true
-          schema:
-            type: string
+      - name: scheduleId
+        in: path
+        description: The unique identifier of the scheduled agent
+        required: true
+        schema:
+          type: string
       responses:
         '200':
           description: Scheduled agent paused successfully
@@ -1103,7 +1172,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/schedules/{scheduleId}/resume':
+  /agent/schedules/{scheduleId}/resume:
     post:
       summary: Resume a scheduled agent
       description: |
@@ -1111,16 +1180,16 @@ paths:
         according to its cron schedule.
       operationId: resumeScheduledAgent
       tags:
-        - schedules
+      - schedules
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: scheduleId
-          in: path
-          description: The unique identifier of the scheduled agent
-          required: true
-          schema:
-            type: string
+      - name: scheduleId
+        in: path
+        description: The unique identifier of the scheduled agent
+        required: true
+        schema:
+          type: string
       responses:
         '200':
           description: Scheduled agent resumed successfully
@@ -1161,23 +1230,23 @@ paths:
         or has accessed via link sharing.
       operationId: listEnvironments
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: sort_by
-          in: query
-          required: false
-          description: |
-            Sort order for the returned environments.
-            - `name`: alphabetical by environment name
-            - `last_updated`: most recently updated first (default)
-          schema:
-            type: string
-            enum:
-              - name
-              - last_updated
-            default: last_updated
+      - name: sort_by
+        in: query
+        required: false
+        description: |
+          Sort order for the returned environments.
+          - `name`: alphabetical by environment name
+          - `last_updated`: most recently updated first (default)
+        schema:
+          type: string
+          enum:
+          - name
+          - last_updated
+          default: last_updated
       responses:
         '200':
           description: List of accessible environments
@@ -1207,9 +1276,9 @@ paths:
         currently disabled (and why).
       operationId: listModels
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       responses:
         '200':
           description: List of available models
@@ -1229,7 +1298,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/artifacts/{artifactUid}':
+  /agent/artifacts/{artifactUid}:
     get:
       summary: Get artifact details
       description: |
@@ -1238,16 +1307,16 @@ paths:
         the current plan content inline.
       operationId: getArtifact
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: artifactUid
-          in: path
-          description: The unique identifier (UUID) of the artifact
-          required: true
-          schema:
-            type: string
+      - name: artifactUid
+        in: path
+        description: The unique identifier (UUID) of the artifact
+        required: true
+        schema:
+          type: string
       responses:
         '200':
           description: Artifact details with download information
@@ -1279,50 +1348,63 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  /harness-support/transcript:
+  /agent/artifacts/{artifactUid}/download:
     get:
-      summary: Download the raw third-party harness transcript
+      summary: Download an artifact
       description: |
-        Redirects to a signed download URL for the raw third-party harness transcript
-        (e.g. `claude_code.json`) of the current task's conversation. Only supported
-        for conversations produced by non-Oz harnesses; Oz conversations 400.
-
-        This may only be called from within a cloud agent execution environment whose
-        task already has an associated conversation (e.g. on a resumed run).
-      operationId: getTranscriptDownload
+        Redirect to a temporary signed download URL for a downloadable artifact.
+        Public artifacts can be downloaded without authentication; private
+        artifacts require the caller to be authenticated and authorized.
+      operationId: downloadArtifact
       tags:
-        - harness-support
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
+      - {}
+      parameters:
+      - name: artifactUid
+        in: path
+        description: The unique identifier (UUID) of the artifact
+        required: true
+        schema:
+          type: string
       responses:
-        '307':
-          description: Redirect to a signed download URL for the transcript
+        '302':
+          description: Redirect to a temporary signed artifact download URL
+          headers:
+            Location:
+              description: Temporary signed download URL
+              schema:
+                type: string
+                format: uri
+            Cache-Control:
+              description: Cache directive for the redirect response
+              schema:
+                type: string
+            X-Content-Type-Options:
+              description: Browser content sniffing protection
+              schema:
+                type: string
         '400':
-          description: 'Task has no conversation, or conversation format does not support transcript downloads'
+          description: Missing artifact UID
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
         '401':
-          description: Authentication required
+          description: Authentication required for private artifacts
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
         '403':
-          description: No permission to access the conversation
+          description: No permission to access private artifact
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
         '404':
-          description: Conversation or transcript not found
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
-        '500':
-          description: Internal server error
+          description: Artifact not found or unsupported artifact type
           content:
             application/json:
               schema:
@@ -1335,9 +1417,9 @@ paths:
         Agents can be used as the execution principal for team-owned runs.
       operationId: createAgent
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       requestBody:
         required: true
         content:
@@ -1352,7 +1434,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/AgentResponse'
         '400':
-          description: 'Invalid request (empty name, user on multiple teams, or on no team)'
+          description: Invalid request (empty name, user on multiple teams, or on no team)
           content:
             application/json:
               schema:
@@ -1364,7 +1446,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error'
         '403':
-          description: 'Only human users can manage agents, or plan limit exceeded'
+          description: Only human users can manage agents, or plan limit exceeded
           content:
             application/json:
               schema:
@@ -1383,9 +1465,9 @@ paths:
         and may be used for runs.
       operationId: listAgents
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       responses:
         '200':
           description: List of agents
@@ -1394,7 +1476,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/ListAgentIdentitiesResponse'
         '400':
-          description: 'User on multiple teams, or on no team'
+          description: User on multiple teams, or on no team
           content:
             application/json:
               schema:
@@ -1417,7 +1499,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/identities/{uid}':
+  /agent/identities/{uid}:
     get:
       summary: Retrieve an agent
       description: |
@@ -1426,16 +1508,16 @@ paths:
         is within the team's plan limit and may be used for runs.
       operationId: getAgent
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: uid
-          in: path
-          description: The unique identifier of the agent
-          required: true
-          schema:
-            type: string
+      - name: uid
+        in: path
+        description: The unique identifier of the agent
+        required: true
+        schema:
+          type: string
       responses:
         '200':
           description: Agent details
@@ -1467,16 +1549,16 @@ paths:
         Update an existing agent.
       operationId: updateAgent
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: uid
-          in: path
-          description: The unique identifier of the agent
-          required: true
-          schema:
-            type: string
+      - name: uid
+        in: path
+        description: The unique identifier of the agent
+        required: true
+        schema:
+          type: string
       requestBody:
         required: true
         content:
@@ -1503,7 +1585,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error'
         '403':
-          description: 'Only human users can manage agents, or plan limit exceeded'
+          description: Only human users can manage agents, or plan limit exceeded
           content:
             application/json:
               schema:
@@ -1527,16 +1609,16 @@ paths:
         agent are deleted atomically.
       operationId: deleteAgent
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: uid
-          in: path
-          description: The unique identifier of the agent
-          required: true
-          schema:
-            type: string
+      - name: uid
+        in: path
+        description: The unique identifier of the agent
+        required: true
+        schema:
+          type: string
       responses:
         '204':
           description: Agent deleted successfully
@@ -1617,11 +1699,21 @@ components:
           description: |
             Whether to create a team-owned run.
             Defaults to true for users on a single team.
+          x-go-type-skip-optional-pointer: false
         agent_identity_uid:
           type: string
           description: |
             Optional agent identity UID to use as the execution principal for the run.
-            This is only valid for runs that are team owned. 
+            This is only valid for runs that are team owned.
+        on_behalf_of:
+          type: string
+          description: |
+            Optional email address or user ID of a Warp user to attribute the run to.
+            When set, the resolved user becomes the run's creator instead of the caller.
+            Only agent API keys may use this field, and the calling agent must have
+            on_behalf_of enabled in its configuration (`on_behalf_of_enabled`), which a
+            team admin must intentionally turn on per agent. The target user must be an
+            active member of the run's owner team. Only valid for team-owned runs.
         conversation_id:
           type: string
           description: |
@@ -1644,12 +1736,26 @@ components:
           description: |
             Whether the run should be interactive.
             If not set, defaults to false.
+        metadata:
+          $ref: '#/components/schemas/RunMetadata'
+    RunMetadata:
+      type: object
+      additionalProperties:
+        type: string
+      description: |
+        Custom key/value metadata attached to a run at creation time and immutable afterward.
+        At most 20 keys. Keys are 1-64 bytes matching [a-zA-Z0-9._-]+ (case-sensitive);
+        values are 0-256 bytes of UTF-8 and cannot contain NUL characters.
+        Requests with invalid metadata are rejected.
+        A run's effective metadata is merged per key at creation: explicit request keys
+        override keys inherited from the parent run, which override automatic keys
+        (ticket_id and ticket_source on Linear- and Jira-triggered runs).
     RunAgentResponse:
       type: object
       required:
-        - run_id
-        - task_id
-        - state
+      - run_id
+      - task_id
+      - state
       properties:
         run_id:
           type: string
@@ -1657,6 +1763,7 @@ components:
         task_id:
           type: string
           deprecated: true
+          x-stainless-deprecation-message: Use run_id instead.
           description: Unique identifier for the task (same as run_id). Deprecated - use run_id instead.
         state:
           $ref: '#/components/schemas/RunState'
@@ -1671,15 +1778,15 @@ components:
           - plan: Planning Mode. The agent researches and creates a plan, then waits for approval before execution.
           - orchestrate: Orchestration Mode. The agent proposes an orchestration plan and must not start child agents until approved.
       enum:
-        - normal
-        - plan
-        - orchestrate
+      - normal
+      - plan
+      - orchestrate
       default: normal
     ListRunsResponse:
       type: object
       required:
-        - runs
-        - page_info
+      - runs
+      - page_info
       properties:
         runs:
           type: array
@@ -1690,13 +1797,13 @@ components:
     RunItem:
       type: object
       required:
-        - run_id
-        - task_id
-        - title
-        - state
-        - prompt
-        - created_at
-        - updated_at
+      - run_id
+      - task_id
+      - title
+      - state
+      - prompt
+      - created_at
+      - updated_at
       properties:
         run_id:
           type: string
@@ -1704,6 +1811,7 @@ components:
         task_id:
           type: string
           deprecated: true
+          x-stainless-deprecation-message: Use run_id instead.
           description: Unique identifier for the task (typically matches run_id). Deprecated - use run_id instead.
         title:
           type: string
@@ -1726,7 +1834,7 @@ components:
         run_time:
           type: string
           format: duration
-          description: 'Total runtime as an ISO 8601 duration (e.g. "PT2M30S"), computed server-side from run executions.'
+          description: Total runtime as an ISO 8601 duration (e.g. "PT2M30S"), computed server-side from run executions.
         started_at:
           type: string
           format: date-time
@@ -1748,7 +1856,7 @@ components:
         trigger_url:
           type: string
           format: uri
-          description: 'URL to the run trigger (e.g. Slack thread, Linear issue, schedule)'
+          description: URL to the run trigger (e.g. Slack thread, Linear issue, schedule)
         creator:
           $ref: '#/components/schemas/RunCreatorInfo'
         executor:
@@ -1763,14 +1871,22 @@ components:
         parent_run_id:
           type: string
           description: UUID of the parent run that spawned this run
+        metadata:
+          $ref: '#/components/schemas/RunMetadata'
         is_sandbox_running:
           type: boolean
           description: Whether the sandbox environment is currently running
+        is_run_type_cancellable:
+          type: boolean
+          description: |
+            Whether the run's type is eligible for cancellation via the API. State-independent:
+            false for GitHub Action and local runs; true for all other run types (including
+            self-hosted). Clients should still gate the control on the run's current state.
         artifacts:
           type: array
           items:
             $ref: '#/components/schemas/ArtifactItem'
-          description: 'Artifacts created during the run (plans, pull requests, etc.)'
+          description: Artifacts created during the run (plans, pull requests, etc.)
         agent_skill:
           $ref: '#/components/schemas/AgentSkill'
         scope:
@@ -1779,20 +1895,23 @@ components:
       type: object
       description: Response body for listing run timeline events.
       required:
-        - events
+      - events
       properties:
         events:
           type: array
           items:
             $ref: '#/components/schemas/AIRunTimelineEvent'
     AIRunTimelineEvent:
+      x-go-type: types.AIRunTimelineEvent
+      x-go-type-import:
+        path: github.com/warpdotdev/warp-server/model/types
       type: object
       description: A setup or lifecycle event recorded for an agent run.
       required:
-        - event_uuid
-        - run_id
-        - event_type
-        - occurred_at
+      - event_uuid
+      - run_id
+      - event_type
+      - occurred_at
       properties:
         event_uuid:
           type: string
@@ -1803,7 +1922,8 @@ components:
         execution_id:
           type: integer
           format: int64
-          description: 'Run execution associated with this event, when available.'
+          x-go-type-skip-optional-pointer: false
+          description: Run execution associated with this event, when available.
         event_type:
           $ref: '#/components/schemas/AIRunTimelineEventType'
         occurred_at:
@@ -1813,23 +1933,28 @@ components:
         payload:
           type: object
           additionalProperties: true
+          x-go-type: json.RawMessage
           description: Optional event-specific JSON payload.
     AIRunTimelineEventType:
       type: string
       description: Type of timeline event recorded for a run.
       enum:
-        - oz_run_created
-        - oz_run_claimed
-        - worker_container_ready
-        - shared_session_started
-        - agent_started
-        - oz_run_finished
-        - oz_run_failure
+      - oz_run_created
+      - oz_run_claimed
+      - worker_container_ready
+      - shared_session_started
+      - agent_started
+      - oz_run_done
+      - oz_run_blocked
+      - oz_run_cancelled
+      - oz_run_failed
+      - oz_run_errored
+      - vm_shutdown
     ConversationResponse:
       type: object
       required:
-        - conversation_id
-        - steps
+      - conversation_id
+      - steps
       properties:
         conversation_id:
           type: string
@@ -1842,9 +1967,9 @@ components:
     ConversationStep:
       type: object
       required:
-        - id
-        - messages
-        - steps
+      - id
+      - messages
+      - steps
       properties:
         id:
           type: string
@@ -1876,8 +2001,8 @@ components:
     ConversationMessage:
       type: object
       required:
-        - role
-        - content
+      - role
+      - content
       properties:
         message_ids:
           type: array
@@ -1886,7 +2011,7 @@ components:
             type: string
         request_id:
           type: string
-          description: 'Request identifier shared by transcript messages from the same request, when available'
+          description: Request identifier shared by transcript messages from the same request, when available
         role:
           $ref: '#/components/schemas/ConversationMessageRole'
         timestamp:
@@ -1901,16 +2026,16 @@ components:
       type: string
       description: Role of the normalized message
       enum:
-        - user
-        - assistant
-        - tool
-        - system
+      - user
+      - assistant
+      - tool
+      - system
     ConversationContentBlock:
       oneOf:
-        - $ref: '#/components/schemas/TextContentBlock'
-        - $ref: '#/components/schemas/ActionContentBlock'
-        - $ref: '#/components/schemas/ActionResultContentBlock'
-        - $ref: '#/components/schemas/EventContentBlock'
+      - $ref: '#/components/schemas/TextContentBlock'
+      - $ref: '#/components/schemas/ActionContentBlock'
+      - $ref: '#/components/schemas/ActionResultContentBlock'
+      - $ref: '#/components/schemas/EventContentBlock'
       discriminator:
         propertyName: type
         mapping:
@@ -1921,16 +2046,16 @@ components:
     TextContentBlock:
       type: object
       required:
-        - type
-        - text
+      - type
+      - text
       properties:
         type:
           type: string
           enum:
-            - text
+          - text
         message_id:
           type: string
-          description: 'Underlying transcript message ID that produced this content block, when available'
+          description: Underlying transcript message ID that produced this content block, when available
         text:
           type: string
           description: Plain text content
@@ -1938,38 +2063,38 @@ components:
       type: string
       description: High-level category of an action performed during the conversation
       enum:
-        - command
-        - files
-        - search
-        - integration
-        - documents
-        - computer
-        - review
-        - skill
+      - command
+      - files
+      - search
+      - integration
+      - documents
+      - computer
+      - review
+      - skill
     ActionState:
       type: string
       description: State of an action result
       enum:
-        - running
-        - completed
-        - failed
-        - denied
+      - running
+      - completed
+      - failed
+      - denied
     ActionContentBlock:
       type: object
       required:
-        - type
-        - id
-        - category
-        - name
-        - input
+      - type
+      - id
+      - category
+      - name
+      - input
       properties:
         type:
           type: string
           enum:
-            - action
+          - action
         message_id:
           type: string
-          description: 'Underlying transcript message ID that produced this content block, when available'
+          description: Underlying transcript message ID that produced this content block, when available
         id:
           type: string
           description: Unique identifier for the action
@@ -1977,7 +2102,7 @@ components:
           $ref: '#/components/schemas/ActionCategory'
         name:
           type: string
-          description: 'Public action name, such as run_command or edit_files'
+          description: Public action name, such as run_command or edit_files
         input:
           type: object
           additionalProperties: true
@@ -1985,20 +2110,20 @@ components:
     ActionResultContentBlock:
       type: object
       required:
-        - type
-        - action_id
-        - category
-        - name
-        - state
-        - output
+      - type
+      - action_id
+      - category
+      - name
+      - state
+      - output
       properties:
         type:
           type: string
           enum:
-            - action_result
+          - action_result
         message_id:
           type: string
-          description: 'Underlying transcript message ID that produced this content block, when available'
+          description: Underlying transcript message ID that produced this content block, when available
         action_id:
           type: string
           description: Identifier of the corresponding action
@@ -2016,17 +2141,17 @@ components:
     EventContentBlock:
       type: object
       required:
-        - type
-        - name
-        - data
+      - type
+      - name
+      - data
       properties:
         type:
           type: string
           enum:
-            - event
+          - event
         message_id:
           type: string
-          description: 'Underlying transcript message ID that produced this content block, when available'
+          description: Underlying transcript message ID that produced this content block, when available
         name:
           type: string
           description: Event type for intentionally exposed non-core transcript events
@@ -2036,10 +2161,11 @@ components:
           description: Minimal structured metadata for the event
     ArtifactItem:
       oneOf:
-        - $ref: '#/components/schemas/PlanArtifact'
-        - $ref: '#/components/schemas/PullRequestArtifact'
-        - $ref: '#/components/schemas/ScreenshotArtifact'
-        - $ref: '#/components/schemas/FileArtifact'
+      - $ref: '#/components/schemas/PlanArtifact'
+      - $ref: '#/components/schemas/PullRequestArtifact'
+      - $ref: '#/components/schemas/ScreenshotArtifact'
+      - $ref: '#/components/schemas/FileArtifact'
+      - $ref: '#/components/schemas/ExternalReferenceArtifact'
       discriminator:
         propertyName: artifact_type
         mapping:
@@ -2047,17 +2173,36 @@ components:
           PULL_REQUEST: '#/components/schemas/PullRequestArtifact'
           SCREENSHOT: '#/components/schemas/ScreenshotArtifact'
           FILE: '#/components/schemas/FileArtifact'
+          EXTERNAL_REFERENCE: '#/components/schemas/ExternalReferenceArtifact'
+    ExternalReferenceArtifact:
+      type: object
+      required:
+      - artifact_type
+      - created_at
+      - data
+      properties:
+        artifact_type:
+          type: string
+          enum:
+          - EXTERNAL_REFERENCE
+          description: Type of the artifact
+        created_at:
+          type: string
+          format: date-time
+          description: Timestamp when the artifact was created (RFC3339)
+        data:
+          $ref: '#/components/schemas/ExternalReferenceArtifactData'
     PlanArtifact:
       type: object
       required:
-        - artifact_type
-        - created_at
-        - data
+      - artifact_type
+      - created_at
+      - data
       properties:
         artifact_type:
           type: string
           enum:
-            - PLAN
+          - PLAN
           description: Type of the artifact
         created_at:
           type: string
@@ -2068,14 +2213,14 @@ components:
     PullRequestArtifact:
       type: object
       required:
-        - artifact_type
-        - created_at
-        - data
+      - artifact_type
+      - created_at
+      - data
       properties:
         artifact_type:
           type: string
           enum:
-            - PULL_REQUEST
+          - PULL_REQUEST
           description: Type of the artifact
         created_at:
           type: string
@@ -2086,14 +2231,14 @@ components:
     ScreenshotArtifact:
       type: object
       required:
-        - artifact_type
-        - created_at
-        - data
+      - artifact_type
+      - created_at
+      - data
       properties:
         artifact_type:
           type: string
           enum:
-            - SCREENSHOT
+          - SCREENSHOT
           description: Type of the artifact
         created_at:
           type: string
@@ -2104,14 +2249,14 @@ components:
     FileArtifact:
       type: object
       required:
-        - artifact_type
-        - created_at
-        - data
+      - artifact_type
+      - created_at
+      - data
       properties:
         artifact_type:
           type: string
           enum:
-            - FILE
+          - FILE
           description: Type of the artifact
         created_at:
           type: string
@@ -2122,11 +2267,11 @@ components:
     PlanArtifactData:
       type: object
       required:
-        - document_uid
+      - document_uid
       properties:
         artifact_uid:
           type: string
-          description: 'Unique identifier for the plan artifact, usable with the artifact retrieval endpoint'
+          description: Unique identifier for the plan artifact, usable with the artifact retrieval endpoint
         document_uid:
           type: string
           description: Unique identifier for the plan document
@@ -2143,8 +2288,8 @@ components:
     PullRequestArtifactData:
       type: object
       required:
-        - url
-        - branch
+      - url
+      - branch
       properties:
         url:
           type: string
@@ -2156,8 +2301,8 @@ components:
     ScreenshotArtifactData:
       type: object
       required:
-        - artifact_uid
-        - mime_type
+      - artifact_uid
+      - mime_type
       properties:
         artifact_uid:
           type: string
@@ -2171,10 +2316,10 @@ components:
     FileArtifactData:
       type: object
       required:
-        - artifact_uid
-        - filepath
-        - filename
-        - mime_type
+      - artifact_uid
+      - filepath
+      - filename
+      - mime_type
       properties:
         artifact_uid:
           type: string
@@ -2185,6 +2330,12 @@ components:
         filename:
           type: string
           description: Last path component of filepath
+        title:
+          type: string
+          description: |
+            Short, badge-visible label for the artifact. For recording artifacts,
+            this is the agent-authored title shown in Oz web and blocklist badges.
+            Distinct from description, which is longer and shown in detail views.
         description:
           type: string
           description: Optional description of the file
@@ -2195,13 +2346,14 @@ components:
           type: integer
           format: int64
           description: Size of the uploaded file in bytes
+          x-go-type-skip-optional-pointer: false
     ScheduleInfo:
       type: object
       description: Information about the schedule that triggered this run (only present for scheduled runs)
       required:
-        - schedule_id
-        - schedule_name
-        - cron_schedule
+      - schedule_id
+      - schedule_name
+      - cron_schedule
       properties:
         schedule_id:
           type: string
@@ -2215,7 +2367,7 @@ components:
     PageInfo:
       type: object
       required:
-        - has_next_page
+      - has_next_page
       properties:
         has_next_page:
           type: boolean
@@ -2229,7 +2381,7 @@ components:
         Status message for a run. For terminal error states, includes structured
         error code and retryability info from the platform error catalog.
       required:
-        - message
+      - message
       properties:
         message:
           type: string
@@ -2264,8 +2416,8 @@ components:
         type:
           type: string
           enum:
-            - user
-            - service_account
+          - user
+          - service_account
           description: Type of the creator principal
         uid:
           type: string
@@ -2283,15 +2435,15 @@ components:
     RunState:
       type: string
       enum:
-        - QUEUED
-        - PENDING
-        - CLAIMED
-        - INPROGRESS
-        - SUCCEEDED
-        - FAILED
-        - BLOCKED
-        - ERROR
-        - CANCELLED
+      - QUEUED
+      - PENDING
+      - CLAIMED
+      - INPROGRESS
+      - SUCCEEDED
+      - FAILED
+      - BLOCKED
+      - ERROR
+      - CANCELLED
       description: |
         Current state of the run:
         - QUEUED: Run is waiting to be picked up
@@ -2306,15 +2458,16 @@ components:
     RunSourceType:
       type: string
       enum:
-        - LINEAR
-        - API
-        - SLACK
-        - LOCAL
-        - SCHEDULED_AGENT
-        - WEB_APP
-        - GITHUB_ACTION
-        - CLOUD_MODE
-        - CLI
+      - LINEAR
+      - API
+      - SLACK
+      - LOCAL
+      - SCHEDULED_AGENT
+      - WEB_APP
+      - GITHUB_ACTION
+      - CLOUD_MODE
+      - CLI
+      - JIRA
       description: |
         Source that created the run:
         - LINEAR: Created from Linear integration
@@ -2326,11 +2479,12 @@ components:
         - GITHUB_ACTION: Created from a GitHub action
         - CLOUD_MODE: Created from a Cloud Mode
         - CLI: Created from the CLI
+        - JIRA: Created from Jira integration
     RunExecutionLocation:
       type: string
       enum:
-        - LOCAL
-        - REMOTE
+      - LOCAL
+      - REMOTE
       description: |
         Where the run executed:
         - LOCAL: Executed in the user's local Oz environment
@@ -2349,6 +2503,9 @@ components:
         model_id:
           type: string
           description: LLM model to use (uses team default if not specified)
+          x-stainless-naming:
+            python:
+              method_argument: llm_id
         base_prompt:
           type: string
           description: Custom base prompt for the agent
@@ -2382,7 +2539,11 @@ components:
           type: boolean
           description: |
             Controls whether computer use is enabled for this agent.
-            If not set, defaults to false.
+            Defaults to true for Warp-hosted runs (when `worker_host` is unset or
+            set to "warp"). When `worker_host` is set (self-hosted), defaults to
+            false and requires an explicit true to enable computer use and its
+            associated Xvfb sidecar overhead.
+          x-go-type-skip-optional-pointer: false
         idle_timeout_minutes:
           type: integer
           format: int32
@@ -2392,6 +2553,7 @@ components:
             Number of minutes to keep the agent environment alive after task completion.
             If not set, defaults to 10 minutes.
             Maximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier).
+          x-go-type-skip-optional-pointer: false
         worker_host:
           type: string
           description: |
@@ -2410,11 +2572,12 @@ components:
           description: Memory stores to attach to this run.
         inference_providers:
           allOf:
-            - $ref: '#/components/schemas/InferenceProvidersConfig'
+          - $ref: '#/components/schemas/InferenceProvidersConfig'
           description: |
             Optional inference provider settings for this run. Run-level
             config takes precedence over the agent's stored config and
             the workspace's admin-configured defaults.
+          x-go-type-skip-optional-pointer: false
     SessionSharingConfig:
       type: object
       description: |
@@ -2428,8 +2591,8 @@ components:
         public_access:
           type: string
           enum:
-            - VIEWER
-            - EDITOR
+          - VIEWER
+          - EDITOR
           description: |
             Grants anyone-with-link access at the specified level to the run's
             shared session and backing conversation.
@@ -2446,16 +2609,29 @@ components:
         type:
           type: string
           enum:
-            - oz
-            - claude
-            - gemini
-            - codex
+          - oz
+          - claude
+          - gemini
+          - codex
           description: |
             The harness type identifier.
             - oz: Warp's built-in harness (default)
             - claude: Claude Code harness
             - gemini: Gemini CLI harness
             - codex: Codex CLI harness
+        model_id:
+          type: string
+          description: |
+            Model to use with a third-party harness (e.g. "claude-haiku-4-5").
+            Only applies when type is a non-oz harness; the top-level config
+            model_id targets the built-in Oz harness instead. When omitted or
+            empty, the harness uses its own default model.
+        reasoning_level:
+          type: string
+          description: |
+            Reasoning effort for harnesses that support it (e.g. Codex).
+            Only applies when type is a non-oz harness. Ignored by harnesses
+            that do not support reasoning levels.
     HarnessAuthSecrets:
       type: object
       description: |
@@ -2481,7 +2657,10 @@ components:
       properties:
         warp_id:
           type: string
-          description: Reference to a Warp shared MCP server by UUID
+          description: |
+            Reference to a Warp shared MCP server by UUID, or a well-known
+            integration MCP id (e.g. "linear") backed by the team's integration
+            connection.
         command:
           type: string
           description: Stdio transport - command to run
@@ -2514,10 +2693,10 @@ components:
         Additional extension members (e.g., `auth_url`, `provider`) may be
         present depending on the error code.
       required:
-        - type
-        - title
-        - status
-        - error
+      - type
+      - title
+      - status
+      - error
       properties:
         type:
           type: string
@@ -2528,7 +2707,7 @@ components:
             See PlatformErrorCode for the list of possible error codes.
         title:
           type: string
-          description: 'A short, human-readable summary of the problem type (RFC 7807)'
+          description: A short, human-readable summary of the problem type (RFC 7807)
         status:
           type: integer
           description: The HTTP status code for this occurrence of the problem (RFC 7807)
@@ -2554,9 +2733,9 @@ components:
           description: OpenTelemetry trace ID for debugging and support requests
     ArtifactResponse:
       oneOf:
-        - $ref: '#/components/schemas/PlanArtifactResponse'
-        - $ref: '#/components/schemas/ScreenshotArtifactResponse'
-        - $ref: '#/components/schemas/FileArtifactResponse'
+      - $ref: '#/components/schemas/PlanArtifactResponse'
+      - $ref: '#/components/schemas/ScreenshotArtifactResponse'
+      - $ref: '#/components/schemas/FileArtifactResponse'
       discriminator:
         propertyName: artifact_type
         mapping:
@@ -2567,10 +2746,10 @@ components:
       type: object
       description: Response for retrieving a plan artifact.
       required:
-        - artifact_uid
-        - artifact_type
-        - created_at
-        - data
+      - artifact_uid
+      - artifact_type
+      - created_at
+      - data
       properties:
         artifact_uid:
           type: string
@@ -2578,7 +2757,7 @@ components:
         artifact_type:
           type: string
           enum:
-            - PLAN
+          - PLAN
           description: Type of the artifact
         created_at:
           type: string
@@ -2588,12 +2767,12 @@ components:
           $ref: '#/components/schemas/PlanArtifactResponseData'
     PlanArtifactResponseData:
       type: object
-      description: 'Response data for a plan artifact, including current markdown content.'
+      description: Response data for a plan artifact, including current markdown content.
       required:
-        - document_uid
-        - notebook_uid
-        - content
-        - content_type
+      - document_uid
+      - notebook_uid
+      - content
+      - content_type
       properties:
         document_uid:
           type: string
@@ -2618,10 +2797,10 @@ components:
       type: object
       description: Response for retrieving a screenshot artifact.
       required:
-        - artifact_uid
-        - artifact_type
-        - created_at
-        - data
+      - artifact_uid
+      - artifact_type
+      - created_at
+      - data
       properties:
         artifact_uid:
           type: string
@@ -2629,7 +2808,7 @@ components:
         artifact_type:
           type: string
           enum:
-            - SCREENSHOT
+          - SCREENSHOT
           description: Type of the artifact
         created_at:
           type: string
@@ -2639,11 +2818,11 @@ components:
           $ref: '#/components/schemas/ScreenshotArtifactResponseData'
     ScreenshotArtifactResponseData:
       type: object
-      description: 'Response data for a screenshot artifact, including a signed download URL.'
+      description: Response data for a screenshot artifact, including a signed download URL.
       required:
-        - download_url
-        - expires_at
-        - content_type
+      - download_url
+      - expires_at
+      - content_type
       properties:
         download_url:
           type: string
@@ -2655,7 +2834,7 @@ components:
           description: Timestamp when the download URL expires (RFC3339)
         content_type:
           type: string
-          description: 'MIME type of the screenshot (e.g., image/png)'
+          description: MIME type of the screenshot (e.g., image/png)
         description:
           type: string
           description: Optional description of the screenshot
@@ -2663,10 +2842,10 @@ components:
       type: object
       description: Response for retrieving a file artifact.
       required:
-        - artifact_uid
-        - artifact_type
-        - created_at
-        - data
+      - artifact_uid
+      - artifact_type
+      - created_at
+      - data
       properties:
         artifact_uid:
           type: string
@@ -2674,7 +2853,7 @@ components:
         artifact_type:
           type: string
           enum:
-            - FILE
+          - FILE
           description: Type of the artifact
         created_at:
           type: string
@@ -2684,13 +2863,13 @@ components:
           $ref: '#/components/schemas/FileArtifactResponseData'
     FileArtifactResponseData:
       type: object
-      description: 'Response data for a file artifact, including a signed download URL.'
+      description: Response data for a file artifact, including a signed download URL.
       required:
-        - download_url
-        - expires_at
-        - content_type
-        - filepath
-        - filename
+      - download_url
+      - expires_at
+      - content_type
+      - filepath
+      - filename
       properties:
         download_url:
           type: string
@@ -2709,6 +2888,12 @@ components:
         filename:
           type: string
           description: Last path component of filepath
+        title:
+          type: string
+          description: |
+            Short, badge-visible label for the artifact. For recording artifacts,
+            this is the agent-authored title shown in Oz web and blocklist badges.
+            Distinct from description, which is longer and shown in detail views.
         description:
           type: string
           description: Optional description of the file
@@ -2716,13 +2901,14 @@ components:
           type: integer
           format: int64
           description: Size of the uploaded file in bytes
+          x-go-type-skip-optional-pointer: false
     AttachmentInput:
       type: object
       description: A base64-encoded file attachment to include with the prompt
       required:
-        - file_name
-        - mime_type
-        - data
+      - file_name
+      - mime_type
+      - data
       properties:
         file_name:
           type: string
@@ -2739,13 +2925,13 @@ components:
     ScheduledAgentItem:
       type: object
       required:
-        - id
-        - name
-        - cron_schedule
-        - enabled
-        - prompt
-        - created_at
-        - updated_at
+      - id
+      - name
+      - cron_schedule
+      - enabled
+      - prompt
+      - created_at
+      - updated_at
       properties:
         id:
           type: string
@@ -2755,7 +2941,7 @@ components:
           description: Human-readable name for the schedule
         cron_schedule:
           type: string
-          description: 'Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)'
+          description: Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)
         enabled:
           type: boolean
           description: Whether the schedule is currently active
@@ -2765,16 +2951,21 @@ components:
         last_spawn_error:
           type: string
           nullable: true
-          description: 'Error message from the last failed spawn attempt, if any'
+          description: Error message from the last failed spawn attempt, if any
         agent_config:
           $ref: '#/components/schemas/AmbientAgentConfig'
         agent_uid:
           type: string
           format: uuid
+          x-go-type-skip-optional-pointer: false
           description: UID of the agent that this schedule runs as
+        metadata:
+          allOf:
+          - $ref: '#/components/schemas/RunMetadata'
+          description: Custom metadata stamped onto every run spawned by this schedule
         environment:
           allOf:
-            - $ref: '#/components/schemas/CloudEnvironmentConfig'
+          - $ref: '#/components/schemas/CloudEnvironmentConfig'
           description: Resolved environment configuration (if agent_config references an environment_id)
         created_at:
           type: string
@@ -2812,15 +3003,15 @@ components:
         Request body for creating a new scheduled agent.
         Either prompt or agent_config.skill_spec or agent_config.skills is required.
       required:
-        - name
-        - cron_schedule
+      - name
+      - cron_schedule
       properties:
         name:
           type: string
           description: Human-readable name for the schedule
         cron_schedule:
           type: string
-          description: 'Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)'
+          description: Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)
         prompt:
           type: string
           description: |
@@ -2839,6 +3030,7 @@ components:
         agent_uid:
           type: string
           format: uuid
+          x-go-type-skip-optional-pointer: false
           description: |
             Agent UID to use as the execution principal for this schedule.
             Only valid for team-owned schedules.
@@ -2849,15 +3041,22 @@ components:
           description: |
             Whether to create a team-owned schedule.
             Defaults to true for users on a single team.
+          x-go-type-skip-optional-pointer: false
+        metadata:
+          allOf:
+          - $ref: '#/components/schemas/RunMetadata'
+          description: |
+            Custom metadata stamped onto every run spawned by this schedule as the run's
+            explicit metadata layer.
     UpdateScheduledAgentRequest:
       type: object
       description: |
         Request body for updating a scheduled agent.
         Either prompt or agent_config.skill_spec or agent_config.skills is required.
       required:
-        - name
-        - cron_schedule
-        - enabled
+      - name
+      - cron_schedule
+      - enabled
       properties:
         name:
           type: string
@@ -2882,15 +3081,23 @@ components:
         agent_uid:
           type: string
           format: uuid
+          x-go-type-skip-optional-pointer: false
           description: |
             Agent UID to use as the execution principal for this schedule.
             Only valid for team-owned schedules.
         agent_config:
           $ref: '#/components/schemas/AmbientAgentConfig'
+        metadata:
+          allOf:
+          - $ref: '#/components/schemas/RunMetadata'
+          description: |
+            Custom metadata stamped onto every run spawned by this schedule.
+            Updates follow full-replacement PUT semantics: omitting this field
+            clears the schedule's metadata. Changes apply only to future runs.
     ListScheduledAgentsResponse:
       type: object
       required:
-        - schedules
+      - schedules
       properties:
         schedules:
           type: array
@@ -2900,7 +3107,7 @@ components:
     DeleteScheduledAgentResponse:
       type: object
       required:
-        - success
+      - success
       properties:
         success:
           type: boolean
@@ -2918,7 +3125,7 @@ components:
           description: Optional description of the environment
         docker_image:
           type: string
-          description: 'Docker image to use (e.g., "ubuntu:latest" or "registry/repo:tag")'
+          description: Docker image to use (e.g., "ubuntu:latest" or "registry/repo:tag")
         github_repos:
           type: array
           items:
@@ -2949,12 +3156,12 @@ components:
       type: object
       description: GCP Workload Identity Federation settings
       required:
-        - project_number
-        - workload_identity_federation_pool_id
-        - workload_identity_federation_provider_id
+      - project_number
+      - workload_identity_federation_pool_id
+      - workload_identity_federation_provider_id
       externalDocs:
         description: Google documentation on Workload Identity Federation
-        url: 'https://docs.cloud.google.com/iam/docs/workload-identity-federation'
+        url: https://docs.cloud.google.com/iam/docs/workload-identity-federation
       properties:
         project_number:
           type: string
@@ -2973,9 +3180,9 @@ components:
       description: AWS IAM role assumption settings
       externalDocs:
         description: AWS documentation on IAM OIDC federation
-        url: 'https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html'
+        url: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html
       required:
-        - role_arn
+      - role_arn
       properties:
         role_arn:
           type: string
@@ -2987,11 +3194,11 @@ components:
         agent or run.
       externalDocs:
         description: AWS documentation on IAM OIDC federation
-        url: 'https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html'
+        url: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html
       properties:
         disabled:
           type: boolean
-          description: 'If true, opt out of Bedrock at this layer.'
+          description: If true, opt out of Bedrock at this layer.
         role_arn:
           type: string
           description: IAM role ARN to assume when calling Bedrock.
@@ -3001,8 +3208,8 @@ components:
     GitHubRepo:
       type: object
       required:
-        - owner
-        - repo
+      - owner
+      - repo
       properties:
         owner:
           type: string
@@ -3013,7 +3220,7 @@ components:
     ListAgentsResponse:
       type: object
       required:
-        - agents
+      - agents
       properties:
         agents:
           type: array
@@ -3023,7 +3230,7 @@ components:
     ListConnectedSelfHostedWorkersResponse:
       type: object
       required:
-        - workers
+      - workers
       properties:
         workers:
           type: array
@@ -3033,10 +3240,10 @@ components:
     ConnectedSelfHostedWorker:
       type: object
       required:
-        - worker_host
-        - connection_count
-        - connected_at
-        - last_seen_at
+      - worker_host
+      - connection_count
+      - connected_at
+      - last_seen_at
       properties:
         worker_host:
           type: string
@@ -3055,8 +3262,8 @@ components:
     AgentListItem:
       type: object
       required:
-        - name
-        - variants
+      - name
+      - variants
       properties:
         name:
           type: string
@@ -3069,11 +3276,11 @@ components:
     AgentListVariant:
       type: object
       required:
-        - id
-        - description
-        - base_prompt
-        - source
-        - environments
+      - id
+      - description
+      - base_prompt
+      - source
+      - environments
       properties:
         id:
           type: string
@@ -3108,9 +3315,9 @@ components:
     AgentListSource:
       type: object
       required:
-        - owner
-        - name
-        - skill_path
+      - owner
+      - name
+      - skill_path
       properties:
         owner:
           type: string
@@ -3130,8 +3337,8 @@ components:
     AgentListEnvironment:
       type: object
       required:
-        - uid
-        - name
+      - uid
+      - name
       properties:
         uid:
           type: string
@@ -3143,14 +3350,14 @@ components:
       type: object
       description: Ownership scope for a resource (team or personal)
       required:
-        - type
+      - type
       properties:
         type:
           type: string
           enum:
-            - User
-            - Team
-          description: 'Type of ownership ("User" for personal, "Team" for team-owned)'
+          - User
+          - Team
+          description: Type of ownership ("User" for personal, "Team" for team-owned)
         uid:
           type: string
           description: UID of the owning user or team
@@ -3181,22 +3388,22 @@ components:
         - `resource_unavailable` — Transient infrastructure issue (retryable)
         - `internal_error` — Unexpected server-side error (retryable)
       enum:
-        - insufficient_credits
-        - feature_not_available
-        - external_authentication_required
-        - not_authorized
-        - invalid_request
-        - resource_not_found
-        - budget_exceeded
-        - integration_disabled
-        - integration_not_configured
-        - operation_not_supported
-        - environment_setup_failed
-        - content_policy_violation
-        - conflict
-        - authentication_required
-        - resource_unavailable
-        - internal_error
+      - insufficient_credits
+      - feature_not_available
+      - external_authentication_required
+      - not_authorized
+      - invalid_request
+      - resource_not_found
+      - budget_exceeded
+      - integration_disabled
+      - integration_not_configured
+      - operation_not_supported
+      - environment_setup_failed
+      - content_policy_violation
+      - conflict
+      - authentication_required
+      - resource_unavailable
+      - internal_error
     RunFollowupRequest:
       type: object
       description: Request body for submitting a follow-up message to an existing run.
@@ -3213,8 +3420,8 @@ components:
     ListModelsResponse:
       type: object
       required:
-        - default_model_id
-        - models
+      - default_model_id
+      - models
       properties:
         default_model_id:
           type: string
@@ -3227,10 +3434,10 @@ components:
     ModelInfo:
       type: object
       required:
-        - id
-        - display_name
-        - provider
-        - vision_supported
+      - id
+      - display_name
+      - provider
+      - vision_supported
       properties:
         id:
           type: string
@@ -3241,10 +3448,10 @@ components:
         provider:
           type: string
           enum:
-            - OPENAI
-            - ANTHROPIC
-            - GOOGLE
-            - UNKNOWN
+          - OPENAI
+          - ANTHROPIC
+          - GOOGLE
+          - UNKNOWN
           description: The LLM provider
         vision_supported:
           type: boolean
@@ -3254,15 +3461,54 @@ components:
           description: Optional extra descriptor for the model
         reasoning_level:
           type: string
-          description: 'Reasoning level descriptor, if any (e.g. "low", "medium", "high")'
+          description: Reasoning level descriptor, if any (e.g. "low", "medium", "high")
         disable_reason:
           type: string
           enum:
-            - PROVIDER_OUTAGE
-            - OUT_OF_REQUESTS
-            - ADMIN_DISABLED
-            - REQUIRES_UPGRADE
-          description: 'If set, the model is currently unavailable for the given reason'
+          - PROVIDER_OUTAGE
+          - OUT_OF_REQUESTS
+          - ADMIN_DISABLED
+          - REQUIRES_UPGRADE
+          description: If set, the model is currently unavailable for the given reason
+    ExternalReferenceArtifactData:
+      type: object
+      description: Data for a generic external reference artifact.
+      required:
+      - reference_type
+      - url
+      properties:
+        reference_type:
+          type: string
+          maxLength: 256
+          x-oapi-codegen-extra-tags:
+            binding: required
+          description: |
+            Free-form category identifier for this reference (e.g. "linear_issue",
+            "spec_link", "jira_ticket"). Used for filtering and display.
+        url:
+          type: string
+          maxLength: 2048
+          x-oapi-codegen-extra-tags:
+            binding: required
+          description: |
+            Canonical URL for the reference. Used as the key for reverse lookups
+            ("which run produced this URL?").
+        title:
+          type: string
+          description: Optional human-readable label for the reference.
+        metadata:
+          type: object
+          additionalProperties: true
+          description: Optional category-specific extra fields.
+    RunByExternalReferenceResponse:
+      type: object
+      description: Response for a run reverse-lookup by external reference URL.
+      required:
+      - run_id
+      properties:
+        run_id:
+          type: string
+          description: The ID of the run that produced the external reference.
     AgentSkill:
       type: object
       description: |
@@ -3284,7 +3530,7 @@ components:
     ListEnvironmentsResponse:
       type: object
       required:
-        - environments
+      - environments
       properties:
         environments:
           type: array
@@ -3295,10 +3541,10 @@ components:
       type: object
       description: A cloud environment for running agents
       required:
-        - uid
-        - config
-        - last_updated
-        - setup_failed
+      - uid
+      - config
+      - last_updated
+      - setup_failed
       properties:
         uid:
           type: string
@@ -3330,7 +3576,7 @@ components:
       description: |
         Reference to a managed secret by name.
       required:
-        - name
+      - name
       properties:
         name:
           type: string
@@ -3339,9 +3585,9 @@ components:
       type: object
       description: Reference to a memory store to attach to an agent.
       required:
-        - uid
-        - access
-        - instructions
+      - uid
+      - access
+      - instructions
       properties:
         uid:
           type: string
@@ -3349,16 +3595,115 @@ components:
         access:
           type: string
           enum:
-            - read_write
-            - read_only
+          - read_write
+          - read_only
           description: Access level for the store.
         instructions:
           type: string
           description: Instructions for how the agent should use this memory store. Must not be empty.
+    MemoryStoreAttachmentResponse:
+      type: object
+      description: Memory store attached to an agent.
+      required:
+      - uid
+      - access
+      - instructions
+      - owner_type
+      - owner_uid
+      properties:
+        uid:
+          type: string
+          description: UID of the memory store.
+        access:
+          type: string
+          enum:
+          - read_write
+          - read_only
+          description: Access level for the store.
+        instructions:
+          type: string
+          description: Instructions for how the agent should use this memory store.
+        owner_type:
+          type: string
+          description: Public owner type.
+          enum:
+          - user
+          - service_account
+          - team
+        owner_uid:
+          type: string
+          description: Public UID of the user, service account, or team that owns the memory store.
+        description:
+          type: string
+          x-go-type-skip-optional-pointer: false
+          description: Optional description for the memory store.
+    AgentAutoMemoryCreateConfig:
+      type: object
+      description: Auto-memory settings for creating an agent.
+      properties:
+        enabled:
+          type: boolean
+          x-go-type-skip-optional-pointer: false
+          description: |
+            Whether to create and attach a default service-account-owned memory store for this agent.
+            Defaults to true when omitted.
+    AgentMemoryCreateConfig:
+      type: object
+      description: Memory settings for creating an agent.
+      properties:
+        auto_memory:
+          allOf:
+          - $ref: '#/components/schemas/AgentAutoMemoryCreateConfig'
+          description: Agent-owned memory settings. Defaults to enabled when omitted.
+        attached_stores:
+          type: array
+          items:
+            $ref: '#/components/schemas/MemoryStoreRef'
+          description: |
+            Existing team memory stores to attach to the agent.
+            Duplicate UIDs within a single request are rejected.
+    AgentMemoryUpdateConfig:
+      type: object
+      description: Memory settings for updating an agent.
+      properties:
+        attached_stores:
+          type: array
+          nullable: true
+          items:
+            $ref: '#/components/schemas/MemoryStoreRef'
+          description: |
+            Replacement list of attached team memory stores. Omit to leave unchanged,
+            pass an empty array to clear, or pass a non-empty array to replace.
+          x-go-type-skip-optional-pointer: false
+    AgentAutoMemoryResponse:
+      type: object
+      description: Auto-memory state for an agent.
+      required:
+      - enabled
+      properties:
+        enabled:
+          type: boolean
+          description: Whether this agent has an agent-owned memory store.
+        store:
+          $ref: '#/components/schemas/MemoryStoreAttachmentResponse'
+    AgentMemoryResponse:
+      type: object
+      description: Memory settings for an agent.
+      required:
+      - auto_memory
+      - attached_stores
+      properties:
+        auto_memory:
+          $ref: '#/components/schemas/AgentAutoMemoryResponse'
+        attached_stores:
+          type: array
+          items:
+            $ref: '#/components/schemas/MemoryStoreRef'
+          description: Team memory stores attached to the agent.
     CreateAgentRequest:
       type: object
       required:
-        - name
+      - name
       properties:
         name:
           type: string
@@ -3378,6 +3723,14 @@ components:
           description: |
             Optional default cloud environment ID for runs executed by this agent.
             The environment must be owned by the same team as the agent.
+        default_runner_uid:
+          type: string
+          nullable: true
+          description: |
+            Optional default runner UID for runs executed by this agent. When set,
+            it overrides the selected environment's default runner for runs that
+            do not specify their own `runner_id`. The editor must have View
+            permission on the referenced runner.
         secrets:
           type: array
           items:
@@ -3402,19 +3755,22 @@ components:
             Optional base model for runs executed by this agent.
         inference_providers:
           allOf:
-            - $ref: '#/components/schemas/InferenceProvidersConfig'
+          - $ref: '#/components/schemas/InferenceProvidersConfig'
           description: |
             Optional inference provider settings for this agent.
             Agent-level config takes precedence over the workspace's
             admin-configured defaults.
-        memory_stores:
-          type: array
-          items:
-            $ref: '#/components/schemas/MemoryStoreRef'
+        memory:
+          allOf:
+          - $ref: '#/components/schemas/AgentMemoryCreateConfig'
+          description: Optional memory settings for the agent.
+        mcp_servers:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/MCPServerConfig'
           description: |
-            Optional list of memory stores to attach to the agent.
-            Each store must be team-owned by the same team as the agent.
-            Duplicate UIDs within a single request are rejected.
+            Optional map of MCP server configurations by name to attach to runs executed by this agent.
+            Run-level MCP config takes precedence over this agent-level default.
         base_harness:
           type: string
           nullable: true
@@ -3422,11 +3778,17 @@ components:
             Optional default harness for runs executed by this agent.
         harness_auth_secrets:
           allOf:
-            - $ref: '#/components/schemas/HarnessAuthSecrets'
+          - $ref: '#/components/schemas/HarnessAuthSecrets'
           description: |
             Optional per-harness authentication secrets for this agent.
             Each field names a managed secret for the corresponding harness.
             Secrets are resolved at execution time from the agent's team scope.
+        on_behalf_of_enabled:
+          type: boolean
+          description: |
+            Whether runs created with this agent's API key may use the on_behalf_of
+            field to attribute runs to another team member. Defaults to false.
+            Only team admins may set this field.
     UpdateAgentRequest:
       type: object
       description: |
@@ -3443,17 +3805,28 @@ components:
           nullable: true
           description: |
             Replacement description. Omit or pass `null` to leave unchanged, or use an empty value to clear.
+          x-go-type-skip-optional-pointer: false
         prompt:
           type: string
           nullable: true
           description: |
             Replacement prompt. Omit or pass `null` to leave unchanged, or use an empty value to clear.
+          x-go-type-skip-optional-pointer: false
         environment_id:
           type: string
           nullable: true
           description: |
             Replacement default cloud environment ID. Omit or pass `null` to leave unchanged,
             or pass an empty string to clear.
+          x-go-type-skip-optional-pointer: false
+        default_runner_uid:
+          type: string
+          nullable: true
+          description: |
+            Replacement default runner UID. Omit or pass `null` to leave unchanged,
+            or pass an empty string to clear. A non-empty value must reference a
+            runner the editor can View.
+          x-go-type-skip-optional-pointer: false
         secrets:
           type: array
           nullable: true
@@ -3463,6 +3836,7 @@ components:
             Replacement list of secrets. Omit to leave unchanged, pass an
             empty array to clear, or pass a non-empty array to replace.
             Duplicate names are rejected.
+          x-go-type-skip-optional-pointer: false
         skills:
           type: array
           nullable: true
@@ -3471,54 +3845,76 @@ components:
           description: |
             Replacement list of skill specs. Omit to leave unchanged, pass an empty array
             to clear, or pass a non-empty array to replace.
+          x-go-type-skip-optional-pointer: false
         base_model:
           type: string
           nullable: true
           description: |
             Replacement base model. Omit or pass `null` to leave unchanged,
             or pass an empty string to clear.
-        memory_stores:
-          type: array
+          x-go-type-skip-optional-pointer: false
+        memory:
+          allOf:
+          - $ref: '#/components/schemas/AgentMemoryUpdateConfig'
           nullable: true
-          items:
-            $ref: '#/components/schemas/MemoryStoreRef'
+          description: Replacement memory settings for this agent.
+          x-go-type-skip-optional-pointer: false
+        mcp_servers:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/MCPServerConfig'
           description: |
-            Replacement list of memory stores. Omit to leave unchanged, pass an empty array
-            to clear, or pass a non-empty array to replace.
+            Replacement map of MCP server configurations by name. Omit to leave
+            unchanged, pass an empty object to clear, or pass a non-empty object
+            to replace. Run-level MCP config takes precedence over this agent-level
+            default.
+          x-go-type-skip-optional-pointer: false
         inference_providers:
           type: object
           allOf:
-            - $ref: '#/components/schemas/InferenceProvidersConfig'
+          - $ref: '#/components/schemas/InferenceProvidersConfig'
           nullable: true
           description: |
             Replacement inference provider settings for this agent.
             Agent-level config takes precedence over the workspace's
             admin-configured defaults. Omit or pass `null` to leave
             unchanged. Pass an empty object `{}` to clear.
+          x-go-type-skip-optional-pointer: false
         base_harness:
           type: string
           nullable: true
           description: |
             Replacement default harness. Omit or pass `null` to leave unchanged,
             or pass an empty string to clear.
+          x-go-type-skip-optional-pointer: false
         harness_auth_secrets:
           allOf:
-            - $ref: '#/components/schemas/HarnessAuthSecrets'
+          - $ref: '#/components/schemas/HarnessAuthSecrets'
           nullable: true
           description: |
             Replacement per-harness authentication secrets. Omit or pass `null`
             to leave unchanged, or pass an empty object to clear all secrets.
+          x-go-type-skip-optional-pointer: false
+        on_behalf_of_enabled:
+          type: boolean
+          nullable: true
+          description: |
+            Whether runs created with this agent's API key may use the on_behalf_of
+            field to attribute runs to another team member. Omit or pass `null` to
+            leave unchanged. Only team admins may set this field.
+          x-go-type-skip-optional-pointer: false
     AgentResponse:
       type: object
       required:
-        - uid
-        - name
-        - available
-        - created_at
-        - updated_at
-        - secrets
-        - skills
-        - memory_stores
+      - uid
+      - name
+      - available
+      - created_at
+      - updated_at
+      - secrets
+      - skills
+      - memory
+      - default_runner_uid
       properties:
         uid:
           type: string
@@ -3542,6 +3938,17 @@ components:
             1. The environment specified on the run itself
             2. The agent's default environment
             3. An empty environment
+        default_runner_uid:
+          type: string
+          description: |
+            Default runner UID for runs executed by this agent. When set, it overrides the
+            selected environment's default runner for runs that do not specify their own
+            `runner_id`. The precedence order for runner resolution is:
+            1. The runner specified on the run itself
+            2. The agent's default runner
+            3. The selected environment's default runner
+            4. The environment's legacy inline compute fields
+            5. System defaults
         available:
           type: boolean
           description: Whether this agent is within the team's plan limit and can be used for runs
@@ -3575,18 +3982,24 @@ components:
             3. The team's default model
         inference_providers:
           allOf:
-            - $ref: '#/components/schemas/InferenceProvidersConfig'
+          - $ref: '#/components/schemas/InferenceProvidersConfig'
           description: |
             The agent's stored inference provider settings. May be overridden
             by run-level config; if empty, falls back to the workspace's
             admin-configured defaults.
-        memory_stores:
-          type: array
-          items:
-            $ref: '#/components/schemas/MemoryStoreRef'
+        memory:
+          allOf:
+          - $ref: '#/components/schemas/AgentMemoryResponse'
           description: |
-            Memory stores attached to this agent.
-            Always present; empty when no stores are attached.
+            Memory settings for this agent.
+            Always present; attached_stores is empty when no team stores are attached.
+        mcp_servers:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/MCPServerConfig'
+          description: |
+            MCP server configurations attached to this agent by default.
+            Run-level MCP config takes precedence over this agent-level default.
         base_harness:
           type: string
           description: |
@@ -3596,15 +4009,20 @@ components:
             3. Oz
         harness_auth_secrets:
           allOf:
-            - $ref: '#/components/schemas/HarnessAuthSecrets'
+          - $ref: '#/components/schemas/HarnessAuthSecrets'
           description: |
             Per-harness authentication secrets configured on this agent.
             Each field names a managed secret for the corresponding harness.
             Secrets can be overridden per run.
+        on_behalf_of_enabled:
+          type: boolean
+          description: |
+            Whether runs created with this agent's API key may use the on_behalf_of
+            field to attribute runs to another team member.
     ListAgentIdentitiesResponse:
       type: object
       required:
-        - agents
+      - agents
       properties:
         agents:
           type: array
@@ -3614,11 +4032,11 @@ components:
       type: object
       description: Summary of the most recently created task for an environment
       required:
-        - id
-        - title
-        - state
-        - created_at
-        - updated_at
+      - id
+      - title
+      - state
+      - created_at
+      - updated_at
       properties:
         id:
           type: string
@@ -3640,4 +4058,4 @@ components:
           type: string
           format: date-time
           nullable: true
-          description: 'When the task started running (RFC3339), null if not yet started'
+          description: When the task started running (RFC3339), null if not yet started
diff --git a/src/content/docs/agent-platform/capabilities/computer-use-testing-and-recordings.mdx b/src/content/docs/agent-platform/capabilities/computer-use-testing-and-recordings.mdx
index b50333de7..f33754212 100644
--- a/src/content/docs/agent-platform/capabilities/computer-use-testing-and-recordings.mdx
+++ b/src/content/docs/agent-platform/capabilities/computer-use-testing-and-recordings.mdx
@@ -32,7 +32,7 @@ You don't need to ask the agent to record explicitly. Prompts like "test this ch
 
 ## How it works
 
-1. **Enable Computer Use.** The agent needs Computer Use enabled for its run. See the [Computer Use](/agent-platform/capabilities/computer-use/#enabling-computer-use) page for how to enable it via the Warp app, the CLI, or the API.
+1. **Enable Computer Use.** The agent needs Computer Use enabled for its run. See the [Computer Use](/agent-platform/capabilities/computer-use/#configuring-computer-use) page for how to configure it via the {VARS.WEB_APP}, the CLI, or the API.
 2. **Agent starts recording.** Once Computer Use is active, the agent begins a screen capture inside the sandbox. The recording is gated by your session's Computer Use approval. If you've already approved Computer Use for the run, recording starts automatically without a separate prompt.
 3. **Agent exercises the UI.** The agent takes screenshots, clicks, types, scrolls, and drives the interface. Each successful interaction is tracked: when it started, when it finished, what actions it contained, and where the cursor moved.
 4. **Agent stops and processes.** When the task is complete (or when the recording's configured time or size limit is reached), the agent stops capture. Before upload, the recording is post-processed: idle and thinking gaps are cut, leaving only the windows where real interaction happened, and action overlays are burned in so the video is annotated.
@@ -82,7 +82,7 @@ The finished recording is attached to the pull request, giving a reviewer proof
 
 ### End-to-end QA of an existing flow
 
-An agent walks through a critical user journey, such as the "New run" creation flow in the Oz web app, capturing the complete interaction.
+An agent walks through a critical user journey, such as the "New run" creation flow in the {VARS.WEB_APP}, capturing the complete interaction.
 
 Example prompt:
 ```text
@@ -91,7 +91,7 @@ Build the Oz web app and walk through the entire "New run" creation flow end to
 
 This gives you a reproducible, time-stamped clip of the flow that can be archived, diffed across releases, or shared with the team as a baseline.
 
-<DemoVideo src="/assets/agent-platform/new-run-demo.mp4" label="Agent walking through the New run creation flow in the Oz web app with Computer Use" />
+<DemoVideo src="/assets/agent-platform/new-run-demo.mp4" label={`Agent walking through the New run creation flow in the ${VARS.WEB_APP} with Computer Use`} />
 
 ### Reproducing a bug
 
diff --git a/src/content/docs/agent-platform/capabilities/computer-use.mdx b/src/content/docs/agent-platform/capabilities/computer-use.mdx
index 276383663..ae766f522 100644
--- a/src/content/docs/agent-platform/capabilities/computer-use.mdx
+++ b/src/content/docs/agent-platform/capabilities/computer-use.mdx
@@ -7,7 +7,9 @@ description: >-
   automated UI testing and validation.
 ---
 
-Computer Use is an experimental feature that enables Warp's agents to interact with desktop environments. The agent can see what's displayed on screen, click and drag, type text, use keyboard shortcuts, and perform other GUI interactions—all within a secure, isolated sandbox.
+import { VARS } from '@data/vars';
+
+Computer Use enables Warp's cloud agents to interact with desktop environments in a secure, isolated sandbox. The agent can see what's displayed on screen, click and drag, type text, use keyboard shortcuts, and perform other GUI interactions.
 
 A key use case is **testing UI changes** with a self-contained feedback loop, where the agent can verify that your code changes produce the expected visual and behavioral results without requiring manual testing.
 
@@ -25,17 +27,21 @@ Computer Use is only available in Warp's sandboxed cloud environments, not in lo
 
 ---
 
-## Enabling Computer Use
+## Configuring Computer Use
+
+Computer Use is **enabled by default** for Warp-hosted Oz cloud runs. When starting a run from the {VARS.WEB_APP}, the Computer Use checkbox is pre-selected. When calling the API without specifying `computer_use_enabled`, Computer Use is on for Warp-hosted runs; runs dispatched to [self-hosted runners](/platform/runners/) still require an explicit `computer_use_enabled: true`. You can disable or explicitly control it through the following entry points:
 
-Computer Use is **opt-in** and disabled by default. You can enable it through several entry points:
+### {VARS.WEB_APP}
 
-### Warp app settings
+In the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a>, Computer Use is enabled by default when starting a run. To change it for a specific run or agent:
 
-To enable Computer Use for [Cloud Agents](/platform/), navigate to **Settings** > **Agents** > **Warp Agent** > **Experimental** > **Computer use in Cloud Agents** and toggle to enable.
+* **New agent runs** - Deselect **Enable computer use** when starting a new agent run
+* **Scheduled agent runs** - Configure **Enable computer use** in the scheduled agent settings
+* **Integrations** - Configure **Enable computer use** for Slack, Linear, and other integration-triggered agents
 
 ### CLI
 
-When running agents in the cloud via the [CLI](/reference/cli/), use flags to control Computer Use per run:
+When running agents in the cloud via the [{VARS.WARP_AGENT_CLI}](/reference/cli/), use flags to override the default per run:
 
 ```bash
 oz agent run-cloud --computer-use --prompt "<task>"
@@ -44,7 +50,16 @@ oz agent run-cloud --no-computer-use --prompt "<task>"
 
 ### API
 
-When calling the Warp API to create agent runs, include the `computer_use_enabled` field in your request:
+When calling the Warp API to create agent runs, computer use is **enabled by default for Warp-hosted runs** when `computer_use_enabled` is omitted. The `worker_host` field determines this: when `worker_host` is unset or set to `"warp"`, computer use defaults to enabled; when `worker_host` is set to any other value (a self-hosted runner endpoint), computer use defaults to disabled — pass `computer_use_enabled: true` to enable it. To disable computer use explicitly for Warp-hosted runs, set `computer_use_enabled` to `false`:
+
+```json
+{
+  "prompt": "Build a button component that matches this design, then test it in the browser",
+  "computer_use_enabled": false
+}
+```
+
+Explicit `true` is also accepted and behaves the same as omitting the field:
 
 ```json
 {
@@ -56,13 +71,13 @@ When calling the Warp API to create agent runs, include the `computer_use_enable
 
 For full API documentation, see the [Oz API & SDK](/reference/api-and-sdk/) reference.
 
-### Web App
+### Warp desktop app
 
-In the Warp web app, you can enable or disable Computer Use for:
+For cloud agent conversations started from the Warp desktop app, Computer Use can be toggled independently of the web UI and API defaults. The toggle is off by default in released builds and must be enabled manually. In the Warp app, navigate to **Settings** > **Agents** > **Warp Agent** > **Experimental** > **Computer use in Cloud Agents** to enable or disable Computer Use for cloud agents initiated from the desktop.
 
-* **New agent runs** - Configure Computer Use when starting a new agent run from the web app
-* **Scheduled agent runs** - Enable Computer Use for scheduled agents managed from the web app
-* **Integrations** - Configure Computer Use for Slack, Linear, and other integration-triggered agents
+:::note
+This toggle applies only to cloud runs started from the Warp desktop app. Cloud runs started via the {VARS.WEB_APP} or API have Computer Use enabled by default regardless of this setting.
+:::
 
 ---
 
@@ -92,7 +107,7 @@ For a full explanation of the recording pipeline, what the finished video contai
 
 ## Security considerations
 
-Computer Use is an experimental feature with unique security considerations. These risks are heightened when interacting with the internet.
+Computer Use operates inside a sandboxed cloud environment and has unique security considerations. These risks are heightened when interacting with the internet.
 
 To minimize risks when using Computer Use: