# Ze Harness API

Typed HTTP API for durable agent Sessions and Turns.

66 operations. The full OpenAPI 3.1.0 document is at [/openapi.json](https://github.com/openapi.json).

Authentication: operations marked with security use `bearer` (http Bearer).

## System

### `GET /v1/health`

**Health check.**
Reports whether the HTTP service is available.

Operation ID: `health`

Response `200` (`application/json`):

```ts
{ status: "ok" }
```

Errors: `400` ValidationErrorEncoded, `403` ForbiddenErrorEncoded, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/capabilities`

**Host capabilities.**
Reports the feature flags this host supports.

Operation ID: `capabilities`

Response `200` (`application/json`):

```ts
{
  backgroundSubagents: boolean;
  protocolVersion?: number;
  harnessVersion?: string;
}
```

Errors: `400` ValidationErrorEncoded, `403` ForbiddenErrorEncoded, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/logs`

**Read daemon logs.**
Reads a bounded, newest-first page of structured daemon log entries. Hosts without a log store report unavailable.

Operation ID: `logs`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `limit` | query | `string` | no |
| `level` | query | `"debug" \| "info" \| "warn" \| "error"` | no |

Response `200` (`application/json`):

```ts
{
  entries: {
    timestamp: string;
    level: "debug" | "info" | "warn" | "error";
    run: string;
    service: string;
    event: string;
    fields: Record<string, string>;
  }[];
  truncated: boolean;
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

## Sessions

Durable Session and Turn operations.

### `GET /v1/servers/{server}/sessions/{sessionId}`

**Get a Session.**
Returns current Session metadata.

Operation ID: `getSession`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  session: {
    id: string; // uuid
    defaultModel?: string;
    systemPrompt?: string;
    title?: string; // max length 100
    workdir: string; // max length 1024
    projectId: string; // max length 128
    forkedFrom?: {
      parentSessionId: string; // uuid
      turnId?: string; // uuid
      through?:
        | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
        | { kind: "conversationEntry"; entryId: string /* uuid */ };
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    spawnedFrom?: { parentSessionId: string /* uuid */ };
    agent?: string; // max length 128
    configuration: {
      revision: number; // min 1
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      approval: {
        timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
    };
    createdAt: number;
    updatedAt: number;
    nextSequence: number; // min 1
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `PUT /v1/servers/{server}/sessions/{sessionId}`

**Create a Session.**
Creates a Session with caller-selected identity.

Operation ID: `createSession`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Request body (`application/json`):

```ts
{
  defaultModel?: string;
  systemPrompt?: string;
  workdir?: string; // max length 1024
  clientWorkdir?: string; // max length 1024
  permissions?: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
  approval?: {
    timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
  };
}
```

Response `200` (`application/json`):

```ts
{
  session: {
    id: string; // uuid
    defaultModel?: string;
    systemPrompt?: string;
    title?: string; // max length 100
    workdir: string; // max length 1024
    projectId: string; // max length 128
    forkedFrom?: {
      parentSessionId: string; // uuid
      turnId?: string; // uuid
      through?:
        | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
        | { kind: "conversationEntry"; entryId: string /* uuid */ };
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    spawnedFrom?: { parentSessionId: string /* uuid */ };
    agent?: string; // max length 128
    configuration: {
      revision: number; // min 1
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      approval: {
        timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
    };
    createdAt: number;
    updatedAt: number;
    nextSequence: number; // min 1
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `DELETE /v1/servers/{server}/sessions/{sessionId}`

**Delete a Session.**
Cancels the Session work, finalizes its private state, and deletes its public history. The exact replay is idempotent and the deleted identity stays retired.

Operation ID: `deleteSession`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Request body (`application/json`):

```ts
null | { reason?: string }
```

Response `200` (`application/json`):

```ts
{ deleted: { sessionId: string /* uuid */ } }
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `PUT /v1/servers/{server}/sessions/{sessionId}/title`

**Set a Session title.**
Sets the Session display title. The same title is a no-op.

Operation ID: `setSessionTitle`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Request body (`application/json`):

```ts
{ title: string /* max length 100 */ }
```

Response `200` (`application/json`):

```ts
{
  session: {
    id: string; // uuid
    defaultModel?: string;
    systemPrompt?: string;
    title?: string; // max length 100
    workdir: string; // max length 1024
    projectId: string; // max length 128
    forkedFrom?: {
      parentSessionId: string; // uuid
      turnId?: string; // uuid
      through?:
        | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
        | { kind: "conversationEntry"; entryId: string /* uuid */ };
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    spawnedFrom?: { parentSessionId: string /* uuid */ };
    agent?: string; // max length 128
    configuration: {
      revision: number; // min 1
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      approval: {
        timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
    };
    createdAt: number;
    updatedAt: number;
    nextSequence: number; // min 1
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `PUT /v1/servers/{server}/sessions/{sessionId}/default-model`

**Set a Session default model.**
Sets the Session default model for later Turns. The same model is a no-op.

Operation ID: `setSessionDefaultModel`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Request body (`application/json`):

```ts
{ defaultModel: string }
```

Response `200` (`application/json`):

```ts
{
  session: {
    id: string; // uuid
    defaultModel?: string;
    systemPrompt?: string;
    title?: string; // max length 100
    workdir: string; // max length 1024
    projectId: string; // max length 128
    forkedFrom?: {
      parentSessionId: string; // uuid
      turnId?: string; // uuid
      through?:
        | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
        | { kind: "conversationEntry"; entryId: string /* uuid */ };
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    spawnedFrom?: { parentSessionId: string /* uuid */ };
    agent?: string; // max length 128
    configuration: {
      revision: number; // min 1
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      approval: {
        timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
    };
    createdAt: number;
    updatedAt: number;
    nextSequence: number; // min 1
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions`

**List Sessions.**
Returns one server’s Sessions, oldest first, optionally filtered by project.

Operation ID: `listSessions`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `projectId` | query | `string` | no |

Response `200` (`application/json`):

```ts
{
  sessions: {
    id: string; // uuid
    defaultModel?: string;
    systemPrompt?: string;
    title?: string; // max length 100
    workdir: string; // max length 1024
    projectId: string; // max length 128
    forkedFrom?: {
      parentSessionId: string; // uuid
      turnId?: string; // uuid
      through?:
        | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
        | { kind: "conversationEntry"; entryId: string /* uuid */ };
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    spawnedFrom?: { parentSessionId: string /* uuid */ };
    agent?: string; // max length 128
    configuration: {
      revision: number; // min 1
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      approval: {
        timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
    };
    createdAt: number;
    updatedAt: number;
    nextSequence: number; // min 1
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
  }[];
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/events`

**Watch a server.**
Streams every Session creation, title, deletion, and Turn update on one server, without the live text deltas. Without afterServerCursor the stream starts live from the current cursor and announces it with its first server.cursor; with one it replays every stamped row after that cursor. A caught-up stream repeats its current server.cursor at least every 15 seconds, so a longer silence means the connection is gone.

Operation ID: `watchServer`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `afterServerCursor` | query | `string` | no |

Response `200`: no body.

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `DELETE /v1/servers/{server}`

**Delete a server.**
Cancels and deletes Sessions on one server, optionally filtered by project. Workspace files stay.

Operation ID: `deleteServer`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `projectId` | query | `string` | no |

Response `200` (`application/json`):

```ts
{ deleted: { server: string /* max length 128 */; sessionIds: string[] } }
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/children`

**List Session children.**
Returns the Sessions spawned directly from one parent, oldest first.

Operation ID: `listSessionChildren`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  sessions: {
    id: string; // uuid
    defaultModel?: string;
    systemPrompt?: string;
    title?: string; // max length 100
    workdir: string; // max length 1024
    projectId: string; // max length 128
    forkedFrom?: {
      parentSessionId: string; // uuid
      turnId?: string; // uuid
      through?:
        | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
        | { kind: "conversationEntry"; entryId: string /* uuid */ };
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    spawnedFrom?: { parentSessionId: string /* uuid */ };
    agent?: string; // max length 128
    configuration: {
      revision: number; // min 1
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      approval: {
        timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
    };
    createdAt: number;
    updatedAt: number;
    nextSequence: number; // min 1
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
  }[];
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/background`

**Detach Session sub-agents.**
Detaches running foreground sub-agent chains to the background. Their results arrive as queued turns.

Operation ID: `promoteSessionBackground`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{ promoted: boolean }
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/configuration`

**Get Session configuration.**
Returns the versioned Session permission and approval configuration.

Operation ID: `getSessionConfiguration`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  configuration: {
    revision: number; // min 1
    permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
    approval: {
      timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
    };
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `PUT /v1/servers/{server}/sessions/{sessionId}/configuration`

**Replace Session configuration.**
Replaces the ordered Session rules when the expected revision is current.

Operation ID: `replaceSessionConfiguration`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Request body (`application/json`):

```ts
{
  expectedRevision: number; // min 1
  permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
  approval: {
    timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
  };
}
```

Response `200` (`application/json`):

```ts
{
  configuration: {
    revision: number; // min 1
    permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
    approval: {
      timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
    };
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/permissions/saved`

**List saved permissions.**
Returns durable Session-scoped allow grants.

Operation ID: `listSavedPermissions`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  permissions: {
    id: string; // uuid
    sessionId: string; // uuid
    action: string;
    resource: string;
    createdAt: number;
    sourcePermissionRequestId: string; // uuid
  }[];
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `DELETE /v1/servers/{server}/sessions/{sessionId}/permissions/saved/{savedPermissionId}`

**Remove saved permission.**
Removes one durable Session-scoped allow grant.

Operation ID: `removeSavedPermission`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `savedPermissionId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  permission: {
    id: string; // uuid
    sessionId: string; // uuid
    action: string;
    resource: string;
    createdAt: number;
    sourcePermissionRequestId: string; // uuid
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/forks/{forkedSessionId}`

**Fork a Session.**
Copies settled history before an optional Turn into a new Session with caller-selected identity.

Operation ID: `forkSession`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `forkedSessionId` | path | `string (uuid)` | yes |

Request body (`application/json`):

```ts
| null
  | {
    turnId?: string; // uuid
    through?:
      | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
      | { kind: "conversationEntry"; entryId: string /* uuid */ };
    visibility?: {
      floorHistoryRevision?: number;
      excludedTurnIds?: string[];
      excludedEntryIds?: string[];
    };
  }
```

Response `200` (`application/json`):

```ts
{
  session: {
    id: string; // uuid
    defaultModel?: string;
    systemPrompt?: string;
    title?: string; // max length 100
    workdir: string; // max length 1024
    projectId: string; // max length 128
    forkedFrom?: {
      parentSessionId: string; // uuid
      turnId?: string; // uuid
      through?:
        | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
        | { kind: "conversationEntry"; entryId: string /* uuid */ };
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    spawnedFrom?: { parentSessionId: string /* uuid */ };
    agent?: string; // max length 128
    configuration: {
      revision: number; // min 1
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      approval: {
        timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
    };
    createdAt: number;
    updatedAt: number;
    nextSequence: number; // min 1
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/skills`

**List Session Skills.**
Returns safe metadata for the effective host and Session Skill catalog.

Operation ID: `sessionSkills`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  sessionId: string; // uuid
  skills: {
    id: string; // max length 128
    displayName: string;
    description: string;
    advertised: boolean;
    userInvocable: boolean;
    origin: "host" | "session";
  }[];
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/turns`

**List Session Turns.**
Reads a bounded, stable Session history page.

Operation ID: `listSessionTurns`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `limit` | query | `string` | no |
| `afterSequence` | query | `string` | no |
| `throughSequence` | query | `string` | no |
| `snapshotActivityCursor` | query | `string` | no |

Response `200` (`application/json`):

```ts
{
  sessionId: string; // uuid
  boundary: { throughSequence: number; activityCursor: number };
  turns: {
    activityCursor: number;
    workSequence: number; // min 1
    turn: {
      id: string; // uuid
      sessionId: string; // uuid
      sequence: number; // min 1
      request: {
        sessionId: string; // uuid
        turnId: string; // uuid
        // at least 1
        prompt: Array<
          | { type: "text"; text: string }
          | {
            type: "image";
            source:
              | {
                type: "url";
                url: string;
                mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              }
              | {
                type: "base64";
                data: string;
                mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              };
          }
          | { type: "content-reference"; reference: string /* max length 2048 */ }
        >;
        conversationEntry?: { entryId: string /* uuid */; historyRevision: number /* min 1 */ };
        model?: string;
        agent?: string; // max length 128
        skills?: string[]; // at least 1
        reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
        visibility?: {
          floorHistoryRevision?: number;
          excludedTurnIds?: string[];
          excludedEntryIds?: string[];
        };
      };
      attribution?: {
        clientId: string; // max length 256
        authorId?: string; // max length 256
      };
      model: string;
      modelLeaseId: string; // max length 68
      requestOptionsId: string; // uuid
      policy: {
        version: 4;
        permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
        permissionMatching: { caseSensitive: boolean };
        approval: {
          timeoutMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
        };
        timeouts: {
          turnMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
        };
        steering: {
          maxBatches:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number;
              origin: "configured" | "provider" | "platform";
            };
        };
        subagents: {
          maxDepth:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number;
              origin: "configured" | "provider" | "platform";
            };
        };
        provider: {
          maxAttempts:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
          attemptTimeoutMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
          elapsedMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
          pacing:
            | { kind: "none" }
            | { kind: "fixed"; delayMs: number }
            | {
              kind: "exponential";
              initialDelayMs: number; // min 1
              maximumDelayMs: number; // min 1
              jitter: boolean;
            };
        };
        context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
        images: {
          maxBase64Bytes:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
        };
      };
      steering: {
        gate: "open" | "closed";
        promotedBatchCount: number;
        steers: {
          sessionId: string; // uuid
          turnId: string; // uuid
          steerId: string; // uuid
          sequence: number; // min 1
          // at least 1
          prompt: Array<
            | { type: "text"; text: string }
            | {
              type: "image";
              source:
                | {
                  type: "url";
                  url: string;
                  mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                }
                | {
                  type: "base64";
                  data: string;
                  mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                };
            }
            | { type: "content-reference"; reference: string /* max length 2048 */ }
          >;
          attribution: {
            clientId: string; // max length 256
            authorId?: string; // max length 256
          };
          acceptedAt: number;
          state:
            | { state: "accepted" }
            | { state: "promoted"; batch: number /* min 1 */; promotedAt: number }
            | {
              state: "undelivered";
              reason: "process_lost" | "turn_cancelled" | "turn_failed";
              undeliveredAt: number;
            };
        }[];
      };
      phase: "pending" | "running" | "completed" | "cancelled" | "failed";
      revision: number;
      parts: Array<
        | {
          type: "text";
          id: string; // uuid
          assistantMessageIndex: number;
          text: string;
        }
        | {
          type: "refusal";
          id: string; // uuid
          assistantMessageIndex: number;
          text: string;
        }
        | {
          type: "reasoning";
          id: string; // uuid
          assistantMessageIndex: number;
          text: string;
          startedAt?: number;
          completedAt?: number;
        }
        | {
          type: "tool";
          id: string; // uuid
          toolCallId: string;
          toolId: string;
          origin?:
            | { kind: "model" }
            | {
              kind: "codemode";
              parentToolCallId: string;
              ordinal: number; // min 1
              ownerPluginId?: string;
              binding?: { snapshotId: string; bindingId: string; modelMessageId: string };
            };
          execution?: { result: unknown; logs: string[] };
          instructions?: Array<
            | {
              kind: "instruction";
              id: string; // max length 512
              revision: string; // max length 512
              order: number;
              role: "system" | "developer" | "user";
              content: string;
              afterToolCallId?: string;
            }
            | {
              kind: "skill";
              id: string; // max length 512
              revision: string; // max length 512
              order: number;
              reference: string; // max length 2048
              content: string;
            }
            | {
              kind: "plugin";
              id: string; // max length 512
              revision: string; // max length 512
              order: number;
              reference: string; // max length 2048
            }
          >;
          assistantMessageIndex: number;
          modelInput?: unknown;
          input: unknown;
          state: "requested" | "completed" | "failed" | "denied";
          output?: unknown;
          fault?: {
            code: string; // max length 128
            message: string; // max length 4096
            providerCode?: string; // max length 128
          };
          canonicalResult?:
            | {
              format: "content";
              // at least 1
              value: Array<
                | { type: "text"; text: string }
                | { type: "json"; value: unknown }
                | {
                  type: "image";
                  source:
                    | {
                      type: "url";
                      url: string;
                      mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                    }
                    | {
                      type: "base64";
                      data: string;
                      mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                    };
                }
              >;
            }
            | { format: "text"; value: string }
            | { format: "json"; value: unknown };
          approval:
            | { state: "none" }
            | {
              state: "pending";
              request: {
                id: string; // uuid
                sessionId: string; // uuid
                turnId: string; // uuid
                toolId: string;
                toolCallId: string;
                action: string;
                resources: string[]; // at least 1
                save?: string[];
                metadata?: unknown;
              };
              requestedAt: number;
            }
            | {
              state: "resolved";
              request: {
                id: string; // uuid
                sessionId: string; // uuid
                turnId: string; // uuid
                toolId: string;
                toolCallId: string;
                action: string;
                resources: string[]; // at least 1
                save?: string[];
                metadata?: unknown;
              };
              requestedAt: number;
              resolvedAt: number;
              decision: "allow" | "deny";
              source: "config" | "saved" | "hook" | "callback" | "remote" | "default" | "timeout" | "terminal";
              reply?: "once" | "always" | "reject";
              replyMessage?: string; // max length 4096
            };
          question?:
            | {
              state: "pending";
              request: {
                id: string; // uuid
                sessionId: string; // uuid
                turnId: string; // uuid
                toolId: string;
                toolCallId: string;
                // at least 1
                questions: {
                  question: string; // max length 4096
                  header: string; // max length 30
                  // at least 1
                  options: {
                    label: string; // max length 256
                    description: string; // max length 4096
                  }[];
                  multiple?: boolean;
                  custom?: boolean;
                }[];
              };
              requestedAt: number;
            }
            | {
              state: "answered";
              request: {
                id: string; // uuid
                sessionId: string; // uuid
                turnId: string; // uuid
                toolId: string;
                toolCallId: string;
                // at least 1
                questions: {
                  question: string; // max length 4096
                  header: string; // max length 30
                  // at least 1
                  options: {
                    label: string; // max length 256
                    description: string; // max length 4096
                  }[];
                  multiple?: boolean;
                  custom?: boolean;
                }[];
              };
              requestedAt: number;
              resolvedAt: number;
              answers: string[][]; // at least 1
            }
            | {
              state: "dismissed";
              request: {
                id: string; // uuid
                sessionId: string; // uuid
                turnId: string; // uuid
                toolId: string;
                toolCallId: string;
                // at least 1
                questions: {
                  question: string; // max length 4096
                  header: string; // max length 30
                  // at least 1
                  options: {
                    label: string; // max length 256
                    description: string; // max length 4096
                  }[];
                  multiple?: boolean;
                  custom?: boolean;
                }[];
              };
              requestedAt: number;
              resolvedAt: number;
            };
          requestedAt: number;
          completedAt?: number;
          activity?: {
            checkpoint: number; // min 1
            updatedAt: number;
            message?: string; // max length 1024
            preview?: string;
            observedBytes: number;
            truncated: boolean;
            artifact?: {
              id: string; // uuid
              path: string;
              observedBytes: number;
              state: "writing" | "complete" | "incomplete";
            };
            childSessionId?: string; // uuid
          };
          artifact?: {
            id: string; // uuid
            path: string;
            observedBytes: number;
            state: "writing" | "complete" | "incomplete";
          };
        }
        | {
          type: "steering";
          id: string; // uuid
          batch: number; // min 1
          promotedAt: number;
          steers: {
            steerId: string; // uuid
            sequence: number; // min 1
            // at least 1
            prompt: Array<
              | { type: "text"; text: string }
              | {
                type: "image";
                source:
                  | {
                    type: "url";
                    url: string;
                    mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  }
                  | {
                    type: "base64";
                    data: string;
                    mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  };
              }
              | { type: "content-reference"; reference: string /* max length 2048 */ }
            >;
            attribution: {
              clientId: string; // max length 256
              authorId?: string; // max length 256
            };
            acceptedAt: number;
          }[];
        }
      >;
      usage?: {
        promptTokens: number | "Infinity" | "-Infinity" | "NaN";
        completionTokens: number | "Infinity" | "-Infinity" | "NaN";
        totalTokens: number | "Infinity" | "-Infinity" | "NaN";
        cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
        reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
      };
      contextUse?: { model: string; usedUnits: number; contextUnits: number };
      cancellation?: { reason?: string; requestedAt: number };
      outcome?:
        | { kind: "completed"; turnId: string; text: string }
        | { kind: "cancelled"; turnId: string; reason?: string }
        | {
          kind: "failed";
          turnId: string;
          fault: {
            code: string; // max length 128
            message: string; // max length 4096
            providerCode?: string; // max length 128
          };
        }
        | {
          kind: "limit_reached";
          turnId: string;
          limit:
            | {
              name: "turn_elapsed";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "approval_wait";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "provider_elapsed";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "provider_attempt_timeout";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "steering_batches";
              origin: "configured" | "provider" | "platform";
              value: number;
              unit: "batches";
            }
            | {
              name: "provider_attempts";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "attempts";
            }
            | {
              name: "model_context";
              origin: "configured" | "provider" | "platform";
              value: number;
              unit: "model_units";
              estimatedInputUnits: number;
              outputReserveUnits: number;
              safetyReserveUnits: number;
              availableInputUnits: number;
              estimator: string; // max length 128
            };
          diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
        };
      acceptedAt: number;
      startedAt?: number;
      completedAt?: number;
    };
  }[];
  nextAfterSequence?: number;
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/journal`

**List Session plugin journal entries.**
Reads durable plugin-reported facts in record order, optionally for one Turn.

Operation ID: `listPluginJournal`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `limit` | query | `string` | no |
| `turnId` | query | `string (uuid)` | no |
| `afterTurnSequence` | query | `string` | no |
| `afterSequence` | query | `string` | no |

Response `200` (`application/json`):

```ts
{
  sessionId: string; // uuid
  entries: {
    sessionId: string; // uuid
    turnId: string; // uuid
    sequence: number; // min 1
    pluginId: string;
    kind: string;
    summary: string;
    data: unknown;
    logicalCallOrdinal?: number; // min 1
    toolCallId?: string;
    recordedAt: number;
  }[];
  next?: { turnSequence: number; sequence: number };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/events`

**Watch a Session.**
Streams observational Session updates after a durable cursor. A caught-up stream repeats its current session.cursor at least every 15 seconds, so a longer silence means the connection is gone.

Operation ID: `watchSession`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `afterActivityCursor` | query | `string` | yes |

Response `200`: no body.

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/prompts`

**Submit a prompt.**
Durably admits queued work or steering input.

Operation ID: `submitPrompt`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `x-ze-harness-client-id` | header | `string` | yes |

Request body (`application/json`):

```ts
| {
    delivery: "queue";
    turnId: string; // uuid
    // at least 1
    prompt: Array<
      | { type: "text"; text: string }
      | {
        type: "image";
        source:
          | {
            type: "url";
            url: string;
            mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
          }
          | {
            type: "base64";
            data: string;
            mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
          };
      }
      | { type: "content-reference"; reference: string /* max length 2048 */ }
    >;
    conversationEntry?: { entryId: string /* uuid */; historyRevision: number /* min 1 */ };
    model?: string;
    agent?: string; // max length 128
    skills?: string[]; // at least 1
    reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
    visibility?: {
      floorHistoryRevision?: number;
      excludedTurnIds?: string[];
      excludedEntryIds?: string[];
    };
    authorId?: string; // max length 256
    providerOptions?: unknown;
  }
  | {
    delivery: "steer";
    steerId: string; // uuid
    expectedTurnId: string; // uuid
    // at least 1
    prompt: Array<
      | { type: "text"; text: string }
      | {
        type: "image";
        source:
          | {
            type: "url";
            url: string;
            mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
          }
          | {
            type: "base64";
            data: string;
            mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
          };
      }
      | { type: "content-reference"; reference: string /* max length 2048 */ }
    >;
    authorId?: string; // max length 256
  }
```

Response `202` (`application/json`):

```ts
{
  receipt:
    | {
      delivery: "queue";
      sessionId: string; // uuid
      turnId: string; // uuid
      modelLeaseId: string; // max length 68
      requestOptionsId: string; // uuid
      sequence: number; // min 1
      acceptedAt: number;
      attribution?: {
        clientId: string; // max length 256
        authorId?: string; // max length 256
      };
    }
    | {
      delivery: "steer";
      sessionId: string; // uuid
      turnId: string; // uuid
      steerId: string; // uuid
      sequence: number; // min 1
      acceptedAt: number;
      attribution: {
        clientId: string; // max length 256
        authorId?: string; // max length 256
      };
    };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/conversation`

**Append a conversation entry.**
Appends a durable user message for later work without admitting a Turn or calling a model.

Operation ID: `appendConversation`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `x-ze-harness-client-id` | header | `string` | yes |

Request body (`application/json`):

```ts
{
  entryId: string; // uuid
  // at least 1
  content: Array<
    | { type: "text"; text: string }
    | { type: "content-reference"; reference: string /* max length 2048 */ }
  >;
  authorId?: string; // max length 256
}
```

Response `200` (`application/json`):

```ts
{
  receipt: {
    sessionId: string; // uuid
    entryId: string; // uuid
    historyRevision: number; // min 1
    acceptedAt: number;
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/mcp`

**Get the MCP catalog.**
Returns the effective host and Session MCP catalog without private metadata.

Operation ID: `getMcpCatalog`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  catalog: {
    revision: number;
    servers: {
      origin: "host" | "session";
      serverId: string;
      name: string; // max length 128
      order: number;
      protocolVersion: string;
      capabilities: {
        tools: { supported: boolean; listChanged: boolean };
        resources: { supported: boolean; listChanged: boolean; subscribe: boolean };
        prompts: { supported: boolean; listChanged: boolean };
        logging: boolean;
        completions: boolean;
      };
      instructions?: string;
      catalog: {
        revision: number;
        tools: {
          name: string;
          title?: string;
          description?: string;
          inputSchema: unknown;
          outputSchema?: unknown;
          annotations?: {
            title?: string;
            readOnlyHint?: boolean;
            destructiveHint?: boolean;
            idempotentHint?: boolean;
            openWorldHint?: boolean;
          };
        }[];
        resources: {
          uri: string;
          name: string;
          title?: string;
          description?: string;
          mimeType?: string;
          annotations?: {
            audience?: ("user" | "assistant")[];
            priority?: number; // max 1
            lastModified?: string;
          };
          size?: number;
        }[];
        resourceTemplates: {
          uriTemplate: string;
          name: string;
          title?: string;
          description?: string;
          mimeType?: string;
          annotations?: {
            audience?: ("user" | "assistant")[];
            priority?: number; // max 1
            lastModified?: string;
          };
        }[];
        prompts: {
          name: string;
          title?: string;
          description?: string;
          arguments?: { name: string; title?: string; description?: string; required?: boolean }[];
        }[];
      };
    }[];
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/mcp/{serverName}/prompts/{promptName}`

**Submit an MCP prompt.**
Resolves an MCP prompt and durably admits it through the ordinary prompt path.

Operation ID: `submitMcpPrompt`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `serverName` | path | `string` | yes |
| `promptName` | path | `string` | yes |
| `x-ze-harness-client-id` | header | `string` | yes |

Request body (`application/json`):

```ts
{
  turnId: string; // uuid
  arguments?: Record<string, string>;
  model?: string;
  providerOptions?: unknown;
}
```

Response `202` (`application/json`):

```ts
{
  receipt:
    | {
      delivery: "queue";
      sessionId: string; // uuid
      turnId: string; // uuid
      modelLeaseId: string; // max length 68
      requestOptionsId: string; // uuid
      sequence: number; // min 1
      acceptedAt: number;
      attribution?: {
        clientId: string; // max length 256
        authorId?: string; // max length 256
      };
    }
    | {
      delivery: "steer";
      sessionId: string; // uuid
      turnId: string; // uuid
      steerId: string; // uuid
      sequence: number; // min 1
      acceptedAt: number;
      attribution: {
        clientId: string; // max length 256
        authorId?: string; // max length 256
      };
    };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/mcp/{serverName}/resources/read`

**Read an MCP resource.**
Reads one resource advertised by the effective leased MCP catalog.

Operation ID: `readMcpResource`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `serverName` | path | `string` | yes |

Request body (`application/json`):

```ts
{ uri: string }
```

Response `200` (`application/json`):

```ts
{
  resource: {
    contents: Array<
      | { uri: string; mimeType?: string; text: string }
      | { uri: string; mimeType?: string; blob: string }
    >;
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/compactions`

**List context compactions.**
Reads a bounded, stable page of durable Session compactions.

Operation ID: `listSessionCompactions`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `limit` | query | `string` | no |
| `afterSequence` | query | `string` | no |
| `afterOrdinal` | query | `string` | no |
| `throughSequence` | query | `string` | no |
| `throughOrdinal` | query | `string` | no |
| `snapshotActivityCursor` | query | `string` | no |

Response `200` (`application/json`):

```ts
{
  sessionId: string; // uuid
  boundary: { throughSequence: number; throughOrdinal: number; activityCursor: number };
  compactions: {
    sequence: number; // min 1
    ordinal: number; // min 1
    compaction: {
      id: string; // uuid
      sessionId: string; // uuid
      sequence: number; // min 1
      request: {
        sessionId: string; // uuid
        compactionId: string; // uuid
        model?: string;
        visibility?: {
          floorHistoryRevision?: number;
          excludedTurnIds?: string[];
          excludedEntryIds?: string[];
        };
      };
      attribution?: {
        clientId: string; // max length 256
        authorId?: string; // max length 256
      };
      trigger:
        | { kind: "manual" }
        | { kind: "preflight"; turnId: string /* uuid */ }
        | { kind: "overflow"; turnId: string /* uuid */ };
      model: string;
      modelLeaseId: string; // max length 68
      requestOptionsId: string; // uuid
      policy: {
        version: 4;
        permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
        permissionMatching: { caseSensitive: boolean };
        approval: {
          timeoutMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
        };
        timeouts: {
          turnMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
        };
        steering: {
          maxBatches:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number;
              origin: "configured" | "provider" | "platform";
            };
        };
        subagents: {
          maxDepth:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number;
              origin: "configured" | "provider" | "platform";
            };
        };
        provider: {
          maxAttempts:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
          attemptTimeoutMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
          elapsedMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
          pacing:
            | { kind: "none" }
            | { kind: "fixed"; delayMs: number }
            | {
              kind: "exponential";
              initialDelayMs: number; // min 1
              maximumDelayMs: number; // min 1
              jitter: boolean;
            };
        };
        context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
        images: {
          maxBase64Bytes:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
        };
      };
      phase: "pending" | "running" | "completed" | "cancelled" | "failed";
      revision: number;
      cancellation?: { reason?: string; requestedAt: number };
      usage?: {
        promptTokens: number | "Infinity" | "-Infinity" | "NaN";
        completionTokens: number | "Infinity" | "-Infinity" | "NaN";
        totalTokens: number | "Infinity" | "-Infinity" | "NaN";
        cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
        reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
      };
      outcome?:
        | {
          kind: "completed";
          checkpoint: {
            id: string; // uuid
            compactionId: string; // uuid
            sessionId: string; // uuid
            throughHistoryRevision: number; // min 1
            throughChronologyRevision: number;
            sourceMessageCount: number; // min 1
            summary: {
              version: 1;
              overview: string; // max length 262144
              keyFacts: string[];
              decisions: string[];
              openTasks: string[];
            };
            chronology: {
              revision: number; // min 1
              historyRevision: number;
              boundaryOrder: number;
              change: "activated" | "updated" | "removed";
              source:
                | {
                  kind: "instruction";
                  id: string; // max length 512
                  revision: string; // max length 512
                  order: number;
                  role: "system" | "developer" | "user";
                  content: string;
                  afterToolCallId?: string;
                }
                | {
                  kind: "skill";
                  id: string; // max length 512
                  revision: string; // max length 512
                  order: number;
                  reference: string; // max length 2048
                  content: string;
                }
                | {
                  kind: "plugin";
                  id: string; // max length 512
                  revision: string; // max length 512
                  order: number;
                  reference: string; // max length 2048
                };
            }[];
            estimate: {
              estimator: string; // max length 128
              inputUnits: number;
              contextUnits: number;
              outputUnits: number;
              safetyReserveUnits: number;
              availableInputUnits: number;
              fits: boolean;
            };
            createdAt: number;
          };
          usage?: {
            promptTokens: number | "Infinity" | "-Infinity" | "NaN";
            completionTokens: number | "Infinity" | "-Infinity" | "NaN";
            totalTokens: number | "Infinity" | "-Infinity" | "NaN";
            cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
            reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
          };
        }
        | {
          kind: "cancelled";
          reason?: string;
          usage?: {
            promptTokens: number | "Infinity" | "-Infinity" | "NaN";
            completionTokens: number | "Infinity" | "-Infinity" | "NaN";
            totalTokens: number | "Infinity" | "-Infinity" | "NaN";
            cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
            reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
          };
        }
        | {
          kind: "failed";
          fault: {
            code: string; // max length 128
            message: string; // max length 4096
            providerCode?: string; // max length 128
          };
          usage?: {
            promptTokens: number | "Infinity" | "-Infinity" | "NaN";
            completionTokens: number | "Infinity" | "-Infinity" | "NaN";
            totalTokens: number | "Infinity" | "-Infinity" | "NaN";
            cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
            reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
          };
        }
        | {
          kind: "no_compressible_history";
          usage?: {
            promptTokens: number | "Infinity" | "-Infinity" | "NaN";
            completionTokens: number | "Infinity" | "-Infinity" | "NaN";
            totalTokens: number | "Infinity" | "-Infinity" | "NaN";
            cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
            reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
          };
        }
        | {
          kind: "limit_reached";
          limit:
            | {
              name: "turn_elapsed";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "approval_wait";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "provider_elapsed";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "provider_attempt_timeout";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "steering_batches";
              origin: "configured" | "provider" | "platform";
              value: number;
              unit: "batches";
            }
            | {
              name: "provider_attempts";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "attempts";
            }
            | {
              name: "model_context";
              origin: "configured" | "provider" | "platform";
              value: number;
              unit: "model_units";
              estimatedInputUnits: number;
              outputReserveUnits: number;
              safetyReserveUnits: number;
              availableInputUnits: number;
              estimator: string; // max length 128
            };
          diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
          usage?: {
            promptTokens: number | "Infinity" | "-Infinity" | "NaN";
            completionTokens: number | "Infinity" | "-Infinity" | "NaN";
            totalTokens: number | "Infinity" | "-Infinity" | "NaN";
            cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
            reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
          };
        };
      acceptedAt: number;
      startedAt?: number;
      completedAt?: number;
    };
  }[];
  next?: { sequence: number /* min 1 */; ordinal: number /* min 1 */ };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/compactions`

**Compact Session context.**
Durably admits an ordered manual context compaction.

Operation ID: `submitContextCompaction`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `x-ze-harness-client-id` | header | `string` | yes |

Request body (`application/json`):

```ts
{
  compactionId: string; // uuid
  model?: string;
  visibility?: {
    floorHistoryRevision?: number;
    excludedTurnIds?: string[];
    excludedEntryIds?: string[];
  };
  authorId?: string; // max length 256
  providerOptions?: unknown;
}
```

Response `202` (`application/json`):

```ts
{
  receipt: {
    delivery: "compaction";
    sessionId: string; // uuid
    compactionId: string; // uuid
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    sequence: number; // min 1
    acceptedAt: number;
    attribution: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/compactions/{compactionId}`

**Get context compaction.**
Returns authoritative context compaction state.

Operation ID: `getContextCompaction`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `compactionId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  compaction: {
    id: string; // uuid
    sessionId: string; // uuid
    sequence: number; // min 1
    request: {
      sessionId: string; // uuid
      compactionId: string; // uuid
      model?: string;
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
    trigger:
      | { kind: "manual" }
      | { kind: "preflight"; turnId: string /* uuid */ }
      | { kind: "overflow"; turnId: string /* uuid */ };
    model: string;
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    policy: {
      version: 4;
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      permissionMatching: { caseSensitive: boolean };
      approval: {
        timeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      timeouts: {
        turnMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      steering: {
        maxBatches:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      subagents: {
        maxDepth:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      provider: {
        maxAttempts:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        attemptTimeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        elapsedMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        pacing:
          | { kind: "none" }
          | { kind: "fixed"; delayMs: number }
          | {
            kind: "exponential";
            initialDelayMs: number; // min 1
            maximumDelayMs: number; // min 1
            jitter: boolean;
          };
      };
      context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
      images: {
        maxBase64Bytes:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
    };
    phase: "pending" | "running" | "completed" | "cancelled" | "failed";
    revision: number;
    cancellation?: { reason?: string; requestedAt: number };
    usage?: {
      promptTokens: number | "Infinity" | "-Infinity" | "NaN";
      completionTokens: number | "Infinity" | "-Infinity" | "NaN";
      totalTokens: number | "Infinity" | "-Infinity" | "NaN";
      cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
      reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
    };
    outcome?:
      | {
        kind: "completed";
        checkpoint: {
          id: string; // uuid
          compactionId: string; // uuid
          sessionId: string; // uuid
          throughHistoryRevision: number; // min 1
          throughChronologyRevision: number;
          sourceMessageCount: number; // min 1
          summary: {
            version: 1;
            overview: string; // max length 262144
            keyFacts: string[];
            decisions: string[];
            openTasks: string[];
          };
          chronology: {
            revision: number; // min 1
            historyRevision: number;
            boundaryOrder: number;
            change: "activated" | "updated" | "removed";
            source:
              | {
                kind: "instruction";
                id: string; // max length 512
                revision: string; // max length 512
                order: number;
                role: "system" | "developer" | "user";
                content: string;
                afterToolCallId?: string;
              }
              | {
                kind: "skill";
                id: string; // max length 512
                revision: string; // max length 512
                order: number;
                reference: string; // max length 2048
                content: string;
              }
              | {
                kind: "plugin";
                id: string; // max length 512
                revision: string; // max length 512
                order: number;
                reference: string; // max length 2048
              };
          }[];
          estimate: {
            estimator: string; // max length 128
            inputUnits: number;
            contextUnits: number;
            outputUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            fits: boolean;
          };
          createdAt: number;
        };
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "cancelled";
        reason?: string;
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "failed";
        fault: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "no_compressible_history";
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "limit_reached";
        limit:
          | {
            name: "turn_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "approval_wait";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_attempt_timeout";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "steering_batches";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "batches";
          }
          | {
            name: "provider_attempts";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "attempts";
          }
          | {
            name: "model_context";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "model_units";
            estimatedInputUnits: number;
            outputReserveUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            estimator: string; // max length 128
          };
        diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      };
    acceptedAt: number;
    startedAt?: number;
    completedAt?: number;
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/compactions/{compactionId}/cancel`

**Cancel context compaction.**
Requests cancellation of pending or running context compaction.

Operation ID: `cancelContextCompaction`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `compactionId` | path | `string (uuid)` | yes |

Request body (`application/json`):

```ts
{ reason?: string }
```

Response `200` (`application/json`):

```ts
{
  compaction: {
    id: string; // uuid
    sessionId: string; // uuid
    sequence: number; // min 1
    request: {
      sessionId: string; // uuid
      compactionId: string; // uuid
      model?: string;
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
    trigger:
      | { kind: "manual" }
      | { kind: "preflight"; turnId: string /* uuid */ }
      | { kind: "overflow"; turnId: string /* uuid */ };
    model: string;
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    policy: {
      version: 4;
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      permissionMatching: { caseSensitive: boolean };
      approval: {
        timeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      timeouts: {
        turnMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      steering: {
        maxBatches:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      subagents: {
        maxDepth:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      provider: {
        maxAttempts:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        attemptTimeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        elapsedMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        pacing:
          | { kind: "none" }
          | { kind: "fixed"; delayMs: number }
          | {
            kind: "exponential";
            initialDelayMs: number; // min 1
            maximumDelayMs: number; // min 1
            jitter: boolean;
          };
      };
      context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
      images: {
        maxBase64Bytes:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
    };
    phase: "pending" | "running" | "completed" | "cancelled" | "failed";
    revision: number;
    cancellation?: { reason?: string; requestedAt: number };
    usage?: {
      promptTokens: number | "Infinity" | "-Infinity" | "NaN";
      completionTokens: number | "Infinity" | "-Infinity" | "NaN";
      totalTokens: number | "Infinity" | "-Infinity" | "NaN";
      cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
      reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
    };
    outcome?:
      | {
        kind: "completed";
        checkpoint: {
          id: string; // uuid
          compactionId: string; // uuid
          sessionId: string; // uuid
          throughHistoryRevision: number; // min 1
          throughChronologyRevision: number;
          sourceMessageCount: number; // min 1
          summary: {
            version: 1;
            overview: string; // max length 262144
            keyFacts: string[];
            decisions: string[];
            openTasks: string[];
          };
          chronology: {
            revision: number; // min 1
            historyRevision: number;
            boundaryOrder: number;
            change: "activated" | "updated" | "removed";
            source:
              | {
                kind: "instruction";
                id: string; // max length 512
                revision: string; // max length 512
                order: number;
                role: "system" | "developer" | "user";
                content: string;
                afterToolCallId?: string;
              }
              | {
                kind: "skill";
                id: string; // max length 512
                revision: string; // max length 512
                order: number;
                reference: string; // max length 2048
                content: string;
              }
              | {
                kind: "plugin";
                id: string; // max length 512
                revision: string; // max length 512
                order: number;
                reference: string; // max length 2048
              };
          }[];
          estimate: {
            estimator: string; // max length 128
            inputUnits: number;
            contextUnits: number;
            outputUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            fits: boolean;
          };
          createdAt: number;
        };
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "cancelled";
        reason?: string;
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "failed";
        fault: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "no_compressible_history";
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "limit_reached";
        limit:
          | {
            name: "turn_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "approval_wait";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_attempt_timeout";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "steering_batches";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "batches";
          }
          | {
            name: "provider_attempts";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "attempts";
          }
          | {
            name: "model_context";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "model_units";
            estimatedInputUnits: number;
            outputReserveUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            estimator: string; // max length 128
          };
        diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      };
    acceptedAt: number;
    startedAt?: number;
    completedAt?: number;
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/turns/{turnId}`

**Get a Turn.**
Returns authoritative public Turn state.

Operation ID: `getTurn`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `turnId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  turn: {
    id: string; // uuid
    sessionId: string; // uuid
    sequence: number; // min 1
    request: {
      sessionId: string; // uuid
      turnId: string; // uuid
      // at least 1
      prompt: Array<
        | { type: "text"; text: string }
        | {
          type: "image";
          source:
            | {
              type: "url";
              url: string;
              mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            }
            | {
              type: "base64";
              data: string;
              mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            };
        }
        | { type: "content-reference"; reference: string /* max length 2048 */ }
      >;
      conversationEntry?: { entryId: string /* uuid */; historyRevision: number /* min 1 */ };
      model?: string;
      agent?: string; // max length 128
      skills?: string[]; // at least 1
      reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
    model: string;
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    policy: {
      version: 4;
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      permissionMatching: { caseSensitive: boolean };
      approval: {
        timeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      timeouts: {
        turnMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      steering: {
        maxBatches:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      subagents: {
        maxDepth:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      provider: {
        maxAttempts:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        attemptTimeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        elapsedMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        pacing:
          | { kind: "none" }
          | { kind: "fixed"; delayMs: number }
          | {
            kind: "exponential";
            initialDelayMs: number; // min 1
            maximumDelayMs: number; // min 1
            jitter: boolean;
          };
      };
      context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
      images: {
        maxBase64Bytes:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
    };
    steering: {
      gate: "open" | "closed";
      promotedBatchCount: number;
      steers: {
        sessionId: string; // uuid
        turnId: string; // uuid
        steerId: string; // uuid
        sequence: number; // min 1
        // at least 1
        prompt: Array<
          | { type: "text"; text: string }
          | {
            type: "image";
            source:
              | {
                type: "url";
                url: string;
                mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              }
              | {
                type: "base64";
                data: string;
                mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              };
          }
          | { type: "content-reference"; reference: string /* max length 2048 */ }
        >;
        attribution: {
          clientId: string; // max length 256
          authorId?: string; // max length 256
        };
        acceptedAt: number;
        state:
          | { state: "accepted" }
          | { state: "promoted"; batch: number /* min 1 */; promotedAt: number }
          | {
            state: "undelivered";
            reason: "process_lost" | "turn_cancelled" | "turn_failed";
            undeliveredAt: number;
          };
      }[];
    };
    phase: "pending" | "running" | "completed" | "cancelled" | "failed";
    revision: number;
    parts: Array<
      | {
        type: "text";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "refusal";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "reasoning";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
        startedAt?: number;
        completedAt?: number;
      }
      | {
        type: "tool";
        id: string; // uuid
        toolCallId: string;
        toolId: string;
        origin?:
          | { kind: "model" }
          | {
            kind: "codemode";
            parentToolCallId: string;
            ordinal: number; // min 1
            ownerPluginId?: string;
            binding?: { snapshotId: string; bindingId: string; modelMessageId: string };
          };
        execution?: { result: unknown; logs: string[] };
        instructions?: Array<
          | {
            kind: "instruction";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            role: "system" | "developer" | "user";
            content: string;
            afterToolCallId?: string;
          }
          | {
            kind: "skill";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
            content: string;
          }
          | {
            kind: "plugin";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
          }
        >;
        assistantMessageIndex: number;
        modelInput?: unknown;
        input: unknown;
        state: "requested" | "completed" | "failed" | "denied";
        output?: unknown;
        fault?: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
        canonicalResult?:
          | {
            format: "content";
            // at least 1
            value: Array<
              | { type: "text"; text: string }
              | { type: "json"; value: unknown }
              | {
                type: "image";
                source:
                  | {
                    type: "url";
                    url: string;
                    mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  }
                  | {
                    type: "base64";
                    data: string;
                    mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  };
              }
            >;
          }
          | { format: "text"; value: string }
          | { format: "json"; value: unknown };
        approval:
          | { state: "none" }
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
          }
          | {
            state: "resolved";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
            resolvedAt: number;
            decision: "allow" | "deny";
            source: "config" | "saved" | "hook" | "callback" | "remote" | "default" | "timeout" | "terminal";
            reply?: "once" | "always" | "reject";
            replyMessage?: string; // max length 4096
          };
        question?:
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
          }
          | {
            state: "answered";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
            answers: string[][]; // at least 1
          }
          | {
            state: "dismissed";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
          };
        requestedAt: number;
        completedAt?: number;
        activity?: {
          checkpoint: number; // min 1
          updatedAt: number;
          message?: string; // max length 1024
          preview?: string;
          observedBytes: number;
          truncated: boolean;
          artifact?: {
            id: string; // uuid
            path: string;
            observedBytes: number;
            state: "writing" | "complete" | "incomplete";
          };
          childSessionId?: string; // uuid
        };
        artifact?: {
          id: string; // uuid
          path: string;
          observedBytes: number;
          state: "writing" | "complete" | "incomplete";
        };
      }
      | {
        type: "steering";
        id: string; // uuid
        batch: number; // min 1
        promotedAt: number;
        steers: {
          steerId: string; // uuid
          sequence: number; // min 1
          // at least 1
          prompt: Array<
            | { type: "text"; text: string }
            | {
              type: "image";
              source:
                | {
                  type: "url";
                  url: string;
                  mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                }
                | {
                  type: "base64";
                  data: string;
                  mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                };
            }
            | { type: "content-reference"; reference: string /* max length 2048 */ }
          >;
          attribution: {
            clientId: string; // max length 256
            authorId?: string; // max length 256
          };
          acceptedAt: number;
        }[];
      }
    >;
    usage?: {
      promptTokens: number | "Infinity" | "-Infinity" | "NaN";
      completionTokens: number | "Infinity" | "-Infinity" | "NaN";
      totalTokens: number | "Infinity" | "-Infinity" | "NaN";
      cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
      reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
    };
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
    cancellation?: { reason?: string; requestedAt: number };
    outcome?:
      | { kind: "completed"; turnId: string; text: string }
      | { kind: "cancelled"; turnId: string; reason?: string }
      | {
        kind: "failed";
        turnId: string;
        fault: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
      }
      | {
        kind: "limit_reached";
        turnId: string;
        limit:
          | {
            name: "turn_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "approval_wait";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_attempt_timeout";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "steering_batches";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "batches";
          }
          | {
            name: "provider_attempts";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "attempts";
          }
          | {
            name: "model_context";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "model_units";
            estimatedInputUnits: number;
            outputReserveUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            estimator: string; // max length 128
          };
        diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
      };
    acceptedAt: number;
    startedAt?: number;
    completedAt?: number;
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/turns/{turnId}/events`

**Watch a Turn.**
Streams observational Turn snapshots, content deltas, and durable state events after a revision cursor. The stream starts with the current snapshot, then replays the durable events recorded after afterRevision so observers see missed state transitions, then continues with live Turn revisions. While the Turn is quiet, the stream sends turn.heartbeat at least every 15 seconds, so a longer silence means the connection is gone.

Operation ID: `watchTurn`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `turnId` | path | `string (uuid)` | yes |
| `afterRevision` | query | `string` | no |

Response `200`: no body.

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/turns/{turnId}/cancel`

**Cancel a Turn.**
Requests cancellation of active Turn work.

Operation ID: `cancelTurn`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `turnId` | path | `string (uuid)` | yes |

Request body (`application/json`):

```ts
{ reason?: string }
```

Response `200` (`application/json`):

```ts
{
  turn: {
    id: string; // uuid
    sessionId: string; // uuid
    sequence: number; // min 1
    request: {
      sessionId: string; // uuid
      turnId: string; // uuid
      // at least 1
      prompt: Array<
        | { type: "text"; text: string }
        | {
          type: "image";
          source:
            | {
              type: "url";
              url: string;
              mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            }
            | {
              type: "base64";
              data: string;
              mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            };
        }
        | { type: "content-reference"; reference: string /* max length 2048 */ }
      >;
      conversationEntry?: { entryId: string /* uuid */; historyRevision: number /* min 1 */ };
      model?: string;
      agent?: string; // max length 128
      skills?: string[]; // at least 1
      reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
    model: string;
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    policy: {
      version: 4;
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      permissionMatching: { caseSensitive: boolean };
      approval: {
        timeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      timeouts: {
        turnMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      steering: {
        maxBatches:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      subagents: {
        maxDepth:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      provider: {
        maxAttempts:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        attemptTimeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        elapsedMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        pacing:
          | { kind: "none" }
          | { kind: "fixed"; delayMs: number }
          | {
            kind: "exponential";
            initialDelayMs: number; // min 1
            maximumDelayMs: number; // min 1
            jitter: boolean;
          };
      };
      context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
      images: {
        maxBase64Bytes:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
    };
    steering: {
      gate: "open" | "closed";
      promotedBatchCount: number;
      steers: {
        sessionId: string; // uuid
        turnId: string; // uuid
        steerId: string; // uuid
        sequence: number; // min 1
        // at least 1
        prompt: Array<
          | { type: "text"; text: string }
          | {
            type: "image";
            source:
              | {
                type: "url";
                url: string;
                mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              }
              | {
                type: "base64";
                data: string;
                mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              };
          }
          | { type: "content-reference"; reference: string /* max length 2048 */ }
        >;
        attribution: {
          clientId: string; // max length 256
          authorId?: string; // max length 256
        };
        acceptedAt: number;
        state:
          | { state: "accepted" }
          | { state: "promoted"; batch: number /* min 1 */; promotedAt: number }
          | {
            state: "undelivered";
            reason: "process_lost" | "turn_cancelled" | "turn_failed";
            undeliveredAt: number;
          };
      }[];
    };
    phase: "pending" | "running" | "completed" | "cancelled" | "failed";
    revision: number;
    parts: Array<
      | {
        type: "text";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "refusal";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "reasoning";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
        startedAt?: number;
        completedAt?: number;
      }
      | {
        type: "tool";
        id: string; // uuid
        toolCallId: string;
        toolId: string;
        origin?:
          | { kind: "model" }
          | {
            kind: "codemode";
            parentToolCallId: string;
            ordinal: number; // min 1
            ownerPluginId?: string;
            binding?: { snapshotId: string; bindingId: string; modelMessageId: string };
          };
        execution?: { result: unknown; logs: string[] };
        instructions?: Array<
          | {
            kind: "instruction";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            role: "system" | "developer" | "user";
            content: string;
            afterToolCallId?: string;
          }
          | {
            kind: "skill";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
            content: string;
          }
          | {
            kind: "plugin";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
          }
        >;
        assistantMessageIndex: number;
        modelInput?: unknown;
        input: unknown;
        state: "requested" | "completed" | "failed" | "denied";
        output?: unknown;
        fault?: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
        canonicalResult?:
          | {
            format: "content";
            // at least 1
            value: Array<
              | { type: "text"; text: string }
              | { type: "json"; value: unknown }
              | {
                type: "image";
                source:
                  | {
                    type: "url";
                    url: string;
                    mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  }
                  | {
                    type: "base64";
                    data: string;
                    mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  };
              }
            >;
          }
          | { format: "text"; value: string }
          | { format: "json"; value: unknown };
        approval:
          | { state: "none" }
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
          }
          | {
            state: "resolved";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
            resolvedAt: number;
            decision: "allow" | "deny";
            source: "config" | "saved" | "hook" | "callback" | "remote" | "default" | "timeout" | "terminal";
            reply?: "once" | "always" | "reject";
            replyMessage?: string; // max length 4096
          };
        question?:
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
          }
          | {
            state: "answered";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
            answers: string[][]; // at least 1
          }
          | {
            state: "dismissed";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
          };
        requestedAt: number;
        completedAt?: number;
        activity?: {
          checkpoint: number; // min 1
          updatedAt: number;
          message?: string; // max length 1024
          preview?: string;
          observedBytes: number;
          truncated: boolean;
          artifact?: {
            id: string; // uuid
            path: string;
            observedBytes: number;
            state: "writing" | "complete" | "incomplete";
          };
          childSessionId?: string; // uuid
        };
        artifact?: {
          id: string; // uuid
          path: string;
          observedBytes: number;
          state: "writing" | "complete" | "incomplete";
        };
      }
      | {
        type: "steering";
        id: string; // uuid
        batch: number; // min 1
        promotedAt: number;
        steers: {
          steerId: string; // uuid
          sequence: number; // min 1
          // at least 1
          prompt: Array<
            | { type: "text"; text: string }
            | {
              type: "image";
              source:
                | {
                  type: "url";
                  url: string;
                  mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                }
                | {
                  type: "base64";
                  data: string;
                  mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                };
            }
            | { type: "content-reference"; reference: string /* max length 2048 */ }
          >;
          attribution: {
            clientId: string; // max length 256
            authorId?: string; // max length 256
          };
          acceptedAt: number;
        }[];
      }
    >;
    usage?: {
      promptTokens: number | "Infinity" | "-Infinity" | "NaN";
      completionTokens: number | "Infinity" | "-Infinity" | "NaN";
      totalTokens: number | "Infinity" | "-Infinity" | "NaN";
      cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
      reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
    };
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
    cancellation?: { reason?: string; requestedAt: number };
    outcome?:
      | { kind: "completed"; turnId: string; text: string }
      | { kind: "cancelled"; turnId: string; reason?: string }
      | {
        kind: "failed";
        turnId: string;
        fault: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
      }
      | {
        kind: "limit_reached";
        turnId: string;
        limit:
          | {
            name: "turn_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "approval_wait";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_attempt_timeout";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "steering_batches";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "batches";
          }
          | {
            name: "provider_attempts";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "attempts";
          }
          | {
            name: "model_context";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "model_units";
            estimatedInputUnits: number;
            outputReserveUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            estimator: string; // max length 128
          };
        diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
      };
    acceptedAt: number;
    startedAt?: number;
    completedAt?: number;
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/permissions/{permissionRequestId}/reply`

**Reply to permission request.**
Records once, always, or reject for a durable pending permission request. A reply addressed to an ancestor Session is forwarded to the descendant sub-agent Session that owns the request, and the returned Turn is the owning Turn.

Operation ID: `replyPermission`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `permissionRequestId` | path | `string (uuid)` | yes |

Request body (`application/json`):

```ts
{ reply: "once" | "always" | "reject"; message?: string /* max length 4096 */ }
```

Response `200` (`application/json`):

```ts
{
  requestId: string; // uuid
  turn: {
    id: string; // uuid
    sessionId: string; // uuid
    sequence: number; // min 1
    request: {
      sessionId: string; // uuid
      turnId: string; // uuid
      // at least 1
      prompt: Array<
        | { type: "text"; text: string }
        | {
          type: "image";
          source:
            | {
              type: "url";
              url: string;
              mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            }
            | {
              type: "base64";
              data: string;
              mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            };
        }
        | { type: "content-reference"; reference: string /* max length 2048 */ }
      >;
      conversationEntry?: { entryId: string /* uuid */; historyRevision: number /* min 1 */ };
      model?: string;
      agent?: string; // max length 128
      skills?: string[]; // at least 1
      reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
    model: string;
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    policy: {
      version: 4;
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      permissionMatching: { caseSensitive: boolean };
      approval: {
        timeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      timeouts: {
        turnMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      steering: {
        maxBatches:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      subagents: {
        maxDepth:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      provider: {
        maxAttempts:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        attemptTimeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        elapsedMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        pacing:
          | { kind: "none" }
          | { kind: "fixed"; delayMs: number }
          | {
            kind: "exponential";
            initialDelayMs: number; // min 1
            maximumDelayMs: number; // min 1
            jitter: boolean;
          };
      };
      context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
      images: {
        maxBase64Bytes:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
    };
    steering: {
      gate: "open" | "closed";
      promotedBatchCount: number;
      steers: {
        sessionId: string; // uuid
        turnId: string; // uuid
        steerId: string; // uuid
        sequence: number; // min 1
        // at least 1
        prompt: Array<
          | { type: "text"; text: string }
          | {
            type: "image";
            source:
              | {
                type: "url";
                url: string;
                mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              }
              | {
                type: "base64";
                data: string;
                mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              };
          }
          | { type: "content-reference"; reference: string /* max length 2048 */ }
        >;
        attribution: {
          clientId: string; // max length 256
          authorId?: string; // max length 256
        };
        acceptedAt: number;
        state:
          | { state: "accepted" }
          | { state: "promoted"; batch: number /* min 1 */; promotedAt: number }
          | {
            state: "undelivered";
            reason: "process_lost" | "turn_cancelled" | "turn_failed";
            undeliveredAt: number;
          };
      }[];
    };
    phase: "pending" | "running" | "completed" | "cancelled" | "failed";
    revision: number;
    parts: Array<
      | {
        type: "text";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "refusal";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "reasoning";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
        startedAt?: number;
        completedAt?: number;
      }
      | {
        type: "tool";
        id: string; // uuid
        toolCallId: string;
        toolId: string;
        origin?:
          | { kind: "model" }
          | {
            kind: "codemode";
            parentToolCallId: string;
            ordinal: number; // min 1
            ownerPluginId?: string;
            binding?: { snapshotId: string; bindingId: string; modelMessageId: string };
          };
        execution?: { result: unknown; logs: string[] };
        instructions?: Array<
          | {
            kind: "instruction";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            role: "system" | "developer" | "user";
            content: string;
            afterToolCallId?: string;
          }
          | {
            kind: "skill";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
            content: string;
          }
          | {
            kind: "plugin";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
          }
        >;
        assistantMessageIndex: number;
        modelInput?: unknown;
        input: unknown;
        state: "requested" | "completed" | "failed" | "denied";
        output?: unknown;
        fault?: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
        canonicalResult?:
          | {
            format: "content";
            // at least 1
            value: Array<
              | { type: "text"; text: string }
              | { type: "json"; value: unknown }
              | {
                type: "image";
                source:
                  | {
                    type: "url";
                    url: string;
                    mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  }
                  | {
                    type: "base64";
                    data: string;
                    mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  };
              }
            >;
          }
          | { format: "text"; value: string }
          | { format: "json"; value: unknown };
        approval:
          | { state: "none" }
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
          }
          | {
            state: "resolved";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
            resolvedAt: number;
            decision: "allow" | "deny";
            source: "config" | "saved" | "hook" | "callback" | "remote" | "default" | "timeout" | "terminal";
            reply?: "once" | "always" | "reject";
            replyMessage?: string; // max length 4096
          };
        question?:
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
          }
          | {
            state: "answered";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
            answers: string[][]; // at least 1
          }
          | {
            state: "dismissed";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
          };
        requestedAt: number;
        completedAt?: number;
        activity?: {
          checkpoint: number; // min 1
          updatedAt: number;
          message?: string; // max length 1024
          preview?: string;
          observedBytes: number;
          truncated: boolean;
          artifact?: {
            id: string; // uuid
            path: string;
            observedBytes: number;
            state: "writing" | "complete" | "incomplete";
          };
          childSessionId?: string; // uuid
        };
        artifact?: {
          id: string; // uuid
          path: string;
          observedBytes: number;
          state: "writing" | "complete" | "incomplete";
        };
      }
      | {
        type: "steering";
        id: string; // uuid
        batch: number; // min 1
        promotedAt: number;
        steers: {
          steerId: string; // uuid
          sequence: number; // min 1
          // at least 1
          prompt: Array<
            | { type: "text"; text: string }
            | {
              type: "image";
              source:
                | {
                  type: "url";
                  url: string;
                  mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                }
                | {
                  type: "base64";
                  data: string;
                  mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                };
            }
            | { type: "content-reference"; reference: string /* max length 2048 */ }
          >;
          attribution: {
            clientId: string; // max length 256
            authorId?: string; // max length 256
          };
          acceptedAt: number;
        }[];
      }
    >;
    usage?: {
      promptTokens: number | "Infinity" | "-Infinity" | "NaN";
      completionTokens: number | "Infinity" | "-Infinity" | "NaN";
      totalTokens: number | "Infinity" | "-Infinity" | "NaN";
      cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
      reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
    };
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
    cancellation?: { reason?: string; requestedAt: number };
    outcome?:
      | { kind: "completed"; turnId: string; text: string }
      | { kind: "cancelled"; turnId: string; reason?: string }
      | {
        kind: "failed";
        turnId: string;
        fault: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
      }
      | {
        kind: "limit_reached";
        turnId: string;
        limit:
          | {
            name: "turn_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "approval_wait";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_attempt_timeout";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "steering_batches";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "batches";
          }
          | {
            name: "provider_attempts";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "attempts";
          }
          | {
            name: "model_context";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "model_units";
            estimatedInputUnits: number;
            outputReserveUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            estimator: string; // max length 128
          };
        diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
      };
    acceptedAt: number;
    startedAt?: number;
    completedAt?: number;
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/permissions/descendants/pending`

**List descendant approvals.**
Returns the pending permission requests owned by descendant sub-agent Sessions, oldest first.

Operation ID: `listDescendantPendingApprovals`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  approvals: {
    request: {
      id: string; // uuid
      sessionId: string; // uuid
      turnId: string; // uuid
      toolId: string;
      toolCallId: string;
      action: string;
      resources: string[]; // at least 1
      save?: string[];
      metadata?: unknown;
    };
    requestedAt: number;
    agent?: string; // max length 128
  }[];
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/questions/{questionRequestId}/reply`

**Reply to question request.**
Records answers for a durable pending user question. A reply addressed to an ancestor Session is forwarded to the descendant sub-agent Session that owns the request, and the returned Turn is the owning Turn.

Operation ID: `replyQuestion`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `questionRequestId` | path | `string (uuid)` | yes |

Request body (`application/json`):

```ts
{ answers: string[][] /* at least 1 */ }
```

Response `200` (`application/json`):

```ts
{
  requestId: string; // uuid
  turn: {
    id: string; // uuid
    sessionId: string; // uuid
    sequence: number; // min 1
    request: {
      sessionId: string; // uuid
      turnId: string; // uuid
      // at least 1
      prompt: Array<
        | { type: "text"; text: string }
        | {
          type: "image";
          source:
            | {
              type: "url";
              url: string;
              mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            }
            | {
              type: "base64";
              data: string;
              mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            };
        }
        | { type: "content-reference"; reference: string /* max length 2048 */ }
      >;
      conversationEntry?: { entryId: string /* uuid */; historyRevision: number /* min 1 */ };
      model?: string;
      agent?: string; // max length 128
      skills?: string[]; // at least 1
      reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
    model: string;
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    policy: {
      version: 4;
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      permissionMatching: { caseSensitive: boolean };
      approval: {
        timeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      timeouts: {
        turnMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      steering: {
        maxBatches:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      subagents: {
        maxDepth:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      provider: {
        maxAttempts:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        attemptTimeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        elapsedMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        pacing:
          | { kind: "none" }
          | { kind: "fixed"; delayMs: number }
          | {
            kind: "exponential";
            initialDelayMs: number; // min 1
            maximumDelayMs: number; // min 1
            jitter: boolean;
          };
      };
      context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
      images: {
        maxBase64Bytes:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
    };
    steering: {
      gate: "open" | "closed";
      promotedBatchCount: number;
      steers: {
        sessionId: string; // uuid
        turnId: string; // uuid
        steerId: string; // uuid
        sequence: number; // min 1
        // at least 1
        prompt: Array<
          | { type: "text"; text: string }
          | {
            type: "image";
            source:
              | {
                type: "url";
                url: string;
                mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              }
              | {
                type: "base64";
                data: string;
                mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              };
          }
          | { type: "content-reference"; reference: string /* max length 2048 */ }
        >;
        attribution: {
          clientId: string; // max length 256
          authorId?: string; // max length 256
        };
        acceptedAt: number;
        state:
          | { state: "accepted" }
          | { state: "promoted"; batch: number /* min 1 */; promotedAt: number }
          | {
            state: "undelivered";
            reason: "process_lost" | "turn_cancelled" | "turn_failed";
            undeliveredAt: number;
          };
      }[];
    };
    phase: "pending" | "running" | "completed" | "cancelled" | "failed";
    revision: number;
    parts: Array<
      | {
        type: "text";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "refusal";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "reasoning";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
        startedAt?: number;
        completedAt?: number;
      }
      | {
        type: "tool";
        id: string; // uuid
        toolCallId: string;
        toolId: string;
        origin?:
          | { kind: "model" }
          | {
            kind: "codemode";
            parentToolCallId: string;
            ordinal: number; // min 1
            ownerPluginId?: string;
            binding?: { snapshotId: string; bindingId: string; modelMessageId: string };
          };
        execution?: { result: unknown; logs: string[] };
        instructions?: Array<
          | {
            kind: "instruction";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            role: "system" | "developer" | "user";
            content: string;
            afterToolCallId?: string;
          }
          | {
            kind: "skill";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
            content: string;
          }
          | {
            kind: "plugin";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
          }
        >;
        assistantMessageIndex: number;
        modelInput?: unknown;
        input: unknown;
        state: "requested" | "completed" | "failed" | "denied";
        output?: unknown;
        fault?: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
        canonicalResult?:
          | {
            format: "content";
            // at least 1
            value: Array<
              | { type: "text"; text: string }
              | { type: "json"; value: unknown }
              | {
                type: "image";
                source:
                  | {
                    type: "url";
                    url: string;
                    mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  }
                  | {
                    type: "base64";
                    data: string;
                    mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  };
              }
            >;
          }
          | { format: "text"; value: string }
          | { format: "json"; value: unknown };
        approval:
          | { state: "none" }
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
          }
          | {
            state: "resolved";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
            resolvedAt: number;
            decision: "allow" | "deny";
            source: "config" | "saved" | "hook" | "callback" | "remote" | "default" | "timeout" | "terminal";
            reply?: "once" | "always" | "reject";
            replyMessage?: string; // max length 4096
          };
        question?:
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
          }
          | {
            state: "answered";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
            answers: string[][]; // at least 1
          }
          | {
            state: "dismissed";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
          };
        requestedAt: number;
        completedAt?: number;
        activity?: {
          checkpoint: number; // min 1
          updatedAt: number;
          message?: string; // max length 1024
          preview?: string;
          observedBytes: number;
          truncated: boolean;
          artifact?: {
            id: string; // uuid
            path: string;
            observedBytes: number;
            state: "writing" | "complete" | "incomplete";
          };
          childSessionId?: string; // uuid
        };
        artifact?: {
          id: string; // uuid
          path: string;
          observedBytes: number;
          state: "writing" | "complete" | "incomplete";
        };
      }
      | {
        type: "steering";
        id: string; // uuid
        batch: number; // min 1
        promotedAt: number;
        steers: {
          steerId: string; // uuid
          sequence: number; // min 1
          // at least 1
          prompt: Array<
            | { type: "text"; text: string }
            | {
              type: "image";
              source:
                | {
                  type: "url";
                  url: string;
                  mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                }
                | {
                  type: "base64";
                  data: string;
                  mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                };
            }
            | { type: "content-reference"; reference: string /* max length 2048 */ }
          >;
          attribution: {
            clientId: string; // max length 256
            authorId?: string; // max length 256
          };
          acceptedAt: number;
        }[];
      }
    >;
    usage?: {
      promptTokens: number | "Infinity" | "-Infinity" | "NaN";
      completionTokens: number | "Infinity" | "-Infinity" | "NaN";
      totalTokens: number | "Infinity" | "-Infinity" | "NaN";
      cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
      reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
    };
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
    cancellation?: { reason?: string; requestedAt: number };
    outcome?:
      | { kind: "completed"; turnId: string; text: string }
      | { kind: "cancelled"; turnId: string; reason?: string }
      | {
        kind: "failed";
        turnId: string;
        fault: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
      }
      | {
        kind: "limit_reached";
        turnId: string;
        limit:
          | {
            name: "turn_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "approval_wait";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_attempt_timeout";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "steering_batches";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "batches";
          }
          | {
            name: "provider_attempts";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "attempts";
          }
          | {
            name: "model_context";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "model_units";
            estimatedInputUnits: number;
            outputReserveUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            estimator: string; // max length 128
          };
        diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
      };
    acceptedAt: number;
    startedAt?: number;
    completedAt?: number;
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/questions/{questionRequestId}/reject`

**Reject question request.**
Dismisses a durable pending user question; the waiting tool fails with question_dismissed. Forwarding matches the question reply.

Operation ID: `rejectQuestion`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `questionRequestId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  requestId: string; // uuid
  turn: {
    id: string; // uuid
    sessionId: string; // uuid
    sequence: number; // min 1
    request: {
      sessionId: string; // uuid
      turnId: string; // uuid
      // at least 1
      prompt: Array<
        | { type: "text"; text: string }
        | {
          type: "image";
          source:
            | {
              type: "url";
              url: string;
              mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            }
            | {
              type: "base64";
              data: string;
              mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            };
        }
        | { type: "content-reference"; reference: string /* max length 2048 */ }
      >;
      conversationEntry?: { entryId: string /* uuid */; historyRevision: number /* min 1 */ };
      model?: string;
      agent?: string; // max length 128
      skills?: string[]; // at least 1
      reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
    model: string;
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    policy: {
      version: 4;
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      permissionMatching: { caseSensitive: boolean };
      approval: {
        timeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      timeouts: {
        turnMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      steering: {
        maxBatches:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      subagents: {
        maxDepth:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      provider: {
        maxAttempts:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        attemptTimeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        elapsedMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        pacing:
          | { kind: "none" }
          | { kind: "fixed"; delayMs: number }
          | {
            kind: "exponential";
            initialDelayMs: number; // min 1
            maximumDelayMs: number; // min 1
            jitter: boolean;
          };
      };
      context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
      images: {
        maxBase64Bytes:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
    };
    steering: {
      gate: "open" | "closed";
      promotedBatchCount: number;
      steers: {
        sessionId: string; // uuid
        turnId: string; // uuid
        steerId: string; // uuid
        sequence: number; // min 1
        // at least 1
        prompt: Array<
          | { type: "text"; text: string }
          | {
            type: "image";
            source:
              | {
                type: "url";
                url: string;
                mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              }
              | {
                type: "base64";
                data: string;
                mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              };
          }
          | { type: "content-reference"; reference: string /* max length 2048 */ }
        >;
        attribution: {
          clientId: string; // max length 256
          authorId?: string; // max length 256
        };
        acceptedAt: number;
        state:
          | { state: "accepted" }
          | { state: "promoted"; batch: number /* min 1 */; promotedAt: number }
          | {
            state: "undelivered";
            reason: "process_lost" | "turn_cancelled" | "turn_failed";
            undeliveredAt: number;
          };
      }[];
    };
    phase: "pending" | "running" | "completed" | "cancelled" | "failed";
    revision: number;
    parts: Array<
      | {
        type: "text";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "refusal";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "reasoning";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
        startedAt?: number;
        completedAt?: number;
      }
      | {
        type: "tool";
        id: string; // uuid
        toolCallId: string;
        toolId: string;
        origin?:
          | { kind: "model" }
          | {
            kind: "codemode";
            parentToolCallId: string;
            ordinal: number; // min 1
            ownerPluginId?: string;
            binding?: { snapshotId: string; bindingId: string; modelMessageId: string };
          };
        execution?: { result: unknown; logs: string[] };
        instructions?: Array<
          | {
            kind: "instruction";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            role: "system" | "developer" | "user";
            content: string;
            afterToolCallId?: string;
          }
          | {
            kind: "skill";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
            content: string;
          }
          | {
            kind: "plugin";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
          }
        >;
        assistantMessageIndex: number;
        modelInput?: unknown;
        input: unknown;
        state: "requested" | "completed" | "failed" | "denied";
        output?: unknown;
        fault?: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
        canonicalResult?:
          | {
            format: "content";
            // at least 1
            value: Array<
              | { type: "text"; text: string }
              | { type: "json"; value: unknown }
              | {
                type: "image";
                source:
                  | {
                    type: "url";
                    url: string;
                    mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  }
                  | {
                    type: "base64";
                    data: string;
                    mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  };
              }
            >;
          }
          | { format: "text"; value: string }
          | { format: "json"; value: unknown };
        approval:
          | { state: "none" }
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
          }
          | {
            state: "resolved";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
            resolvedAt: number;
            decision: "allow" | "deny";
            source: "config" | "saved" | "hook" | "callback" | "remote" | "default" | "timeout" | "terminal";
            reply?: "once" | "always" | "reject";
            replyMessage?: string; // max length 4096
          };
        question?:
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
          }
          | {
            state: "answered";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
            answers: string[][]; // at least 1
          }
          | {
            state: "dismissed";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
          };
        requestedAt: number;
        completedAt?: number;
        activity?: {
          checkpoint: number; // min 1
          updatedAt: number;
          message?: string; // max length 1024
          preview?: string;
          observedBytes: number;
          truncated: boolean;
          artifact?: {
            id: string; // uuid
            path: string;
            observedBytes: number;
            state: "writing" | "complete" | "incomplete";
          };
          childSessionId?: string; // uuid
        };
        artifact?: {
          id: string; // uuid
          path: string;
          observedBytes: number;
          state: "writing" | "complete" | "incomplete";
        };
      }
      | {
        type: "steering";
        id: string; // uuid
        batch: number; // min 1
        promotedAt: number;
        steers: {
          steerId: string; // uuid
          sequence: number; // min 1
          // at least 1
          prompt: Array<
            | { type: "text"; text: string }
            | {
              type: "image";
              source:
                | {
                  type: "url";
                  url: string;
                  mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                }
                | {
                  type: "base64";
                  data: string;
                  mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                };
            }
            | { type: "content-reference"; reference: string /* max length 2048 */ }
          >;
          attribution: {
            clientId: string; // max length 256
            authorId?: string; // max length 256
          };
          acceptedAt: number;
        }[];
      }
    >;
    usage?: {
      promptTokens: number | "Infinity" | "-Infinity" | "NaN";
      completionTokens: number | "Infinity" | "-Infinity" | "NaN";
      totalTokens: number | "Infinity" | "-Infinity" | "NaN";
      cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
      reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
    };
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
    cancellation?: { reason?: string; requestedAt: number };
    outcome?:
      | { kind: "completed"; turnId: string; text: string }
      | { kind: "cancelled"; turnId: string; reason?: string }
      | {
        kind: "failed";
        turnId: string;
        fault: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
      }
      | {
        kind: "limit_reached";
        turnId: string;
        limit:
          | {
            name: "turn_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "approval_wait";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_attempt_timeout";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "steering_batches";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "batches";
          }
          | {
            name: "provider_attempts";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "attempts";
          }
          | {
            name: "model_context";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "model_units";
            estimatedInputUnits: number;
            outputReserveUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            estimator: string; // max length 128
          };
        diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
      };
    acceptedAt: number;
    startedAt?: number;
    completedAt?: number;
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/questions/descendants/pending`

**List descendant questions.**
Returns the pending user questions owned by descendant sub-agent Sessions, oldest first.

Operation ID: `listDescendantPendingQuestions`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  questions: {
    request: {
      id: string; // uuid
      sessionId: string; // uuid
      turnId: string; // uuid
      toolId: string;
      toolCallId: string;
      // at least 1
      questions: {
        question: string; // max length 4096
        header: string; // max length 30
        // at least 1
        options: {
          label: string; // max length 256
          description: string; // max length 4096
        }[];
        multiple?: boolean;
        custom?: boolean;
      }[];
    };
    requestedAt: number;
    agent?: string; // max length 128
  }[];
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/plugins`

**Get Session plugin status.**
Returns the redacted desired and active Session plugin revisions, activation state, and the effective runtime plugin inventory.

Operation ID: `sessionPlugins`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  status: {
    sessionId: string; // uuid
    desired?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    desiredActivation?: {
      revisionId: string;
      state: "pending" | "started" | "active" | "failed";
      failure?: string;
    };
    active?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    plugins: {
      source: string;
      generationId: string;
      pluginId?: string;
      packageVersion?: string;
      status: "active" | "failed";
      registrations: string[];
      error?: string;
    }[];
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `PUT /v1/servers/{server}/sessions/{sessionId}/plugins`

**Add a Session plugin.**
Records an idempotent desired Session plugin revision that replaces the previous one and requests its activation.

Operation ID: `addSessionPlugin`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Request body (`application/json`):

```ts
{
  id: string;
  source:
    | { _tag: "Package"; name: string; requestedVersion?: string }
    | { _tag: "File"; uri: string }
    | { _tag: "Git"; url: string; ref?: string }
    | { _tag: "Bundle"; url: string }
    | { _tag: "Static"; id: string };
  resolved: { pluginId: string; version?: string; integrity?: string };
  options: unknown;
  mcpServers: Array<
    | {
      kind: "local";
      id: string; // max length 128
      name: string; // max length 128
      enabled?: boolean;
      order?: number;
      resourceReadTool?: boolean;
      protocolVersions: string[]; // at least 1
      clientCapabilities?: { roots: false; sampling: false; elicitation: false };
      limits?: {
        startupMs: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
        catalogMs: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
        executionMs: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
      reconnect?:
        | { kind: "manual" }
        | {
          kind: "retry";
          delayMs: number; // min 1
          maxAttempts: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
        };
      transport: {
        kind: "stdio";
        command: string;
        arguments: string[];
        environment: Record<string,
          | { kind: "environment"; reference: string /* max length 256 */ }
          | { kind: "secret"; reference: string /* max length 256 */ }
          | { kind: "oauth"; reference: string /* max length 256 */ }
        >;
      };
    }
    | {
      kind: "remote";
      id: string; // max length 128
      name: string; // max length 128
      enabled?: boolean;
      order?: number;
      resourceReadTool?: boolean;
      protocolVersions: string[]; // at least 1
      clientCapabilities?: { roots: false; sampling: false; elicitation: false };
      limits?: {
        startupMs: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
        catalogMs: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
        executionMs: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
      reconnect?:
        | { kind: "manual" }
        | {
          kind: "retry";
          delayMs: number; // min 1
          maxAttempts: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
        };
      transport: {
        kind: "streamable-http";
        endpoint: string; // max length 2048
        headers: Record<string,
          | { kind: "environment"; reference: string /* max length 256 */ }
          | { kind: "secret"; reference: string /* max length 256 */ }
          | { kind: "oauth"; reference: string /* max length 256 */ }
        >;
        oauth?: { kind: "oauth"; reference: string /* max length 256 */ };
      };
    }
  >;
  skills: Array<
    | {
      kind: "declaration";
      declaration: {
        id: string; // max length 128
        displayName: string;
        description: string;
        body: string;
        version: string;
        modelAdvertisement: { advertised: boolean; userInvocable: boolean };
        publicMetadata: { author?: string; license?: string; homepage?: string; tags: string[] };
        files?: string[];
      };
    }
    | {
      kind: "source";
      source:
        | { kind: "workspace"; id: string /* max length 128 */; directory: string }
        | {
          kind: "http";
          id: string; // max length 128
          catalogUrl: string; // max length 2048
          headers: { name: string /* max length 128 */; value: string /* max length 4096 */ }[];
        };
    }
  >;
}
```

Response `200` (`application/json`):

```ts
{
  status: {
    sessionId: string; // uuid
    desired?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    desiredActivation?: {
      revisionId: string;
      state: "pending" | "started" | "active" | "failed";
      failure?: string;
    };
    active?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    plugins: {
      source: string;
      generationId: string;
      pluginId?: string;
      packageVersion?: string;
      status: "active" | "failed";
      registrations: string[];
      error?: string;
    }[];
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `DELETE /v1/servers/{server}/sessions/{sessionId}/plugins`

**Remove the Session plugin.**
Clears the Session overlay so later Turns use the host baseline.

Operation ID: `removeSessionPlugin`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Request body (`application/json`):

```ts
unknown
```

Response `200` (`application/json`):

```ts
{
  status: {
    sessionId: string; // uuid
    desired?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    desiredActivation?: {
      revisionId: string;
      state: "pending" | "started" | "active" | "failed";
      failure?: string;
    };
    active?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    plugins: {
      source: string;
      generationId: string;
      pluginId?: string;
      packageVersion?: string;
      status: "active" | "failed";
      registrations: string[];
      error?: string;
    }[];
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/plugins/reload`

**Reload the Session plugin.**
Requests lazy reconstruction and activation of the desired overlay revision.

Operation ID: `reloadSessionPlugin`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Request body (`application/json`):

```ts
unknown
```

Response `200` (`application/json`):

```ts
{
  status: {
    sessionId: string; // uuid
    desired?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    desiredActivation?: {
      revisionId: string;
      state: "pending" | "started" | "active" | "failed";
      failure?: string;
    };
    active?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    plugins: {
      source: string;
      generationId: string;
      pluginId?: string;
      packageVersion?: string;
      status: "active" | "failed";
      registrations: string[];
      error?: string;
    }[];
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/plugins/refresh`

**Refresh the Session plugin.**
Re-resolves the active overlay source; only this mutation may adopt a newer unpinned artifact.

Operation ID: `refreshSessionPlugin`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Request body (`application/json`):

```ts
{ id: string }
```

Response `200` (`application/json`):

```ts
{
  status: {
    sessionId: string; // uuid
    desired?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    desiredActivation?: {
      revisionId: string;
      state: "pending" | "started" | "active" | "failed";
      failure?: string;
    };
    active?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    plugins: {
      source: string;
      generationId: string;
      pluginId?: string;
      packageVersion?: string;
      status: "active" | "failed";
      registrations: string[];
      error?: string;
    }[];
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/mcp-credentials/{serverName}/authorize`

**Start MCP OAuth authorization.**
Starts or idempotently resumes user authorization for one remote MCP server and returns only the pending status and the authorization URL.

Operation ID: `startMcpCredential`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `serverName` | path | `string` | yes |

Request body (`application/json`):

```ts
{
  resource?: string;
  challenge?: {
    scheme: "Bearer";
    resourceMetadata: string;
    error?: "invalid_token" | "insufficient_scope";
    scope?: string;
  };
  authorizationServer?: string;
  client?: { clientId: string; tokenEndpointAuthMethod: "none" };
}
```

Response `202` (`application/json`):

```ts
{
  status: { kind: "pending"; generation: number /* min 1 */ };
  authorizationUrl: string;
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/mcp-credentials/{serverName}`

**Get MCP OAuth credential status.**
Returns the secret-free status of one Session MCP server credential.

Operation ID: `getMcpCredential`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `serverName` | path | `string` | yes |

Response `200` (`application/json`):

```ts
{
  status:
    | { kind: "absent"; generation: number }
    | { kind: "pending"; generation: number /* min 1 */ }
    | { kind: "authorized"; generation: number /* min 1 */ }
    | { kind: "expired"; generation: number /* min 1 */; expiredAtEpochMs: number }
    | {
      kind: "authorization-required";
      generation: number; // min 1
      reason: "client-registration-uncertain" | "authorization-code-uncertain" | "refresh-uncertain";
    }
    | {
      kind: "forgotten";
      generation: number; // min 1
      revocation: "completed" | "unsupported" | "not-applicable" | "not-attempted" | "failed" | "uncertain";
    };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/mcp-credentials/{serverName}/callback`

**Complete MCP OAuth callback.**
Completes one external OAuth callback through the private lifecycle; the exchanged token never appears in the response.

Operation ID: `completeMcpCredentialCallback`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `serverName` | path | `string` | yes |

Request body (`application/json`):

```ts
{
  callback:
    | { kind: "success"; state: string; code: string; issuer?: string }
    | {
      kind: "denied";
      state: string;
      error: "access_denied" | "consent_required" | "interaction_required" | "invalid_request" | "invalid_scope" | "login_required" | "server_error" | "temporarily_unavailable" | "unauthorized_client" | "unsupported_response_type";
      issuer?: string;
    };
}
```

Response `200` (`application/json`):

```ts
{
  status:
    | { kind: "absent"; generation: number }
    | { kind: "pending"; generation: number /* min 1 */ }
    | { kind: "authorized"; generation: number /* min 1 */ }
    | { kind: "expired"; generation: number /* min 1 */; expiredAtEpochMs: number }
    | {
      kind: "authorization-required";
      generation: number; // min 1
      reason: "client-registration-uncertain" | "authorization-code-uncertain" | "refresh-uncertain";
    }
    | {
      kind: "forgotten";
      generation: number; // min 1
      revocation: "completed" | "unsupported" | "not-applicable" | "not-attempted" | "failed" | "uncertain";
    };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/mcp-credentials/{serverName}/cancel`

**Cancel MCP OAuth authorization.**
Cancels a pending MCP OAuth authorization and returns the resulting status.

Operation ID: `cancelMcpCredential`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `serverName` | path | `string` | yes |

Request body (`application/json`):

```ts
{ generation?: number /* min 1 */ }
```

Response `200` (`application/json`):

```ts
{
  status:
    | { kind: "absent"; generation: number }
    | { kind: "pending"; generation: number /* min 1 */ }
    | { kind: "authorized"; generation: number /* min 1 */ }
    | { kind: "expired"; generation: number /* min 1 */; expiredAtEpochMs: number }
    | {
      kind: "authorization-required";
      generation: number; // min 1
      reason: "client-registration-uncertain" | "authorization-code-uncertain" | "refresh-uncertain";
    }
    | {
      kind: "forgotten";
      generation: number; // min 1
      revocation: "completed" | "unsupported" | "not-applicable" | "not-attempted" | "failed" | "uncertain";
    };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/servers/{server}/sessions/{sessionId}/mcp-credentials/{serverName}/forget`

**Forget MCP OAuth credential.**
Revokes and forgets one Session MCP server credential and retires its live connections.

Operation ID: `forgetMcpCredential`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |
| `serverName` | path | `string` | yes |

Request body (`application/json`):

```ts
unknown
```

Response `200` (`application/json`):

```ts
{
  generation: number; // min 1
  revocation: "completed" | "unsupported" | "not-applicable" | "not-attempted" | "failed" | "uncertain";
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/models`

**Get Session models.**
Returns the adopted host catalog snapshot for the Session.

Operation ID: `sessionModels`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  hostRevision: string; // max length 128
  defaultModel?: string; // max length 641
  providers: {
    id: string; // max length 128
    displayName: string; // max length 256
    availability:
      | { status: "available" }
      | {
        status: "unavailable";
        reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
      };
  }[];
  models: {
    providerId: string; // max length 128
    ref: string; // max length 641
    id: string; // max length 512
    upstreamId: string; // max length 512
    displayName: string; // max length 256
    capabilities: {
      input: ("text" | "image")[]; // at least 1
      output: "text"[]; // at least 1
      tools: boolean;
      image?: {
        referenceTypes: ("url" | "base64")[]; // at least 1
        mimeTypes: ("image/jpeg" | "image/png" | "image/gif" | "image/webp")[]; // at least 1
      };
      // at least 1
      reasoningEfforts?: ("none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max")[];
    };
    limits: { contextUnits: number; outputUnits: number };
    pricing:
      | {
        version: "v1";
        currency: string; // max length 3
        unit: "million_model_units";
        rates: {
          input: string; // max length 128
          output: string; // max length 128
          cacheReadInput?: string; // max length 128
          cacheWriteInput?: string; // max length 128
        };
      }
      | { version: "unknown" };
    defaults: {
      temperature?: number;
      topP?: number; // max 1
      maxOutputUnits?: number; // min 1
      stopSequences?: string[]; // at least 1
      seed?: number;
      reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
    };
    availability:
      | { status: "available" }
      | {
        status: "unavailable";
        reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
      };
  }[];
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/models/events`

**Stream Session model revision events.**
Streams revision-only SSE events whenever the Session adopts a new host catalog revision.

Operation ID: `sessionModelEvents`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Response `200`: no body.

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/servers/{server}/sessions/{sessionId}/agents`

**List Session agents.**
Returns the effective host and Session agents with their display metadata and modes.

Operation ID: `sessionAgents`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `server` | path | `string` | yes |
| `sessionId` | path | `string (uuid)` | yes |

Response `200` (`application/json`):

```ts
{
  defaultAgent?: string; // max length 128
  agents: {
    id: string; // max length 128
    displayName: string;
    description: string;
    model?: string; // max length 641
    mode: "primary" | "subagent" | "all";
    origin: "host" | "session";
  }[];
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

## Runtime

### `GET /v1/runtime/plugins`

**List runtime plugins.**
Returns safe plugin registration metadata.

Operation ID: `plugins`

Response `200` (`application/json`):

```ts
{
  plugins: {
    source: string;
    generationId: string;
    pluginId?: string;
    packageVersion?: string;
    status: "active" | "failed";
    registrations: string[];
    error?: string;
  }[];
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/runtime/skills`

**List runtime Skills.**
Returns safe host Skill metadata.

Operation ID: `skills`

Response `200` (`application/json`):

```ts
{
  skills: {
    id: string; // max length 128
    displayName: string;
    description: string;
    advertised: boolean;
    userInvocable: boolean;
    origin: "host" | "session";
  }[];
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/runtime/reload`

**Reload runtime.**
Requests a trusted runtime plugin reload.

Operation ID: `reload`

Request body (`application/json`):

```ts
unknown
```

Response `200` (`application/json`):

```ts
{
  result: "reloaded" | "rejected";
  plugins: {
    source: string;
    generationId: string;
    pluginId?: string;
    packageVersion?: string;
    status: "active" | "failed";
    registrations: string[];
    error?: string;
  }[];
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/runtime/models`

**List runtime models.**
Returns the current host model catalog snapshot.

Operation ID: `models`

Response `200` (`application/json`):

```ts
{
  hostRevision: string; // max length 128
  defaultModel?: string; // max length 641
  providers: {
    id: string; // max length 128
    displayName: string; // max length 256
    availability:
      | { status: "available" }
      | {
        status: "unavailable";
        reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
      };
  }[];
  models: {
    providerId: string; // max length 128
    ref: string; // max length 641
    id: string; // max length 512
    upstreamId: string; // max length 512
    displayName: string; // max length 256
    capabilities: {
      input: ("text" | "image")[]; // at least 1
      output: "text"[]; // at least 1
      tools: boolean;
      image?: {
        referenceTypes: ("url" | "base64")[]; // at least 1
        mimeTypes: ("image/jpeg" | "image/png" | "image/gif" | "image/webp")[]; // at least 1
      };
      // at least 1
      reasoningEfforts?: ("none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max")[];
    };
    limits: { contextUnits: number; outputUnits: number };
    pricing:
      | {
        version: "v1";
        currency: string; // max length 3
        unit: "million_model_units";
        rates: {
          input: string; // max length 128
          output: string; // max length 128
          cacheReadInput?: string; // max length 128
          cacheWriteInput?: string; // max length 128
        };
      }
      | { version: "unknown" };
    defaults: {
      temperature?: number;
      topP?: number; // max 1
      maxOutputUnits?: number; // min 1
      stopSequences?: string[]; // at least 1
      seed?: number;
      reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
    };
    availability:
      | { status: "available" }
      | {
        status: "unavailable";
        reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
      };
  }[];
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/runtime/models/refresh`

**Refresh provider models.**
Re-discovers models from the provider (one, or every discovery provider) and returns the resulting catalog. Connecting a provider, and a prompt naming a model the catalog lacks, refresh the same way.

Operation ID: `refreshProviderModels`

Request body (`application/json`):

```ts
{ providerId?: string /* max length 128 */ }
```

Response `200` (`application/json`):

```ts
{
  providers: {
    providerId: string; // max length 128
    status: "updated" | "unchanged" | "failed";
    message?: string;
  }[];
  snapshot: {
    hostRevision: string; // max length 128
    defaultModel?: string; // max length 641
    providers: {
      id: string; // max length 128
      displayName: string; // max length 256
      availability:
        | { status: "available" }
        | {
          status: "unavailable";
          reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
        };
    }[];
    models: {
      providerId: string; // max length 128
      ref: string; // max length 641
      id: string; // max length 512
      upstreamId: string; // max length 512
      displayName: string; // max length 256
      capabilities: {
        input: ("text" | "image")[]; // at least 1
        output: "text"[]; // at least 1
        tools: boolean;
        image?: {
          referenceTypes: ("url" | "base64")[]; // at least 1
          mimeTypes: ("image/jpeg" | "image/png" | "image/gif" | "image/webp")[]; // at least 1
        };
        // at least 1
        reasoningEfforts?: ("none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max")[];
      };
      limits: { contextUnits: number; outputUnits: number };
      pricing:
        | {
          version: "v1";
          currency: string; // max length 3
          unit: "million_model_units";
          rates: {
            input: string; // max length 128
            output: string; // max length 128
            cacheReadInput?: string; // max length 128
            cacheWriteInput?: string; // max length 128
          };
        }
        | { version: "unknown" };
      defaults: {
        temperature?: number;
        topP?: number; // max 1
        maxOutputUnits?: number; // min 1
        stopSequences?: string[]; // at least 1
        seed?: number;
        reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      };
      availability:
        | { status: "available" }
        | {
          status: "unavailable";
          reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
        };
    }[];
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/runtime/models/events`

**Stream runtime model revision events.**
Streams revision-only SSE events whenever the runtime model catalog revision changes.

Operation ID: `modelEvents`

Response `200`: no body.

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/runtime/providers`

**List runtime providers.**
Returns safe runtime provider summaries and connection status.

Operation ID: `providers`

Response `200` (`application/json`):

```ts
{
  providers: {
    id: string; // max length 128
    displayName: string;
    availability:
      | { status: "available" }
      | {
        status: "unavailable";
        reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
      };
    source: "stored" | "environment" | "none" | "via";
    via?: string; // max length 128
    connection?: {
      connectionId: string; // max length 128
      providerId: string; // max length 128
      label: string; // max length 256
      method: "api_key" | "oauth";
      status: "ready" | "reconnect_required";
      createdAt: number;
      updatedAt: number;
    };
    methods: ("api_key" | "oauth")[];
    logins: {
      id: string;
      label: string;
      notice?: { text: string; links: { label: string; url: string }[] };
    }[];
  }[];
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/runtime/providers/{providerId}`

**Get runtime provider.**
Returns a safe runtime provider summary by ID.

Operation ID: `getProvider`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `providerId` | path | `string` | yes |

Response `200` (`application/json`):

```ts
{
  provider: {
    id: string; // max length 128
    displayName: string;
    availability:
      | { status: "available" }
      | {
        status: "unavailable";
        reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
      };
    source: "stored" | "environment" | "none" | "via";
    via?: string; // max length 128
    connection?: {
      connectionId: string; // max length 128
      providerId: string; // max length 128
      label: string; // max length 256
      method: "api_key" | "oauth";
      status: "ready" | "reconnect_required";
      createdAt: number;
      updatedAt: number;
    };
    methods: ("api_key" | "oauth")[];
    logins: {
      id: string;
      label: string;
      notice?: { text: string; links: { label: string; url: string }[] };
    }[];
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/runtime/providers/{providerId}/connect/key`

**Connect provider API key.**
Stores an API key for the provider, replacing any previous key atomically.

Operation ID: `connectProviderKey`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `providerId` | path | `string` | yes |

Request body (`application/json`):

```ts
{ apiKey: string; label?: string /* max length 256 */ }
```

Response `200` (`application/json`):

```ts
{
  connection: {
    connectionId: string; // max length 128
    providerId: string; // max length 128
    label: string; // max length 256
    method: "api_key" | "oauth";
    status: "ready" | "reconnect_required";
    createdAt: number;
    updatedAt: number;
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `POST /v1/runtime/providers/{providerId}/logins`

**Start provider login.**
Starts a host-held login and returns the prompt to show the user. The host completes the provider exchange.

Operation ID: `startProviderLogin`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `providerId` | path | `string` | yes |

Request body (`application/json`):

```ts
{ methodId?: string }
```

Response `200` (`application/json`):

```ts
| {
    status: "pending";
    loginId: string; // max length 128
    methodId: string;
    prompt: { kind: "device"; verificationUrl: string; userCode: string };
    expiresAt: number | "Infinity" | "-Infinity" | "NaN";
  }
  | {
    status: "connected";
    loginId: string; // max length 128
    connection: {
      connectionId: string; // max length 128
      providerId: string; // max length 128
      label: string; // max length 256
      method: "api_key" | "oauth";
      status: "ready" | "reconnect_required";
      createdAt: number;
      updatedAt: number;
    };
  }
  | {
    status: "failed";
    loginId: string; // max length 128
    reason: "denied" | "expired" | "cancelled" | "error";
    message: string;
  }
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `GET /v1/runtime/providers/{providerId}/logins/{loginId}`

**Get provider login.**
Returns the login status, optionally waiting up to waitMs for it to change.

Operation ID: `getProviderLogin`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `providerId` | path | `string` | yes |
| `loginId` | path | `string` | yes |
| `waitMs` | query | `string` | no |

Response `200` (`application/json`):

```ts
| {
    status: "pending";
    loginId: string; // max length 128
    methodId: string;
    prompt: { kind: "device"; verificationUrl: string; userCode: string };
    expiresAt: number | "Infinity" | "-Infinity" | "NaN";
  }
  | {
    status: "connected";
    loginId: string; // max length 128
    connection: {
      connectionId: string; // max length 128
      providerId: string; // max length 128
      label: string; // max length 256
      method: "api_key" | "oauth";
      status: "ready" | "reconnect_required";
      createdAt: number;
      updatedAt: number;
    };
  }
  | {
    status: "failed";
    loginId: string; // max length 128
    reason: "denied" | "expired" | "cancelled" | "error";
    message: string;
  }
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `DELETE /v1/runtime/providers/{providerId}/logins/{loginId}`

**Cancel provider login.**
Cancels a pending login.

Operation ID: `cancelProviderLogin`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `providerId` | path | `string` | yes |
| `loginId` | path | `string` | yes |

Response `200` (`application/json`):

```ts
| {
    status: "pending";
    loginId: string; // max length 128
    methodId: string;
    prompt: { kind: "device"; verificationUrl: string; userCode: string };
    expiresAt: number | "Infinity" | "-Infinity" | "NaN";
  }
  | {
    status: "connected";
    loginId: string; // max length 128
    connection: {
      connectionId: string; // max length 128
      providerId: string; // max length 128
      label: string; // max length 256
      method: "api_key" | "oauth";
      status: "ready" | "reconnect_required";
      createdAt: number;
      updatedAt: number;
    };
  }
  | {
    status: "failed";
    loginId: string; // max length 128
    reason: "denied" | "expired" | "cancelled" | "error";
    message: string;
  }
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `PATCH /v1/runtime/providers/{providerId}/connections/{connectionId}`

**Update provider connection label.**
Updates the metadata label for a provider connection.

Operation ID: `updateProviderConnection`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `providerId` | path | `string` | yes |
| `connectionId` | path | `string` | yes |

Request body (`application/json`):

```ts
{ label: string /* max length 256 */ }
```

Response `200` (`application/json`):

```ts
{
  connection: {
    connectionId: string; // max length 128
    providerId: string; // max length 128
    label: string; // max length 256
    method: "api_key" | "oauth";
    status: "ready" | "reconnect_required";
    createdAt: number;
    updatedAt: number;
  };
}
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

### `DELETE /v1/runtime/providers/{providerId}/connections/{connectionId}`

**Delete provider connection.**
Deletes the provider connection by matching provider ID and connection ID.

Operation ID: `deleteProviderConnection`

| Parameter | In | Type | Required |
| --- | --- | --- | --- |
| `providerId` | path | `string` | yes |
| `connectionId` | path | `string` | yes |

Response `200` (`application/json`):

```ts
{ success: boolean }
```

Errors: `400` ValidationErrorEncoded, `401` UnauthorizedErrorEncoded, `403` ForbiddenErrorEncoded, `404` NotFoundErrorEncoded, `409` ConflictErrors, `500` InternalServerErrorEncoded, `503` UnavailableErrorEncoded.

## Shared schemas

### `UnauthorizedErrorEncoded`

```ts
{ _tag: "UnauthorizedError"; message: string }
```

### `UnavailableErrorEncoded`

```ts
{
  _tag: "UnavailableError";
  message: string;
  reason?: "model_unavailable" | "service_unavailable";
}
```

### `InternalServerErrorEncoded`

```ts
{ _tag: "InternalServerError"; message: string }
```

### `ConflictErrors`

```ts
| ConflictErrorEncoded
  | SteerConflictErrorEncoded
  | TurnNotActiveErrorEncoded
  | TurnNotSteerableErrorEncoded
```

### `TurnNotSteerableErrorEncoded`

```ts
{ _tag: "TurnNotSteerableError"; message: string }
```

### `TurnNotActiveErrorEncoded`

```ts
{ _tag: "TurnNotActiveError"; message: string }
```

### `SteerConflictErrorEncoded`

```ts
{ _tag: "SteerConflictError"; message: string }
```

### `ConflictErrorEncoded`

```ts
{ _tag: "ConflictError"; message: string }
```

### `NotFoundErrorEncoded`

```ts
{
  _tag: "NotFoundError";
  message: string;
  resource?: "session" | "turn" | "tool_call" | "mcp_server" | "mcp_prompt" | "mcp_resource" | "context_compaction" | "permission_request" | "question_request" | "saved_permission" | "endpoint" | "provider_login" | "provider" | "connection";
}
```

### `ForbiddenErrorEncoded`

```ts
{ _tag: "ForbiddenError"; message: string }
```

### `ValidationErrorEncoded`

```ts
{ _tag: "ValidationError"; message: string }
```

---

Generated from [`packages/protocol/src/`](https://github.com/ZephyrCloudIO/ze-harness/tree/main/packages/protocol/src).