{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/aimeat-io/json-schema/aimeat-io-agent-task-schema.json",
  "title": "AgentTask",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/aimeat-io-agent-integration-api-openapi.yml#/components/schemas/AgentTask",
  "type": "object",
  "required": [
    "id",
    "agentName",
    "ownerGaii",
    "title",
    "status",
    "createdAt",
    "updatedAt"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "agentName": {
      "type": "string"
    },
    "ownerGaii": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "status": {
      "$ref": "#/$defs/TaskStatus"
    },
    "todos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          },
          "done": {
            "type": "boolean"
          }
        }
      }
    },
    "events": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/TaskEvent"
      }
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    },
    "resources": {
      "$ref": "#/$defs/AgentTaskResources"
    },
    "deliverableKey": {
      "type": "string",
      "description": "Memory key (agent namespace) where the task's deliverable was published, if any."
    },
    "rating": {
      "$ref": "#/$defs/AgentTaskRating"
    },
    "triage": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "kept",
        "archived"
      ],
      "description": "Tasks-tab triage bucket override (null = default Recent/auto-archive)."
    },
    "dedupeKey": {
      "type": "string",
      "description": "Commission fingerprint (caller `idempotency_key` or a hash of agent + title + description). A partial unique index over the open statuses makes a second identical commission impossible while this one is still running.\n"
    },
    "startPolicy": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "automatic",
        "confirm",
        null
      ],
      "description": "How THIS task starts, when its creator said so (`start` on create): `automatic` (the agent proposes its plan and goes on) or `confirm` (it waits for the owner's OK). Null when they did not; the agent's `task_start` then decides, read when the plan arrives. The permission floor is not part of it; see TaskStartAnswer.\n"
    }
  },
  "$defs": {
    "AgentTaskFileRef": {
      "type": "object",
      "description": "One file handed to the agent WITH the task. Only a REFERENCE is stored, never the bytes. On create, `ref` (and optionally `name`) is supplied; the server verifies the file exists and that the CREATOR can read it, then fills `mime` and `size` from the stored file. On read, the entry is authorized again as the READING principal and carries `access` plus a presigned `download_url` when granted — so a revoked grant stops handing out URLs on the next read.\n",
      "required": [
        "ref"
      ],
      "properties": {
        "ref": {
          "type": "string",
          "description": "\"<ownerGaii>/<storage key>\" (a bare key means the caller's own storage)."
        },
        "name": {
          "type": "string"
        },
        "mime": {
          "type": "string",
          "readOnly": true
        },
        "size": {
          "type": "integer",
          "readOnly": true
        },
        "access": {
          "type": "string",
          "enum": [
            "granted",
            "denied",
            "missing"
          ],
          "readOnly": true
        },
        "reason": {
          "type": "string",
          "readOnly": true,
          "description": "Why a non-granted read was refused (e.g. consent_denied, not_found)."
        },
        "download_url": {
          "type": "string",
          "readOnly": true,
          "description": "Presigned, TTL-limited GET. Present only when access is granted."
        },
        "expires_in_seconds": {
          "type": "integer",
          "readOnly": true
        }
      }
    },
    "AgentTaskRating": {
      "type": "object",
      "description": "Peer/owner review of a completed task's deliverable (Quality tab). Feeds the per-context quality rollup from GET /v1/agents/{name}/statistics.\n",
      "required": [
        "stars",
        "context",
        "ratedBy",
        "raterType",
        "sourceGrounded",
        "ratedAt"
      ],
      "properties": {
        "stars": {
          "type": "integer",
          "minimum": 1,
          "maximum": 5
        },
        "context": {
          "type": "string",
          "enum": [
            "factual",
            "creative",
            "code",
            "planning",
            "summarization",
            "research",
            "communication",
            "other"
          ]
        },
        "comment": {
          "type": "string"
        },
        "ratedBy": {
          "type": "string",
          "description": "GHII (owner) or GAII (agent) of the rater."
        },
        "raterType": {
          "type": "string",
          "enum": [
            "human-owner",
            "agent",
            "source-grounded-agent"
          ]
        },
        "sourceGrounded": {
          "type": "boolean",
          "description": "Whether the rating was checked against the deliverable's inputs/sources."
        },
        "unsupported": {
          "type": "integer",
          "minimum": 0,
          "description": "Optional count of unsupported/fabricated claims."
        },
        "evaluatedModel": {
          "type": "string",
          "description": "Model that produced the deliverable (baseline stamp)."
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true,
          "description": "Free-form evaluation context (temperature, tokens, cost, ...) stored for later slicing."
        },
        "ratedAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "AgentTaskResources": {
      "type": "object",
      "description": "What the agent needs in order to do the task — knowledge, memory, and files.",
      "properties": {
        "knowledge_packages": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "memory_keys": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "memory_prefixes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "files": {
          "type": "array",
          "maxItems": 20,
          "items": {
            "$ref": "#/$defs/AgentTaskFileRef"
          }
        }
      }
    },
    "TaskEvent": {
      "type": "object",
      "required": [
        "type",
        "timestamp"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "created",
            "started",
            "progress",
            "log",
            "completed",
            "failed",
            "declined",
            "stalled"
          ]
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "object"
        },
        "timestamp": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "TaskStatus": {
      "type": "string",
      "description": "Lifecycle status of an agent task.\n- draft: created but not yet visible to the agent.\n- queued: visible to the agent; agent proposes a todo plan; awaits owner /start (or task-runner mode auto-activation).\n- revision_requested: the owner reviewed the proposed todos and used /request-changes to ask for a revised plan; agent will re-propose.\n- active: the agent is executing the plan.\n- paused, stalled: temporary holds.\n- done, failed, declined: terminal states. declined = the agent refused the request with its\n  reason (POST …/decline); it is an answer, not an error, and counts as no failure.\n",
      "enum": [
        "draft",
        "queued",
        "revision_requested",
        "active",
        "paused",
        "done",
        "failed",
        "declined",
        "stalled"
      ]
    }
  }
}