diff --git a/.agents/skills/sync-openapi-spec/references/sync-policy.md b/.agents/skills/sync-openapi-spec/references/sync-policy.md
index b0ba9a04..2c36c72e 100644
--- a/.agents/skills/sync-openapi-spec/references/sync-policy.md
+++ b/.agents/skills/sync-openapi-spec/references/sync-policy.md
@@ -12,14 +12,69 @@ This skill is the manual fallback for the same job, so its output has to match t
 
 `scripts/sync_openapi.py` applies these rules, top-down:
 
-1. Drop every operation marked `x-internal: true`, and drop a path entirely when every one of its operations is internal.
+1. Recursively drop every object marked `x-internal: true`, wherever it
+   appears in the tree — a path operation, a query/path parameter, a
+   schema property, a whole schema, a tag entry, and so on — not only
+   top-level path operations.
 2. Drop every tag listed in `EXCLUDED_TAGS`.
 3. Drop every path whose tags are a subset of `EXCLUDED_TAGS`, plus every path listed explicitly in `EXCLUDED_PATHS` or matching a prefix in `EXCLUDED_PATH_PREFIXES`.
 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.).
+6. Recursively strip every key in `STRIP_FLAGS` from whatever survives
+   steps 1-5, wherever it appears in the tree (operations, schemas,
+   individual properties, parameters).
 
 Rule 1 mirrors warp-server's own filter, so a surface the server team marks private stays private here without anyone having to maintain a matching allowlist entry.
 
+## `x-internal` deletes the whole marked object, not just the flag (`_prune_internal`)
+
+`x-internal: true` mirrors openapi-format's `flagValues` semantics in
+warp-server's filter: the entire object bearing the marker is deleted, not
+just the `x-internal` key on it. An earlier version of this script only
+applied that rule to top-level path operations (`strip_internal_operations`)
+and left every other marked object's `x-internal` key to be stripped later
+by the `STRIP_FLAGS` pass (rule 6 above). Stripping the key without deleting
+the object it was marking leaves the object itself — now unmarked — in the
+published spec. This let several server-internal fields leak through: the
+`factory_uid` and `automation_id` query parameters on `GET /agent/runs`, and
+the `factory_uid`/`agent_type` properties on `CreateAgentRequest`,
+`UpdateAgentRequest`, and `AgentResponse`.
+
+`_prune_internal` now runs first, before any other rule, and walks the
+entire source tree deleting every marked object outright: a schema property
+under `properties`, an item in a `parameters` array, a whole schema in
+`components.schemas`, and so on, in addition to the path operations rule 1
+already covered. `STRIP_FLAGS` (rule 6) then only has to clean up the
+`x-internal` key on anything that rule 1 doesn't fully own removing (there
+is normally nothing left, since every `x-internal: true` object is deleted
+outright) plus the other seven implementation-only extensions.
+
+## Implementation-only extensions are stripped everywhere (`STRIP_FLAGS`)
+
+`STRIP_FLAGS` mirrors the `stripFlags` list in
+`warp-server/public_api/public-openapi-filter.yaml` verbatim: `x-internal`,
+`x-enum-varnames`, `x-go-type`, `x-go-type-import`,
+`x-go-type-skip-optional-pointer`, `x-oapi-codegen-extra-tags`,
+`x-stainless-deprecation-message`, and `x-stainless-naming`. These
+extensions are useful for server/SDK code generation (oapi-codegen,
+Stainless) but carry no meaning for a docs reader, so none of them may
+reach the published Scalar reference.
+
+An earlier version of this script only removed `x-internal` from
+top-level operation objects (the key that decides whether to drop the
+operation entirely). It never stripped the *other* six keys, and it never
+walked into schemas, so implementation-only markers on component schemas
+and their properties — `x-go-type-skip-optional-pointer` and
+`x-stainless-deprecation-message` in particular — leaked into the
+published copy verbatim. `_strip_flags` now walks the entire regenerated
+tree after filtering and removes every `STRIP_FLAGS` key it finds,
+regardless of nesting depth, matching `generate-public-openapi`'s own
+post-generation check that no `x-*` key remains in warp-server's
+published copy.
+
+When warp-server adds a new entry to its `stripFlags` list, add the same
+key to `STRIP_FLAGS` here so the two filters stay in lockstep.
+
 ## Excluded tags
 
 ### `memory_stores` and `memory`
diff --git a/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py b/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py
index 12099c10..7ef73d01 100644
--- a/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py
+++ b/.agents/skills/sync-openapi-spec/scripts/sync_openapi.py
@@ -12,6 +12,9 @@
   * paths listed in EXCLUDED_PATHS are removed
   * components/schemas is pruned to only schemas reachable from the
     surviving paths via $ref walking
