Files
archie/docs/data/generated/contracts.json
T
sam 662a5ee336 feat(telegram): carry inbound media through the chat turn
Telegram dropped every incoming photo, document, video and audio
message: the default handler required message text, and nothing on the
turn path knew media existed. The receiving path now closes the gap
end to end.

- telegram: extract the attachment from the update (largest photo, plus
  document, video, video-note, audio and voice kinds), download its
  bytes on the turn lane through getFile + the Bot API file link with a
  20 MB gate, submit the turn with the attachment, and answer
  unsupported content kinds (sticker, location, contact, poll) with a
  clear notice instead of silence
- messaging: Inbound carries turn-scoped transport media and
  MediaAttachment a Data field for in-process bytes; Message gains
  Media attachment metadata which stores persist (Postgres jsonb via
 migration 0020, memory store) with Data stripped at the persist
  boundary, and pb.Message carries the metadata on the gateway wire
- gateway: TurnModelRequest threads the turn's media to the model seam
- archied: the chat turn model merges the attachments into the final
  user message as ai-sdk image/file part entries, so vision-capable
  models see the file for the turn it arrived in; stored history keeps
  the placeholder note plus caption

Session log: messages carry what was sent as data (the attachment
metadata), not just prose. Transcript rendering of attachments and a
re-look capability are tracked as archie-core-jaba.
2026-09-30 03:07:54 +10:00

495 lines
14 KiB
JSON

