@1claw/openapi-spec 0.16.1 → 0.17.0

package/README.md

@@ -40,10 +40,11 @@ openapi-generator generate \
 import spec from "@1claw/openapi-spec/openapi.json";
 ```
 
-## What's in the spec (v0.16.x)
+## What's in the spec (v0.17.x)
 
+- **Auth — agent JWT** — `POST /v1/auth/agent-token` documents optional JWT claim **`shroud_config`** when the agent has Shroud enabled (mirrors DB; consumed by Shroud PolicyEngine on LLM requests). Re-exchange after changing agent Shroud settings.
 - **Auth — password reset** — `POST /v1/auth/forgot-password`, `POST /v1/auth/reset-password` (public; anti-enumeration on forgot)
-- **Billing — LLM token billing** — `GET /v1/billing/llm-token-billing`, `POST .../subscribe`, `POST .../disable` (Stripe AI Gateway add-on; optional org feature)
+- **Billing — LLM token billing** — `GET /v1/billing/llm-token-billing` (`LlmTokenBillingStatus`: `enabled`, `subscription_status`, optional `credit_balance`, optional `billing_cycle_usage` with `metered_lines[]`), `POST .../subscribe`, `POST .../disable` (Stripe AI Gateway add-on; optional org feature)
 - **Treasury** — Safe multisig treasuries: `POST/GET /v1/treasury`, `GET/PATCH/DELETE /v1/treasury/{id}`, signers, agent access requests (`requests[]` on list)
 - **Vaults** — CRUD, CMEK enable/disable, key rotation with job tracking
 - **Secrets** — CRUD, versioning, CMEK-encrypted flag

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.6.0",
+    "version": "2.7.0",
     "description": "Secure secret management for AI agents. Provides vaults, secrets,\npolicy-based access control, agent identity, Intents API,\nsharing, billing, and audit logging.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.xyz"
@@ -153,6 +153,7 @@
           "Authentication"
         ],
         "summary": "Exchange agent credentials for JWT",
+        "description": "Returns a short-lived EdDSA-signed JWT (`access_token`). Standard claims include `sub`\n(`agent:<uuid>`), `org`, `scopes`, `vault_ids`, optional `intents_api_enabled`, optional\n`shroud_enabled`, optional `llm_token_billing` / `stripe_customer_id` when org LLM billing is on.\n\nWhen **`shroud_enabled`** is true, the JWT payload may include **`shroud_config`**: a JSON object\nmirroring the agent row in Vault (same shape as `ShroudConfig` on `GET /v1/agents/{id}`).\n**Shroud** (TEE proxy) decodes this on each LLM request and runs **PolicyEngine** after the\nglobal inspection pipeline so per-agent limits and threat **block** actions apply without a\nseparate policy fetch. Re-exchange the agent token after changing `shroud_config` so the JWT\nis fresh.\n\nUser JWTs from password, API key, or device flow do **not** include `shroud_config`.\n",
         "operationId": "agentToken",
         "security": [],
         "requestBody": {
@@ -2893,7 +2894,7 @@
         ],
         "summary": "Get LLM token billing status",
         "operationId": "getLlmTokenBilling",
-        "description": "Returns whether LLM token billing is enabled for the caller's org.",
+        "description": "Returns whether LLM token billing is enabled, optional Stripe billing credit balance (metered scope), and estimated cycle usage from the upcoming invoice—including per-line metered rows when Stripe returns them (amounts; quantities such as tokens when present).\n",
         "responses": {
           "200": {
             "description": "LLM token billing status",
@@ -4026,6 +4027,112 @@
           }
         }
       }
+    },
+    "/v1/shroud/activity": {
+      "get": {
+        "tags": [
+          "Shroud"
+        ],
+        "summary": "List Shroud activity events",
+        "description": "Returns recent Shroud proxy activity for the organization (LLM requests, inspections, policy actions).",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "agent_id",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Filter by agent ID"
+          },
+          {
+            "in": "query",
+            "name": "action",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Filter by action (allowed, blocked, warned)"
+          },
+          {
+            "in": "query",
+            "name": "limit",
+            "schema": {
+              "type": "integer",
+              "default": 50
+            },
+            "description": "Maximum events to return"
+          },
+          {
+            "in": "query",
+            "name": "offset",
+            "schema": {
+              "type": "integer",
+              "default": 0
+            },
+            "description": "Pagination offset"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Activity events",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "events": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/ShroudActivityEvent"
+                      }
+                    },
+                    "total": {
+                      "type": "integer"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      },
+      "post": {
+        "tags": [
+          "Shroud"
+        ],
+        "summary": "Ingest Shroud activity event (internal)",
+        "description": "Called by the Shroud proxy to record activity events. Not intended for external use.",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/IngestShroudActivityRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Event recorded"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
     }
   },
   "components": {
@@ -5614,6 +5721,27 @@
             "type": "boolean",
             "default": true,
             "description": "Whether to log all detected threats to audit (even when action is allow/warn)"
+          },
+          "tool_call_inspection": {
+            "$ref": "#/components/schemas/ToolCallPolicy"
+          },
+          "output_policy": {
+            "$ref": "#/components/schemas/OutputPolicy"
+          },
+          "secret_injection_detection": {
+            "$ref": "#/components/schemas/SecretInjectionConfig"
+          },
+          "advanced_redaction": {
+            "$ref": "#/components/schemas/AdvancedRedactionConfig"
+          },
+          "semantic_policy": {
+            "$ref": "#/components/schemas/SemanticPolicy"
+          },
+          "flagged_request_retention_days": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 365,
+            "description": "Number of days to retain flagged request bodies for replay/investigation"
           }
         }
       },
@@ -5820,6 +5948,221 @@
           }
         }
       },
+      "ToolCallPolicy": {
+        "type": "object",
+        "description": "Tool/function call inspection settings",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable tool call inspection"
+          },
+          "allowed_tool_names": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Allowed tool/function names (empty = all allowed)"
+          },
+          "denied_tool_names": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Denied tool/function names"
+          },
+          "scan_arguments": {
+            "type": "boolean",
+            "default": true,
+            "description": "Scan tool call arguments for credential exfiltration"
+          },
+          "block_credential_exfil": {
+            "type": "boolean",
+            "default": true,
+            "description": "Block tool calls that appear to exfiltrate credentials"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "block",
+              "sanitize",
+              "warn",
+              "log"
+            ],
+            "default": "block",
+            "description": "Action when a tool call violation is detected"
+          }
+        }
+      },
+      "OutputPolicy": {
+        "type": "object",
+        "description": "Output content policy settings for LLM responses",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable output content policies"
+          },
+          "blocked_patterns": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Custom regex patterns to block in responses"
+          },
+          "blocked_entities": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Named entities to block (e.g., competitor names)"
+          },
+          "block_harmful_content": {
+            "type": "boolean",
+            "default": false,
+            "description": "Block responses containing harmful content categories"
+          },
+          "harmful_categories": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "violence",
+                "self_harm",
+                "illegal",
+                "hate",
+                "sexual",
+                "malware"
+              ]
+            },
+            "description": "Harm categories to block"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "block",
+              "sanitize",
+              "warn",
+              "log"
+            ],
+            "default": "warn",
+            "description": "Action when output policy is violated"
+          }
+        }
+      },
+      "SecretInjectionConfig": {
+        "type": "object",
+        "description": "Detects credentials injected into prompts that are not from the vault",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable secret injection detection"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "block",
+              "sanitize",
+              "warn",
+              "log"
+            ],
+            "default": "block",
+            "description": "Action when injected credentials are detected"
+          },
+          "sensitivity": {
+            "type": "string",
+            "enum": [
+              "low",
+              "medium",
+              "high"
+            ],
+            "default": "medium",
+            "description": "Detection sensitivity level"
+          }
+        }
+      },
+      "AdvancedRedactionConfig": {
+        "type": "object",
+        "description": "Advanced secret redaction settings (base64-encoded, split, prefix leaks)",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable advanced redaction checks"
+          },
+          "detect_base64_encoded": {
+            "type": "boolean",
+            "default": false,
+            "description": "Detect base64-encoded vault secrets"
+          },
+          "detect_split_secrets": {
+            "type": "boolean",
+            "default": false,
+            "description": "Detect secrets split across tokens or messages"
+          },
+          "detect_prefix_leak": {
+            "type": "boolean",
+            "default": false,
+            "description": "Detect partial/prefix leaks of vault secrets"
+          },
+          "min_secret_length": {
+            "type": "integer",
+            "default": 16,
+            "description": "Minimum secret length to consider for advanced matching"
+          }
+        }
+      },
+      "SemanticPolicy": {
+        "type": "object",
+        "description": "Semantic/intent-level policy enforcement",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable semantic policy enforcement"
+          },
+          "allowed_topics": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Topics the agent is allowed to discuss (empty = all)"
+          },
+          "denied_topics": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Topics to block"
+          },
+          "allowed_tasks": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Tasks the agent is allowed to perform (empty = all)"
+          },
+          "denied_tasks": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Tasks to block (e.g., code_generation, data_export)"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "block",
+              "sanitize",
+              "warn",
+              "log"
+            ],
+            "default": "warn",
+            "description": "Action when semantic policy is violated"
+          }
+        }
+      },
       "AgentCreatedResponse": {
         "type": "object",
         "required": [
@@ -6777,8 +7120,83 @@
           }
         }
       },
+      "LlmMeteredInvoiceLine": {
+        "type": "object",
+        "description": "Metered line from Stripe upcoming invoice (usage detail when available).",
+        "properties": {
+          "description": {
+            "type": "string",
+            "nullable": true
+          },
+          "amount_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "quantity": {
+            "type": "number",
+            "nullable": true,
+            "description": "Billed usage units when Stripe returns quantity (e.g. tokens)."
+          },
+          "price_nickname": {
+            "type": "string",
+            "nullable": true
+          }
+        }
+      },
+      "LlmBillingCycleUsage": {
+        "type": "object",
+        "description": "Accrued LLM charges for the current Stripe subscription period (upcoming invoice).",
+        "properties": {
+          "period_start": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "period_end": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "accrued_usage_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "currency": {
+            "type": "string"
+          },
+          "metered_lines": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/LlmMeteredInvoiceLine"
+            }
+          }
+        }
+      },
+      "LlmCreditBalance": {
+        "type": "object",
+        "properties": {
+          "available_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "ledger_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "used_cents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "currency": {
+            "type": "string"
+          }
+        }
+      },
       "LlmTokenBillingStatus": {
         "type": "object",
+        "required": [
+          "enabled"
+        ],
         "properties": {
           "enabled": {
             "type": "boolean"
@@ -6789,6 +7207,12 @@
               "active",
               "inactive"
             ]
+          },
+          "credit_balance": {
+            "$ref": "#/components/schemas/LlmCreditBalance"
+          },
+          "billing_cycle_usage": {
+            "$ref": "#/components/schemas/LlmBillingCycleUsage"
           }
         }
       },
@@ -7400,6 +7824,116 @@
           }
         }
       },
+      "ShroudActivityEvent": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "action": {
+            "type": "string",
+            "description": "Action taken (allowed, blocked, warned)"
+          },
+          "request_tokens": {
+            "type": "integer"
+          },
+          "response_tokens": {
+            "type": "integer"
+          },
+          "latency_ms": {
+            "type": "integer"
+          },
+          "had_secrets_redacted": {
+            "type": "boolean"
+          },
+          "had_pii_detected": {
+            "type": "boolean"
+          },
+          "injection_score": {
+            "type": "number"
+          },
+          "policy_violations": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "metadata": {
+            "type": "object"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "IngestShroudActivityRequest": {
+        "type": "object",
+        "required": [
+          "agent_id",
+          "action"
+        ],
+        "properties": {
+          "agent_id": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "action": {
+            "type": "string"
+          },
+          "request_tokens": {
+            "type": "integer",
+            "default": 0
+          },
+          "response_tokens": {
+            "type": "integer",
+            "default": 0
+          },
+          "latency_ms": {
+            "type": "integer"
+          },
+          "had_secrets_redacted": {
+            "type": "boolean",
+            "default": false
+          },
+          "had_pii_detected": {
+            "type": "boolean",
+            "default": false
+          },
+          "injection_score": {
+            "type": "number",
+            "default": 0
+          },
+          "policy_violations": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "metadata": {
+            "type": "object"
+          }
+        }
+      },
       "HealthResponse": {
         "type": "object",
         "properties": {

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.6.0
+    version: 2.7.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -105,6 +105,19 @@ paths:
         post:
             tags: [Authentication]
             summary: Exchange agent credentials for JWT
+            description: |
+                Returns a short-lived EdDSA-signed JWT (`access_token`). Standard claims include `sub`
+                (`agent:<uuid>`), `org`, `scopes`, `vault_ids`, optional `intents_api_enabled`, optional
+                `shroud_enabled`, optional `llm_token_billing` / `stripe_customer_id` when org LLM billing is on.
+
+                When **`shroud_enabled`** is true, the JWT payload may include **`shroud_config`**: a JSON object
+                mirroring the agent row in Vault (same shape as `ShroudConfig` on `GET /v1/agents/{id}`).
+                **Shroud** (TEE proxy) decodes this on each LLM request and runs **PolicyEngine** after the
+                global inspection pipeline so per-agent limits and threat **block** actions apply without a
+                separate policy fetch. Re-exchange the agent token after changing `shroud_config` so the JWT
+                is fresh.
+
+                User JWTs from password, API key, or device flow do **not** include `shroud_config`.
             operationId: agentToken
             security: []
             requestBody:
@@ -1854,7 +1867,10 @@ paths:
             tags: [Billing]
             summary: Get LLM token billing status
             operationId: getLlmTokenBilling
-            description: Returns whether LLM token billing is enabled for the caller's org.
+            description: >
+                Returns whether LLM token billing is enabled, optional Stripe billing credit balance
+                (metered scope), and estimated cycle usage from the upcoming invoice—including per-line
+                metered rows when Stripe returns them (amounts; quantities such as tokens when present).
             responses:
                 "200":
                     description: LLM token billing status
@@ -2581,6 +2597,72 @@ paths:
                                         type: string
                                         enum: [ok, degraded, unavailable]
 
+    # --- Shroud Activity ---
+
+    /v1/shroud/activity:
+        get:
+            tags: [Shroud]
+            summary: List Shroud activity events
+            description: Returns recent Shroud proxy activity for the organization (LLM requests, inspections, policy actions).
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: query
+                  name: agent_id
+                  schema:
+                      type: string
+                  description: Filter by agent ID
+                - in: query
+                  name: action
+                  schema:
+                      type: string
+                  description: Filter by action (allowed, blocked, warned)
+                - in: query
+                  name: limit
+                  schema:
+                      type: integer
+                      default: 50
+                  description: Maximum events to return
+                - in: query
+                  name: offset
+                  schema:
+                      type: integer
+                      default: 0
+                  description: Pagination offset
+            responses:
+                "200":
+                    description: Activity events
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    events:
+                                        type: array
+                                        items:
+                                            $ref: "#/components/schemas/ShroudActivityEvent"
+                                    total:
+                                        type: integer
+                "401":
+                    description: Unauthorized
+        post:
+            tags: [Shroud]
+            summary: Ingest Shroud activity event (internal)
+            description: Called by the Shroud proxy to record activity events. Not intended for external use.
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/IngestShroudActivityRequest"
+            responses:
+                "201":
+                    description: Event recorded
+                "401":
+                    description: Unauthorized
+
 # =============================================================================
 # COMPONENTS
 # =============================================================================
@@ -3699,6 +3781,21 @@ components:
                     type: boolean
                     default: true
                     description: Whether to log all detected threats to audit (even when action is allow/warn)
+                tool_call_inspection:
+                    $ref: "#/components/schemas/ToolCallPolicy"
+                output_policy:
+                    $ref: "#/components/schemas/OutputPolicy"
+                secret_injection_detection:
+                    $ref: "#/components/schemas/SecretInjectionConfig"
+                advanced_redaction:
+                    $ref: "#/components/schemas/AdvancedRedactionConfig"
+                semantic_policy:
+                    $ref: "#/components/schemas/SemanticPolicy"
+                flagged_request_retention_days:
+                    type: integer
+                    minimum: 0
+                    maximum: 365
+                    description: Number of days to retain flagged request bodies for replay/investigation
 
         UnicodeNormalizationConfig:
             type: object
@@ -3834,6 +3931,150 @@ components:
                         type: string
                     description: Path patterns to block (e.g., /etc/passwd, ~/.ssh)
 
+        ToolCallPolicy:
+            type: object
+            description: Tool/function call inspection settings
+            properties:
+                enabled:
+                    type: boolean
+                    default: false
+                    description: Enable tool call inspection
+                allowed_tool_names:
+                    type: array
+                    items:
+                        type: string
+                    description: Allowed tool/function names (empty = all allowed)
+                denied_tool_names:
+                    type: array
+                    items:
+                        type: string
+                    description: Denied tool/function names
+                scan_arguments:
+                    type: boolean
+                    default: true
+                    description: Scan tool call arguments for credential exfiltration
+                block_credential_exfil:
+                    type: boolean
+                    default: true
+                    description: Block tool calls that appear to exfiltrate credentials
+                action:
+                    type: string
+                    enum: [block, sanitize, warn, log]
+                    default: block
+                    description: Action when a tool call violation is detected
+
+        OutputPolicy:
+            type: object
+            description: Output content policy settings for LLM responses
+            properties:
+                enabled:
+                    type: boolean
+                    default: false
+                    description: Enable output content policies
+                blocked_patterns:
+                    type: array
+                    items:
+                        type: string
+                    description: Custom regex patterns to block in responses
+                blocked_entities:
+                    type: array
+                    items:
+                        type: string
+                    description: Named entities to block (e.g., competitor names)
+                block_harmful_content:
+                    type: boolean
+                    default: false
+                    description: Block responses containing harmful content categories
+                harmful_categories:
+                    type: array
+                    items:
+                        type: string
+                        enum: [violence, self_harm, illegal, hate, sexual, malware]
+                    description: Harm categories to block
+                action:
+                    type: string
+                    enum: [block, sanitize, warn, log]
+                    default: warn
+                    description: Action when output policy is violated
+
+        SecretInjectionConfig:
+            type: object
+            description: Detects credentials injected into prompts that are not from the vault
+            properties:
+                enabled:
+                    type: boolean
+                    default: false
+                    description: Enable secret injection detection
+                action:
+                    type: string
+                    enum: [block, sanitize, warn, log]
+                    default: block
+                    description: Action when injected credentials are detected
+                sensitivity:
+                    type: string
+                    enum: [low, medium, high]
+                    default: medium
+                    description: Detection sensitivity level
+
+        AdvancedRedactionConfig:
+            type: object
+            description: Advanced secret redaction settings (base64-encoded, split, prefix leaks)
+            properties:
+                enabled:
+                    type: boolean
+                    default: false
+                    description: Enable advanced redaction checks
+                detect_base64_encoded:
+                    type: boolean
+                    default: false
+                    description: Detect base64-encoded vault secrets
+                detect_split_secrets:
+                    type: boolean
+                    default: false
+                    description: Detect secrets split across tokens or messages
+                detect_prefix_leak:
+                    type: boolean
+                    default: false
+                    description: Detect partial/prefix leaks of vault secrets
+                min_secret_length:
+                    type: integer
+                    default: 16
+                    description: Minimum secret length to consider for advanced matching
+
+        SemanticPolicy:
+            type: object
+            description: Semantic/intent-level policy enforcement
+            properties:
+                enabled:
+                    type: boolean
+                    default: false
+                    description: Enable semantic policy enforcement
+                allowed_topics:
+                    type: array
+                    items:
+                        type: string
+                    description: Topics the agent is allowed to discuss (empty = all)
+                denied_topics:
+                    type: array
+                    items:
+                        type: string
+                    description: Topics to block
+                allowed_tasks:
+                    type: array
+                    items:
+                        type: string
+                    description: Tasks the agent is allowed to perform (empty = all)
+                denied_tasks:
+                    type: array
+                    items:
+                        type: string
+                    description: Tasks to block (e.g., code_generation, data_export)
+                action:
+                    type: string
+                    enum: [block, sanitize, warn, log]
+                    default: warn
+                    description: Action when semantic policy is violated
+
         AgentCreatedResponse:
             type: object
             required: [agent]
@@ -4487,14 +4728,74 @@ components:
                 limit:
                     type: integer
 
+        LlmMeteredInvoiceLine:
+            type: object
+            description: Metered line from Stripe upcoming invoice (usage detail when available).
+            properties:
+                description:
+                    type: string
+                    nullable: true
+                amount_cents:
+                    type: integer
+                    format: int64
+                quantity:
+                    type: number
+                    nullable: true
+                    description: Billed usage units when Stripe returns quantity (e.g. tokens).
+                price_nickname:
+                    type: string
+                    nullable: true
+
+        LlmBillingCycleUsage:
+            type: object
+            description: Accrued LLM charges for the current Stripe subscription period (upcoming invoice).
+            properties:
+                period_start:
+                    type: string
+                    format: date-time
+                    nullable: true
+                period_end:
+                    type: string
+                    format: date-time
+                    nullable: true
+                accrued_usage_cents:
+                    type: integer
+                    format: int64
+                currency:
+                    type: string
+                metered_lines:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/LlmMeteredInvoiceLine"
+
+        LlmCreditBalance:
+            type: object
+            properties:
+                available_cents:
+                    type: integer
+                    format: int64
+                ledger_cents:
+                    type: integer
+                    format: int64
+                used_cents:
+                    type: integer
+                    format: int64
+                currency:
+                    type: string
+
         LlmTokenBillingStatus:
             type: object
+            required: [enabled]
             properties:
                 enabled:
                     type: boolean
                 subscription_status:
                     type: string
                     enum: [active, inactive]
+                credit_balance:
+                    $ref: "#/components/schemas/LlmCreditBalance"
+                billing_cycle_usage:
+                    $ref: "#/components/schemas/LlmBillingCycleUsage"
 
         LlmCheckoutResponse:
             type: object
@@ -4919,6 +5220,84 @@ components:
                 description:
                     type: string
 
+        # --- Shroud Activity ---
+
+        ShroudActivityEvent:
+            type: object
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                org_id:
+                    type: string
+                    format: uuid
+                agent_id:
+                    type: string
+                provider:
+                    type: string
+                model:
+                    type: string
+                action:
+                    type: string
+                    description: Action taken (allowed, blocked, warned)
+                request_tokens:
+                    type: integer
+                response_tokens:
+                    type: integer
+                latency_ms:
+                    type: integer
+                had_secrets_redacted:
+                    type: boolean
+                had_pii_detected:
+                    type: boolean
+                injection_score:
+                    type: number
+                policy_violations:
+                    type: array
+                    items:
+                        type: string
+                metadata:
+                    type: object
+                timestamp:
+                    type: string
+                    format: date-time
+
+        IngestShroudActivityRequest:
+            type: object
+            required: [agent_id, action]
+            properties:
+                agent_id:
+                    type: string
+                provider:
+                    type: string
+                model:
+                    type: string
+                action:
+                    type: string
+                request_tokens:
+                    type: integer
+                    default: 0
+                response_tokens:
+                    type: integer
+                    default: 0
+                latency_ms:
+                    type: integer
+                had_secrets_redacted:
+                    type: boolean
+                    default: false
+                had_pii_detected:
+                    type: boolean
+                    default: false
+                injection_score:
+                    type: number
+                    default: 0
+                policy_violations:
+                    type: array
+                    items:
+                        type: string
+                metadata:
+                    type: object
+
         # --- Health ---
 
         HealthResponse:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@1claw/openapi-spec",
-    "version": "0.16.1",
+    "version": "0.17.0",
     "description": "OpenAPI 3.1.0 specification for the 1Claw Vault API — generate clients in any language",
     "license": "MIT",
     "repository": {