+  * every key in STRIP_FLAGS (implementation-only extensions such as
+    ``x-go-type`` and ``x-stainless-naming``) is removed recursively from
+    whatever survives the filtering above, wherever it appears in the tree
   * the regenerated spec is validated for unresolved $refs before
     being written; apply will refuse to write a broken spec
 
@@ -20,7 +23,9 @@
 release pipeline publishes the spec. Honoring the same marker here keeps this
 script from publishing a surface the server team has explicitly marked private,
 instead of relying only on a hand-maintained tag allowlist that goes stale
-whenever a new private tag appears.
+whenever a new private tag appears. STRIP_FLAGS mirrors that same filter's
+``stripFlags`` list, so implementation-only extensions never reach the
+published docs copy either.
 
 Modes:
   diff       Print structural drift between source and target. Exits 1
@@ -59,6 +64,24 @@
 # `flagValues: [x-internal: true]` in warp-server/public_api/public-openapi-filter.yaml.
 INTERNAL_MARKER = "x-internal"
 
+# Implementation-only OpenAPI extensions that must never reach the published
+# docs copy. Mirrors `stripFlags` in
+# warp-server/public_api/public-openapi-filter.yaml: these keys are useful for
+# server/SDK code generation (oapi-codegen, Stainless) but are stripped
+# unconditionally from every remaining object, not just top-level operations.
+STRIP_FLAGS: frozenset[str] = frozenset(
+    {
+        "x-internal",
+        "x-enum-varnames",
+        "x-go-type",
+        "x-go-type-import",
+        "x-go-type-skip-optional-pointer",
+        "x-oapi-codegen-extra-tags",
+        "x-stainless-deprecation-message",
+        "x-stainless-naming",
+    }
+)
+
 # Path-item keys that are HTTP operations rather than shared path metadata.
 HTTP_METHODS: frozenset[str] = frozenset(
     {"get", "put", "post", "delete", "options", "head", "patch", "trace"}
@@ -156,6 +179,35 @@ def _is_internal_operation(operation: Any) -> bool:
     return isinstance(operation, dict) and operation.get(INTERNAL_MARKER) is True
 
 
+def _prune_internal(node: Any) -> Any:
+    """Recursively drop any object marked ``x-internal: true``, then recurse
+    into whatever remains.
+
+    Mirrors openapi-format's ``flagValues: [x-internal: true]`` semantics
+    (warp-server's ``public_api/public-openapi-filter.yaml``): the entire
+    marked node is deleted, not just the marker key. This catches internal
+    schema properties (e.g. ``factory_uid``, ``agent_type``) and internal
+    parameters (e.g. the ``automation_id`` query parameter) wherever they
+    appear in the tree — not only the top-level path operations that
+    ``strip_internal_operations`` inspects. Stripping only the marker key
+    (see ``_strip_flags``) would otherwise leave the internal object itself,
+    just unmarked, in the published spec.
+    """
+    if isinstance(node, dict):
+        return {
+            key: _prune_internal(value)
+            for key, value in node.items()
+            if not _is_internal_operation(value)
+        }
+    if isinstance(node, list):
+        return [
+            _prune_internal(item)
+            for item in node
+            if not _is_internal_operation(item)
+        ]
+    return node
+
+
 def strip_internal_operations(path_item: dict[str, Any]) -> dict[str, Any]:
     """Return ``path_item`` without any operation marked ``x-internal: true``.
 
@@ -191,6 +243,25 @@ def _should_keep_path(path: str, path_item: dict[str, Any]) -> bool:
     return True
 
 
+def _strip_flags(node: Any) -> Any:
+    """Recursively remove every key in ``STRIP_FLAGS`` from ``node``.
+
+    These extensions can appear anywhere in the spec (operations, schemas,
+    individual properties, parameters), not only on the operation objects
+    that ``strip_internal_operations`` already inspects, so this walks the
+    entire tree rather than a fixed set of levels.
+    """
+    if isinstance(node, dict):
+        return {
+            key: _strip_flags(value)
+            for key, value in node.items()
+            if key not in STRIP_FLAGS
+        }
+    if isinstance(node, list):
+        return [_strip_flags(item) for item in node]
+    return node
+
+
 def _collect_refs(node: Any, refs: set[str]) -> None:
     """Recursively collect every component schema name referenced from ``node``.
 
@@ -281,6 +352,11 @@ def visit(node: Any, path: str) -> None:
 
 def transform(source: dict[str, Any]) -> dict[str, Any]:
     """Produce the docs subset of the given source spec."""
+    # Drop every x-internal-marked object (schema properties, parameters,
+    # operations, tags, ...) before anything else, so a downstream pass never
+    # sees an internal node it would otherwise have to know how to filter.
+    source = _prune_internal(source)
+
     out: dict[str, Any] = {}
 
     for top_key in ("openapi", "info", "servers"):
@@ -324,7 +400,7 @@ def transform(source: dict[str, Any]) -> dict[str, Any]:
     if out_components:
         out["components"] = out_components
 
-    return out
+    return _strip_flags(out)
 
 
 # ---------------------------------------------------------------------------
@@ -440,6 +516,20 @@ def _self_test() -> int:
                 "post": {
                     "tags": ["agent"],
                     "operationId": "runAgent",
+                    "x-stainless-deprecation-message": "use /agent/runs instead",
+                    "parameters": [
+                        {
+                            "name": "conversation_id",
+                            "in": "query",
+                            "schema": {"type": "string"},
+                        },
+                        {
+                            "name": "factory_uid",
+                            "in": "query",
+                            "x-internal": True,
+                            "schema": {"type": "string"},
+                        },
+                    ],
                     "requestBody": {
                         "content": {
                             "application/json": {
@@ -487,6 +577,8 @@ def _self_test() -> int:
             "schemas": {
                 "RunReq": {
                     "type": "object",
+                    "x-go-type": "models.RunReq",
+                    "x-go-type-import": {"path": "warp.dev/warp-server/models"},
                     "properties": {
                         "config": {"$ref": "#/components/schemas/Config"}
                     },
@@ -504,9 +596,22 @@ def _self_test() -> int:
                                 {"type": "object"},
                             ]
                         },
+                        "legacy_mode": {
+                            "type": "string",
+                            "x-go-type-skip-optional-pointer": True,
+                            "x-oapi-codegen-extra-tags": {"json": "legacy_mode,omitempty"},
+                        },
+                        "factory_agent_type": {
+                            "allOf": [{"$ref": "#/components/schemas/Mode"}],
+                            "x-internal": True,
+                        },
                     },
                 },
-                "Mode": {"type": "string"},
+                "Mode": {
+                    "type": "string",
+                    "x-enum-varnames": ["ModeFast", "ModeSlow"],
+                    "x-stainless-naming": {"typescript": {"type": "Mode"}},
+                },
                 "RunResp": {"type": "object"},
                 "MSItem": {"type": "object"},  # only referenced by dropped path
                 "Followup": {"type": "object"},
@@ -533,6 +638,33 @@ def _self_test() -> int:
     ref_errors = _validate_output(out)
     assert not ref_errors, f"unexpected unresolved refs: {ref_errors}"
 
+    # Implementation-only extensions must never survive into the output,
+    # regardless of whether they sit on an operation, a schema, or a nested
+    # property — mirrors warp-server's `stripFlags` filter.
+    dumped = yaml.safe_dump(out)
+    for flag in STRIP_FLAGS:
+        assert flag not in dumped, f"{flag} leaked into the regenerated spec"
+    # The objects that carried those flags must otherwise survive intact.
+    assert out["paths"]["/agent/run"]["post"]["operationId"] == "runAgent"
+    assert out["components"]["schemas"]["RunReq"]["type"] == "object"
+    assert out["components"]["schemas"]["Config"]["properties"]["legacy_mode"][
+        "type"
+    ] == "string"
+
+    # An x-internal-marked object must be dropped entirely, not just have its
+    # marker key stripped — covers an internal query parameter and an
+    # internal schema property, alongside the surviving public sibling in
+    # each case.
+    run_params = {
+        p["name"] for p in out["paths"]["/agent/run"]["post"]["parameters"]
+    }
+    assert run_params == {"conversation_id"}, f"unexpected parameters: {run_params}"
+    config_props = set(out["components"]["schemas"]["Config"]["properties"].keys())
+    assert "factory_agent_type" not in config_props, (
+        f"internal property survived: {config_props}"
+    )
+    assert "legacy_mode" in config_props, f"public property dropped: {config_props}"
+
     print("self-test: OK")
     return 0
 
diff --git a/developers/agent-api-openapi.yaml b/developers/agent-api-openapi.yaml
index 6dac974c..0d50c00d 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,194 @@ 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. Passing the literal value
+          `empty-environment` matches runs with no environment configured,
+          rather than omitting the parameter, which applies no environment
+          filter at all. `empty-environment` can never collide with a real
+          environment ID: every environment ID is exactly 22 characters
+          drawn from `[A-Za-z0-9]`, while this sentinel contains a hyphen
+          and is a different length.
+        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 +482,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 +588,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 +636,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 +646,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 +682,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 +695,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 +708,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 +769,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 +780,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 +836,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 +844,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 +901,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 +935,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 +959,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 +981,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/schedules/{scheduleId}':
+  /agent/schedules/{scheduleId}:
     get:
       summary: Get scheduled agent details
       description: |
@@ -913,16 +989,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 +1037,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 +1090,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 +1131,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 +1179,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 +1187,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 +1237,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 +1283,9 @@ paths:
         currently disabled (and why).
       operationId: listModels
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       responses:
         '200':
           description: List of available models
@@ -1229,25 +1305,30 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/artifacts/{artifactUid}':
+  /agent/artifacts/{artifactUid}:
     get:
       summary: Get artifact details
       description: |
         Retrieve an artifact by its UUID. For downloadable file-like artifacts,
         returns a time-limited signed download URL. For plan artifacts, returns
         the current plan content inline.
+
+        Public artifacts can be read without authentication; private artifacts
+        require the caller to be authenticated and authorized. Anonymous reads
+        of public file artifacts omit the `filepath` field.
       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
@@ -1262,13 +1343,13 @@ paths:
               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 artifact
+          description: No permission to access private artifact
           content:
             application/json:
               schema:
@@ -1279,50 +1360,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 +1429,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 +1446,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 +1458,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 +1477,10 @@ paths:
         and may be used for runs.
       operationId: listAgents
       tags:
-        - agent
+      - agent
       security:
-        - bearerAuth: []
+      - bearerAuth: []
+      parameters: []
       responses:
         '200':
           description: List of agents
@@ -1394,7 +1489,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 +1512,65 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-  '/agent/identities/{uid}':
+  /agent/runs/{runId}/scores:
+    post:
+      summary: Report evaluation scores for a run
+      description: |
+        Report one or more evaluation verdicts for a run. Called by the judge run
+        that was dispatched to score this run, authenticating with that judge
+        run's API key. Each verdict is processed independently: the response
+        reports per-verdict acceptance, and a rejected verdict does not block the
+        others. Reporting a subset of the run's evaluations is valid.
+      operationId: reportRunScores
+      tags:
+      - agent
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: runId
+        in: path
+        description: The run being scored
+        required: true
+        schema:
+          type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ReportRunScoresRequest'
+      responses:
+        '200':
+          description: Every reported verdict was accepted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReportRunScoresResponse'
+        '206':
+          description: The request was well-formed but at least one verdict was rejected; inspect each result's status and error before deciding whether to resubmit
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReportRunScoresResponse'
+        '400':
+          description: Malformed request body
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /agent/identities/{uid}:
     get:
       summary: Retrieve an agent
       description: |
@@ -1426,16 +1579,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 +1620,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 +1656,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 +1680,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
@@ -1621,7 +1774,16 @@ components:
           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: |
@@ -1639,17 +1801,35 @@ components:
           description: |
             Optional run ID of the parent that spawned this run.
             Used for orchestration hierarchies.
+            The parent run must exist and be visible to the caller; otherwise the
+            request is rejected with a 400. Child runs are also subject to the
+            server's maximum orchestration depth, and requests that would exceed
+            it are rejected with a 400.
         interactive:
           type: boolean
           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
@@ -1671,15 +1851,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 +1870,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
@@ -1726,7 +1906,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 +1928,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 +1943,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,7 +1967,7 @@ components:
       type: object
       description: Response body for listing run timeline events.
       required:
-        - events
+      - events
       properties:
         events:
           type: array
@@ -1789,10 +1977,10 @@ components:
       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 +1991,7 @@ components:
         execution_id:
           type: integer
           format: int64
-          description: 'Run execution associated with this event, when available.'
+          description: Run execution associated with this event, when available.
         event_type:
           $ref: '#/components/schemas/AIRunTimelineEventType'
         occurred_at:
@@ -1818,18 +2006,22 @@ components:
       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 +2034,9 @@ components:
     ConversationStep:
       type: object
       required:
-        - id
-        - messages
-        - steps
+      - id
+      - messages
+      - steps
       properties:
         id:
           type: string
@@ -1876,8 +2068,8 @@ components:
     ConversationMessage:
       type: object
       required:
-        - role
-        - content
+      - role
+      - content
       properties:
         message_ids:
           type: array
@@ -1886,7 +2078,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 +2093,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 +2113,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 +2130,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 +2169,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 +2177,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 +2208,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 +2228,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 +2240,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 +2280,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 +2298,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 +2316,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 +2334,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 +2355,8 @@ components:
     PullRequestArtifactData:
       type: object
       required:
-        - url
-        - branch
+      - url
+      - branch
       properties:
         url:
           type: string
@@ -2156,8 +2368,8 @@ components:
     ScreenshotArtifactData:
       type: object
       required:
-        - artifact_uid
-        - mime_type
+      - artifact_uid
+      - mime_type
       properties:
         artifact_uid:
           type: string
@@ -2171,10 +2383,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 +2397,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
@@ -2199,9 +2417,9 @@ components:
       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 +2433,7 @@ components:
     PageInfo:
       type: object
       required:
-        - has_next_page
+      - has_next_page
       properties:
         has_next_page:
           type: boolean
@@ -2229,7 +2447,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
@@ -2242,6 +2460,17 @@ components:
             Whether the error is transient and the client may retry by submitting
             a new run. Only present on terminal error states. When false, retrying
             without addressing the underlying cause will not succeed.
+        session_debug_until:
+          type: string
+          format: date-time
+          description: |
+            When a failed run's shared session stops being held open for debugging.
+            Only present while that window is open.
+
+            The window is an idle window owned by the agent process: activity in the
+            session pushes this deadline out. The agent republishes it periodically
+            rather than on every keystroke, so the value can lag the true deadline by
+            up to a throttle interval, and always in the conservative direction.
     RequestUsage:
       type: object
       description: Resource usage information for the run
@@ -2249,23 +2478,41 @@ components:
         inference_cost:
           type: number
           format: double
-          description: Cost of LLM inference for the run
+          description: Credits consumed by LLM inference for the run
         compute_cost:
           type: number
           format: double
-          description: Cost of compute resources for the run
+          description: Credits consumed by compute resources for the run
         platform_cost:
           type: number
           format: double
-          description: Cost of platform usage for the run
+          description: Credits consumed by platform usage for the run
+        inference_cost_usd:
+          type: number
+          format: double
+          description: |
+            inference_cost in US dollars, converted at a fixed rate. An
+            approximate cost, not a billed amount.
+        compute_cost_usd:
+          type: number
+          format: double
+          description: |
+            compute_cost in US dollars, converted at a fixed rate. An
+            approximate cost, not a billed amount.
+        platform_cost_usd:
+          type: number
+          format: double
+          description: |
+            platform_cost in US dollars, converted at a fixed rate. An
+            approximate cost, not a billed amount.
     RunCreatorInfo:
       type: object
       properties:
         type:
           type: string
           enum:
-            - user
-            - service_account
+          - user
+          - service_account
           description: Type of the creator principal
         uid:
           type: string
@@ -2283,15 +2530,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 +2553,22 @@ 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
+      - SELF_IMPROVEMENT
+      - GITHUB_WEBHOOK
+      - GITLAB_WEBHOOK
+      - AUTOFIX
+      - RUN_SCORER
+      - ORCHESTRATION
       description: |
         Source that created the run:
         - LINEAR: Created from Linear integration
@@ -2326,11 +2580,18 @@ 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
+        - SELF_IMPROVEMENT: Created by Warp's self-improvement pipeline
+        - GITHUB_WEBHOOK: Created from a GitHub webhook event
+        - GITLAB_WEBHOOK: Created from a GitLab webhook event
+        - AUTOFIX: Created by Warp's autofix pipeline
+        - RUN_SCORER: Created by Warp's run-scoring judge
+        - ORCHESTRATION: Created as a child run by the orchestration layer (parent_run_id set)
     RunExecutionLocation:
       type: string
       enum:
-        - LOCAL
-        - REMOTE
+      - LOCAL
+      - REMOTE
       description: |
         Where the run executed:
         - LOCAL: Executed in the user's local Oz environment
@@ -2355,6 +2616,14 @@ components:
         environment_id:
           type: string
           description: UID of the environment to run the agent in
+        runner_id:
+          type: string
+          description: |
+            UID of the runner providing the run's compute (platform, instance
+            shape, and setup commands). When omitted on a request, the runner is
+            resolved at run creation from the agent's default runner, then the
+            environment's default runner, and the resolved UID is recorded on
+            the run.
         skill_spec:
           type: string
           description: |
@@ -2382,8 +2651,7 @@ components:
           type: boolean
           description: |
             Controls whether computer use is enabled for this agent.
-            If not set, defaults to true for runs on Warp's built-in harness
-            and false for third-party harnesses.
+            If not set, defaults to true.
         idle_timeout_minutes:
           type: integer
           format: int32
@@ -2411,11 +2679,30 @@ 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.
+        credential_strategy:
+          type: string
+          nullable: true
+          enum:
+          - CREATOR
+          - EXECUTOR
+          description: |
+            Controls which principal's credentials are used when the platform mints
+            tokens (e.g. GitHub or GitLab OAuth tokens) on behalf of this run.
+            - EXECUTOR (default when unset): credentials are sourced from the run's
+              execution principal. For agent principals this produces a
+              GitHub App installation token; for user principals this produces their
+              personal OAuth token.
+            - CREATOR: credentials are always sourced from the run creator,
+              regardless of the execution principal. Useful when a service account
+              executes the run but Git operations should authenticate as the human
+              who triggered it.
+            When unset, behavior is identical to EXECUTOR and no additional
+            pre-flight validation is performed.
     SessionSharingConfig:
       type: object
       description: |
@@ -2429,8 +2716,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.
@@ -2443,20 +2730,37 @@ components:
       description: |
         Specifies which execution harness to use for the agent run.
         Default (nil/empty) uses Warp's built-in harness.
+        When stored as a named agent's default (create/update agent identity),
+        this field replaces the deprecated base_harness/base_model pair: a
+        non-oz type here requires the agent's base_model to be empty, since
+        the two describe mutually exclusive default models.
       properties:
         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: |
@@ -2482,7 +2786,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
@@ -2515,10 +2822,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
@@ -2529,7 +2836,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)
@@ -2553,11 +2860,18 @@ components:
         trace_id:
           type: string
           description: OpenTelemetry trace ID for debugging and support requests
+        provider:
+          type: string
+          description: External provider that requires authorization, such as `linear`.
+        auth_url:
+          type: string
+          format: uri
+          description: URL where the caller can reconnect the external provider.
     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:
@@ -2568,10 +2882,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
@@ -2579,7 +2893,7 @@ components:
         artifact_type:
           type: string
           enum:
-            - PLAN
+          - PLAN
           description: Type of the artifact
         created_at:
           type: string
@@ -2589,12 +2903,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
@@ -2619,10 +2933,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
@@ -2630,7 +2944,7 @@ components:
         artifact_type:
           type: string
           enum:
-            - SCREENSHOT
+          - SCREENSHOT
           description: Type of the artifact
         created_at:
           type: string
@@ -2640,11 +2954,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
@@ -2656,7 +2970,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
@@ -2664,10 +2978,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
@@ -2675,7 +2989,7 @@ components:
         artifact_type:
           type: string
           enum:
-            - FILE
+          - FILE
           description: Type of the artifact
         created_at:
           type: string
@@ -2685,13 +2999,12 @@ 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
+      - filename
       properties:
         download_url:
           type: string
@@ -2706,10 +3019,18 @@ components:
           description: MIME type of the uploaded file
         filepath:
           type: string
-          description: Conversation-relative filepath for the uploaded file
+          description: |
+            Conversation-relative filepath for the uploaded file. Omitted for
+            anonymous reads of public artifacts.
         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
@@ -2721,9 +3042,9 @@ components:
       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
@@ -2740,13 +3061,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
@@ -2756,7 +3077,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
@@ -2766,16 +3087,20 @@ 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
           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
@@ -2813,15 +3138,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: |
@@ -2850,15 +3175,21 @@ components:
           description: |
             Whether to create a team-owned schedule.
             Defaults to true for users on a single team.
+        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
@@ -2888,10 +3219,17 @@ components:
             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
@@ -2901,7 +3239,7 @@ components:
     DeleteScheduledAgentResponse:
       type: object
       required:
-        - success
+      - success
       properties:
         success:
           type: boolean
@@ -2919,7 +3257,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:
@@ -2932,6 +3270,24 @@ components:
           description: Shell commands to run during environment setup
         providers:
           $ref: '#/components/schemas/ProvidersConfig'
+        failure_session_retention_minutes:
+          type: integer
+          nullable: true
+          minimum: 1
+          maximum: 60
+          description: |
+            When set (1–60 minutes), a failed run using this environment keeps its session open
+            for this many minutes so it can be inspected. null or absent means immediate teardown
+            (disabled by default).
+
+            The window is an idle window held open by the agent process itself: working in the
+            session pushes the deadline out, so a session in active use is not torn down
+            mid-debug. It ends early if the run's sandbox reaches its own deadline first.
+
+            This policy applies to future failures of runs using this environment; it does not
+            change the window a currently-failed run was already started with. Opting in keeps
+            injected environment data (including secrets) alive and incurs compute usage for as
+            long as the session is held open.
     ProvidersConfig:
       type: object
       description: Optional cloud provider configurations for automatic auth
@@ -2950,12 +3306,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
@@ -2974,9 +3330,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
@@ -2988,11 +3344,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.
@@ -3002,8 +3358,8 @@ components:
     GitHubRepo:
       type: object
       required:
-        - owner
-        - repo
+      - owner
+      - repo
       properties:
         owner:
           type: string
@@ -3014,7 +3370,7 @@ components:
     ListAgentsResponse:
       type: object
       required:
-        - agents
+      - agents
       properties:
         agents:
           type: array
@@ -3024,7 +3380,7 @@ components:
     ListConnectedSelfHostedWorkersResponse:
       type: object
       required:
-        - workers
+      - workers
       properties:
         workers:
           type: array
@@ -3034,10 +3390,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
@@ -3056,8 +3412,8 @@ components:
     AgentListItem:
       type: object
       required:
-        - name
-        - variants
+      - name
+      - variants
       properties:
         name:
           type: string
@@ -3070,11 +3426,11 @@ components:
     AgentListVariant:
       type: object
       required:
-        - id
-        - description
-        - base_prompt
-        - source
-        - environments
+      - id
+      - description
+      - base_prompt
+      - source
+      - environments
       properties:
         id:
           type: string
@@ -3109,9 +3465,9 @@ components:
     AgentListSource:
       type: object
       required:
-        - owner
-        - name
-        - skill_path
+      - owner
+      - name
+      - skill_path
       properties:
         owner:
           type: string
@@ -3131,8 +3487,8 @@ components:
     AgentListEnvironment:
       type: object
       required:
-        - uid
-        - name
+      - uid
+      - name
       properties:
         uid:
           type: string
@@ -3144,14 +3500,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
@@ -3182,22 +3538,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.
@@ -3214,8 +3570,8 @@ components:
     ListModelsResponse:
       type: object
       required:
-        - default_model_id
-        - models
+      - default_model_id
+      - models
       properties:
         default_model_id:
           type: string
@@ -3228,10 +3584,10 @@ components:
     ModelInfo:
       type: object
       required:
-        - id
-        - display_name
-        - provider
-        - vision_supported
+      - id
+      - display_name
+      - provider
+      - vision_supported
       properties:
         id:
           type: string
@@ -3242,10 +3598,10 @@ components:
         provider:
           type: string
           enum:
-            - OPENAI
-            - ANTHROPIC
-            - GOOGLE
-            - UNKNOWN
+          - OPENAI
+          - ANTHROPIC
+          - GOOGLE
+          - UNKNOWN
           description: The LLM provider
         vision_supported:
           type: boolean
@@ -3255,15 +3611,50 @@ 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
+          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
+          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: |
@@ -3285,7 +3676,7 @@ components:
     ListEnvironmentsResponse:
       type: object
       required:
-        - environments
+      - environments
       properties:
         environments:
           type: array
@@ -3296,10 +3687,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
@@ -3331,7 +3722,7 @@ components:
       description: |
         Reference to a managed secret by name.
       required:
-        - name
+      - name
       properties:
         name:
           type: string
@@ -3340,9 +3731,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
@@ -3350,16 +3741,187 @@ 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
+          description: Optional description for the memory store.
+    AgentAutoMemoryCreateConfig:
+      type: object
+      description: Auto-memory settings for creating an agent.
+      properties:
+        enabled:
+          type: boolean
+          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.
+    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.
+    AgentCredentialStrategy:
+      type: string
+      description: |
+        Default credential strategy for runs executed by a named agent.
+        - EXECUTOR: runs authenticate with the named agent's own credentials
+          (e.g. a GitHub App installation token for the agent's team).
+        - CREATOR: runs authenticate with the credentials of the principal
+          that created the run.
+        Unlike the factory default, an agent may leave this unset. The
+        strategy applied to a run is resolved in this order: the run's
+        config.credential_strategy, then the agent's default, then the
+        factory's default for factory-seeded agents, and finally EXECUTOR.
+        The inherited strategy is validated at run creation time (the required
+        credential must be mintable), like an explicit run-level value.
+      enum:
+      - CREATOR
+      - EXECUTOR
+    ReportedRunScore:
+      type: object
+      required:
+      - scorer_id
+      properties:
+        scorer_id:
+          type: integer
+          description: The evaluation this verdict belongs to
+        classification:
+          type: string
+          description: |
+            The chosen classification. Must exactly match one of the allowed
+            label values captured when the evaluation was dispatched. Ignored
+            when `failed` is true.
+        reason:
+          type: string
+          description: |
+            Optional judge reasoning. Stored outside the database and truncated
+            beyond 8KB; a storage failure does not reject the verdict.
+        failed:
+          type: boolean
+          description: |
+            True when the judge could not evaluate this evaluation. Failed
+            verdicts are accepted but record no score.
+    ReportRunScoresRequest:
+      type: object
+      required:
+      - results
+      properties:
+        results:
+          type: array
+          minItems: 1
+          items:
+            $ref: '#/components/schemas/ReportedRunScore'
+    ReportedRunScoreOutcome:
+      type: object
+      required:
+      - scorer_id
+      - status
+      properties:
+        scorer_id:
+          type: integer
+          description: The evaluation this outcome belongs to
+        status:
+          type: string
+          description: 'Whether the verdict was recorded: "accepted" or "rejected"'
+        error:
+          type: string
+          description: Why the verdict was rejected; absent when accepted
+    ReportRunScoresResponse:
+      type: object
+      required:
+      - results
+      properties:
+        results:
+          type: array
+          items:
+            $ref: '#/components/schemas/ReportedRunScoreOutcome'
     CreateAgentRequest:
       type: object
       required:
-        - name
+      - name
       properties:
         name:
           type: string
@@ -3379,6 +3941,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:
@@ -3403,31 +3973,72 @@ 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
+          deprecated: true
           description: |
             Optional default harness for runs executed by this agent.
+            Deprecated - use harness instead. Kept for backward compatibility;
+            when both are sent, harness is authoritative and a conflicting
+            type is rejected with invalid_request.
+        harness:
+          allOf:
+          - $ref: '#/components/schemas/Harness'
+          description: |
+            Optional default harness for runs executed by this agent.
+            Omission or an empty object stores no harness default.
+        credential_strategy:
+          allOf:
+          - $ref: '#/components/schemas/AgentCredentialStrategy'
+          nullable: true
+          description: |
+            Optional default credential strategy for runs executed by this
+            agent. When omitted or null, the agent has no opinion and runs fall
+            back to the factory default (for factory-seeded agents) and then to
+            EXECUTOR.
         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.
+        worker_host:
+          type: string
+          nullable: true
+          description: |
+            Optional default worker host for runs executed by this agent.
+            Omission, null, or an empty value stores no Agent default, in which
+            case the workspace default applies. A non-empty value is trimmed
+            and stored; use "warp" to force Warp-hosted execution over a
+            self-hosted workspace default. The precedence order for worker
+            host resolution is:
+            1. The host specified on the run itself
+            2. The agent's default host
+            3. The workspace default host
     UpdateAgentRequest:
       type: object
       description: |
@@ -3455,6 +4066,13 @@ components:
           description: |
             Replacement default cloud environment ID. Omit or pass `null` to leave unchanged,
             or pass an empty string to clear.
+        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.
         secrets:
           type: array
           nullable: true
@@ -3478,18 +4096,24 @@ components:
           description: |
             Replacement base model. Omit or pass `null` to leave unchanged,
             or pass an empty string to clear.
-        memory_stores:
-          type: array
+        memory:
+          allOf:
+          - $ref: '#/components/schemas/AgentMemoryUpdateConfig'
           nullable: true
-          items:
-            $ref: '#/components/schemas/MemoryStoreRef'
+          description: Replacement memory settings for this agent.
+        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.
         inference_providers:
           type: object
           allOf:
-            - $ref: '#/components/schemas/InferenceProvidersConfig'
+          - $ref: '#/components/schemas/InferenceProvidersConfig'
           nullable: true
           description: |
             Replacement inference provider settings for this agent.
@@ -3499,27 +4123,67 @@ components:
         base_harness:
           type: string
           nullable: true
+          deprecated: true
           description: |
             Replacement default harness. Omit or pass `null` to leave unchanged,
             or pass an empty string to clear.
+            Deprecated - use harness instead. Kept for backward compatibility;
+            when both are sent, harness is authoritative and a conflicting
+            type is rejected with invalid_request.
+        harness:
+          allOf:
+          - $ref: '#/components/schemas/Harness'
+          nullable: true
+          description: |
+            Replacement default harness for runs executed by this agent. Omit
+            or pass `null` to leave unchanged, pass `{}` to clear the stored
+            default, or pass a populated object to replace it wholesale.
+        credential_strategy:
+          allOf:
+          - $ref: '#/components/schemas/AgentCredentialStrategy'
+          nullable: true
+          description: |
+            Replacement default credential strategy. Omit or pass `null` to
+            leave unchanged, or pass an empty string to clear the agent's
+            default. An agent belonging to a file-managed factory cannot clear
+            it: its agent file expresses the strategy by declaring it, and a
+            file that declares none keeps the strategy already projected, so a
+            clear is rejected with a 400.
         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.
+        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.
+        worker_host:
+          type: string
+          nullable: true
+          description: |
+            Replacement default worker host. Omit or pass `null` to leave
+            unchanged, or pass an empty string to clear (the workspace default
+            then applies). A non-empty value is trimmed and replaces the
+            stored default; use "warp" to force Warp-hosted execution over a
+            self-hosted workspace default.
     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
@@ -3543,6 +4207,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
@@ -3576,36 +4251,77 @@ 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
+          deprecated: true
           description: |
             Default harness for runs executed by this agent. The precedence order for harness resolution is:
             1. The harness specified on the run itself
             2. The agent's base harness
             3. Oz
+            Deprecated - use harness instead, which carries the full
+            {type, model_id, reasoning_level} default.
+        harness:
+          allOf:
+          - $ref: '#/components/schemas/Harness'
+          description: |
+            Default harness for runs executed by this agent. Absent when the
+            agent has no harness default. A stored model_id/reasoning_level
+            pair is still returned even if the model has since left the
+            harness's catalog.
+        credential_strategy:
+          allOf:
+          - $ref: '#/components/schemas/AgentCredentialStrategy'
+          description: |
+            Default credential strategy for runs executed by this agent.
+            Absent when the agent has no default. The precedence order for
+            credential strategy resolution is:
+            1. The strategy specified on the run itself
+            2. The agent's default strategy
+            3. The factory's default strategy, for factory-seeded agents
+            4. EXECUTOR
         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.
+        worker_host:
+          type: string
+          description: |
+            Default worker host for runs executed by this agent, or empty when
+            unset. The precedence order for worker host resolution is:
+            1. The host specified on the run itself
+            2. The agent's default host
+            3. The workspace default host
     ListAgentIdentitiesResponse:
       type: object
       required:
-        - agents
+      - agents
       properties:
         agents:
           type: array
@@ -3615,11 +4331,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
@@ -3641,4 +4357,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