{
"generatedBy": "tools/docsgen",
"schemas": {
"AgentExecutionRequest": {
"additionalProperties": false,
"description": "Request is the complete, serializable input for one agent stage.",
"properties": {
"attempt": {
"type": "integer"
},
"budget": {
"$ref": "#/schemas/Budget"
},
"capture_tools": {
"items": {
"$ref": "#/schemas/CaptureTool"
},
"type": "array"
},
"context_window": {
"type": "integer"
},
"extra_rules": {
"type": "string"
},
"gate": {
"$ref": "#/schemas/Gate"
},
"harness": {
"$ref": "#/schemas/HarnessSpec",
"description": "Harness, when set, runs the stage on an external coding-agent CLI\ninstead of the built-in loop. The worker in a Kit container is the\ndaemon's own archie-agent build, so it always understands this field."
},
"mission": {
"type": "string"
},
"model": {
"type": "string"
},
"notes": {
"type": "string"
},
"plugins": {
"description": "Plugins are bundled Yaegi plugins from the skill's plugins/\ndirectory. Each entry carries the name and source so the agent\ncan register them as tools. PRD section 5 Layer 1.",
"items": {
"$ref": "#/schemas/PluginSpec"
},
"type": "array"
},
"preflight": {
"items": {
"$ref": "#/schemas/Command"
},
"type": "array"
},
"protection": {
"$ref": "#/schemas/Protection"
},
"read_only": {
"type": "boolean"
},
"stage": {
"type": "string"
},
"task_id": {
"type": "integer"
},
"version": {
"type": "integer"
},
"workflow": {
"type": "string"
}
},
"required": [
"version",
"task_id",
"attempt",
"stage",
"model",
"mission",
"budget",
"gate",
"protection"
],
"type": "object"
},
"AgentExecutionResult": {
"additionalProperties": false,
"description": "Result is the serializable outcome of one agent stage.",
"properties": {
"appended_notes": {
"items": {
"type": "string"
},
"type": "array"
},
"attempt": {
"type": "integer"
},
"captures": {
"additionalProperties": {
"items": true,
"type": "array"
},
"type": "object"
},
"changes": {
"items": {
"type": "string"
},
"type": "array"
},
"detail": {
"type": "string"
},
"iterations": {
"type": "integer"
},
"stage": {
"type": "string"
},
"status": {
"type": "string"
},
"stop_reason": {
"type": "string"
},
"summary": {
"type": "string"
},
"task_id": {
"type": "integer"
},
"tokens_used": {
"type": "integer"
},
"usage": {
"$ref": "#/schemas/Usage"
},
"version": {
"type": "integer"
}
},
"required": [
"version",
"task_id",
"attempt",
"stage",
"status",
"usage"
],
"type": "object"
},
"Budget": {
"additionalProperties": false,
"description": "Budget bounds one autonomous execution.",
"properties": {
"max_steps": {
"type": "integer"
},
"wall_clock": {
"type": "integer"
}
},
"type": "object"
},
"CaptureTool": {
"additionalProperties": false,
"description": "CaptureTool declares a structured-output tool whose calls are returned to the daemon as data.",
"properties": {
"boolean_fields": {
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"type": "string"
},
"max_calls": {
"type": "integer"
},
"name": {
"type": "string"
},
"non_empty_strings": {
"items": {
"type": "string"
},
"type": "array"
},
"parameters": true,
"required_fields": {
"items": {
"type": "string"
},
"type": "array"
},
"required_when_true": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "RequiredWhenTrue makes fields required only when a boolean field in\nthe same call is true, keyed by that boolean's name. It exists because\na flat RequiredFields entry cannot express \"name a workflow, but only\nwhen you have said one is needed\": the alternatives were forcing a\nmeaningless answer on the other branch, or accepting the omission and\ndefaulting it, which lets the model skip the decision entirely.\nA named field must also be a non-empty string when the trigger is true.",
"type": "object"
}
},
"required": [
"name"
],
"type": "object"
},
"Command": {
"additionalProperties": false,
"description": "Command is one executable gate or preflight command.",
"properties": {
"argv": {
"items": {
"type": "string"
},
"type": "array"
},
"expect_failure": {
"type": "boolean"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"argv"
],
"type": "object"
},
"Gate": {
"additionalProperties": false,
"description": "Gate is the quality gate an agent must satisfy.",
"properties": {
"commands": {
"items": {
"$ref": "#/schemas/Command"
},
"type": "array"
},
"max_consecutive_failures": {
"type": "integer"
}
},
"type": "object"
},
"HarnessSpec": {
"additionalProperties": false,
"description": "HarnessSpec is how to drive a Kit's agent headlessly: its launch argv (image entrypoint and cmd) and the agent-sessions@1 verb tails appended to it.",
"properties": {
"adapter": {
"description": "Adapter names the output adapter reading the CLI's stream; empty is\na CLI with none.",
"type": "string"
},
"continue": {
"items": {
"type": "string"
},
"type": "array"
},
"env": {
"description": "Env is the invocation's entire environment. Nothing is inherited from\nthe worker, whose environment carries its credentials.",
"items": {
"type": "string"
},
"type": "array"
},
"launch": {
"items": {
"type": "string"
},
"type": "array"
},
"mcp_config": {
"description": "MCPConfig registers archie's MCP server with the CLI: an argv tail\ncarrying {{.MCPConfig}}, the path of a standard mcpServers config.\nA stage with capture tools needs it.",
"items": {
"type": "string"
},
"type": "array"
},
"prompt": {
"items": {
"type": "string"
},
"type": "array"
},
"resume": {
"items": {
"type": "string"
},
"type": "array"
},
"user": {
"description": "User is the Kit's user, a name or \"uid[:gid]\", that every invocation\nruns as. It is never root: the worker's credentials live in the same\ncontainer, readable only by the worker's user.",
"type": "string"
}
},
"required": [
"launch",
"prompt"
],
"type": "object"
},
"MediaAttachment": {
"additionalProperties": false,
"description": "MediaAttachment describes a file attached to a message.",
"properties": {
"data": {
"contentEncoding": "base64",
"description": "Data carries the attachment bytes in-process. An inbound path sets\nit after downloading the file; outbound senders never set it and\nread Path or URL instead. It never crosses a wire or persistence\nboundary -- it is a turn-scoped value, not a stored one.",
"type": "string"
},
"duration": {
"description": "Duration is the play time in seconds for audio and video.",
"type": "integer"
},
"file_id": {
"description": "FileID is the platform-assigned identifier for download APIs.",
"type": "string"
},
"file_name": {
"description": "FileName is the original file name when known.",
"type": "string"
},
"file_size": {
"description": "FileSize is the attachment size in bytes. nil means unknown.",
"type": "integer"
},
"height": {
"description": "Height is the pixel height for images and video. nil means unknown\nor not applicable.",
"type": "integer"
},
"mime_type": {
"description": "MIMEType is the content type (e.g. \"image/png\", \"audio/ogg\").",
"type": "string"
},
"path": {
"description": "Path is a local filesystem path on the host that produced the\nattachment. It is the alternative to URL for outbound delivery: a\nURL is fetched by the platform, a Path is uploaded by us. A file the\nagent wrote has no URL and never gets one -- publishing it would\ntrade a delivery problem for a hosting and access-control one -- so\nsenders that support upload must read this.\n\nExactly one of URL and Path is meaningful for an outbound send.",
"type": "string"
},
"raw": {
"description": "Raw carries platform-specific fields the common vocabulary does not\ncover, so adapters never need a second attachment type.",
"type": "object"
},
"type": {
"description": "Type is \"image\", \"video\", \"audio\", or \"document\".",
"type": "string"
},
"url": {
"description": "URL is a direct download URL when available. May be empty for\nplatforms that require a download API call.",
"type": "string"
},
"width": {
"description": "Width is the pixel width for images and video. nil means unknown\nor not applicable.",
"type": "integer"
}
},
"required": [
"type",
"file_id"
],
"type": "object"
},
"MessageEvent": {
"additionalProperties": false,
"description": "MessageEvent is the rich message model for gateway channels.",
"properties": {
"callback_data": {
"type": "string"
},
"channel_id": {
"type": "string"
},
"edited_from": {
"type": "string"
},
"id": {
"type": "string"
},
"media": {
"items": {
"$ref": "#/schemas/MediaAttachment"
},
"type": "array"
},
"platform": {
"type": "string"
},
"raw": {
"type": "object"
},
"reacted_to_id": {
"type": "string"
},
"reaction": {
"type": "string"
},
"reply_to_id": {
"type": "string"
},
"sender_id": {
"type": "string"
},
"sender_name": {
"type": "string"
},
"text": {
"type": "string"
},
"thread_id": {
"type": "string"
},
"timestamp": {
"type": "integer"
},
"type": {
"type": "string"
}
},
"required": [
"type",
"channel_id",
"platform",
"sender_id"
],
"type": "object"
},
"PluginSpec": {
"additionalProperties": false,
"description": "PluginSpec is a bundled Yaegi plugin passed from daemon to agent.",
"properties": {
"name": {
"type": "string"
},
"src": {
"type": "string"
}
},
"required": [
"name",
"src"
],
"type": "object"
},
"Protection": {
"additionalProperties": false,
"description": "Protection describes paths the agent may read but not mutate.",
"properties": {
"globs": {
"items": {
"type": "string"
},
"type": "array"
},
"suffixes": {
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"Usage": {
"additionalProperties": false,
"description": "Usage preserves provider-reported token economics for evaluation.",
"properties": {
"cache_creation_tokens": {
"type": "integer"
},
"cached_tokens": {
"type": "integer"
},
"completion_tokens": {
"type": "integer"
},
"prompt_tokens": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
}
},
"type": "object"
}
}
}