{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/domani-run/json-schema/domani-run-assistant-work-item-schema.json",
  "title": "AssistantWorkItem",
  "description": "One grounded item of the Today queue. Every field is a proposal derived from mail; the source message stays the only truth.",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/domani-run-openapi.json#/components/schemas/AssistantWorkItem",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "version": {
      "type": "integer"
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "needs_judgment",
        "snoozed",
        "waiting",
        "handled",
        "ignored"
      ]
    },
    "title": {
      "type": "string"
    },
    "summary": {
      "type": "string"
    },
    "ask": {
      "type": [
        "string",
        "null"
      ],
      "description": "The single thing the owner must do or decide, or null."
    },
    "category": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "invoice",
        "payment_notice",
        "payment_failure",
        "refund_request",
        "signature_request",
        "meeting_request",
        "calendar_change",
        "support_ticket",
        "partner_inquiry",
        "recurring_alert",
        "account_notice",
        "newsletter",
        "legal_notice",
        "internal_handover",
        "shipping_notice",
        "phishing",
        "other"
      ],
      "description": "The kind of matter the analysis found (an invoice, a meeting request, a newsletter...), or null when no analysis said. Rules match it as the label category:<kind>."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The person's tags on the matter (CT-01b): confirmed once or set by hand, each one a label on the thread at the provider. Rules match them as the label tag:<name>."
    },
    "proposed_tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The tags the engine proposes for the matter (one per project it named), not yet confirmed. Confirm one with the tag interaction; it then applies to the next matter of the same project without a question."
    },
    "suspect": {
      "type": "boolean",
      "description": "The trust signals found the sender suspect: the matter sits in the Suspect section, is never Now, carries no decision, and no effect runs on it until the person reports it legitimate."
    },
    "suspect_reasons": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Why it looks suspect, one sentence per signal (a failed authentication, a diverging Reply-To, a lookalike domain, a borrowed name, a first contact about money, an instruction to the assistant, a secret asked by return mail)."
    },
    "sender": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "address": {
          "type": "string"
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "kind": {
          "type": "string",
          "enum": [
            "human",
            "automated",
            "self",
            "harness"
          ]
        }
      }
    },
    "recurrence": {
      "type": "object",
      "description": "How often this same situation came back: one item, N messages.",
      "properties": {
        "count": {
          "type": "integer"
        },
        "first_seen_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "last_seen_at": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "mailbox": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "address": {
          "type": "string"
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "operator": {
          "type": "string",
          "enum": [
            "human",
            "agent"
          ]
        },
        "agent": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "name": {
              "type": "string"
            },
            "emoji": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        }
      }
    },
    "opened_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "delegated_to": {
      "type": [
        "string",
        "null"
      ],
      "description": "The slug of the agent the owner handed this item to, or null."
    },
    "delegation_rule": {
      "type": [
        "object",
        "null"
      ],
      "description": "The standing delegation that handed this item over, and why it matched; suspended once the owner took the item back.",
      "properties": {
        "id": {
          "type": "string"
        },
        "why": {
          "type": [
            "string",
            "null"
          ]
        },
        "suspended": {
          "type": "boolean"
        }
      }
    },
    "unread": {
      "type": "boolean",
      "description": "True until the owner opens the item after its latest change."
    },
    "messages": {
      "type": "array",
      "description": "The source messages behind this item, newest first.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "subject": {
            "type": [
              "string",
              "null"
            ]
          },
          "from": {
            "type": "string"
          },
          "received_at": {
            "type": "string"
          },
          "conversation_id": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    },
    "history": {
      "type": "array",
      "description": "What already happened in this matter, oldest first: one line per earlier message.",
      "items": {
        "type": "object",
        "properties": {
          "message_id": {
            "type": "string"
          },
          "occurred_at": {
            "type": "string"
          },
          "sender": {
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        }
      }
    },
    "source": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "conversation_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "event_id": {
          "type": "string"
        },
        "revision": {
          "type": "integer"
        }
      }
    },
    "attention": {
      "type": "object",
      "properties": {
        "level": {
          "type": "string",
          "enum": [
            "now",
            "needs_you",
            "fyi",
            "quiet"
          ]
        },
        "reason": {
          "type": "string"
        },
        "confidence": {
          "type": "string"
        },
        "deadline": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "analysis": {
      "type": "object",
      "properties": {
        "coverage": {
          "type": "string"
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "evidence_refs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "entity_refs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "snoozed_until": {
      "type": [
        "string",
        "null"
      ]
    },
    "decision": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "version": {
          "type": "integer"
        },
        "status": {
          "type": "string"
        },
        "question": {
          "type": "string"
        },
        "options": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "recommended": {
                "type": "boolean"
              },
              "outcome": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "plan": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "expires_at": {
          "type": "string"
        }
      }
    }
  }
}