@talqing/mcp 0.10.0 → 0.12.0

package/SKILL.md

@@ -37,8 +37,10 @@ An agent is a single object, `config`, plus what you attach to it:
 - **`prompt`** — the system prompt. This is where the agent's behaviour lives.
 - **`greeting`** — the line spoken on connect, and on the way in from a
   handoff. Voice and video only. `greeting_interruptible: false` makes the
-  caller unable to cut it off (cascade only); a greeting speaking the recording
-  notice is always protected.
+  caller unable to cut it off (cascade only). To tell callers they are recorded,
+  set `recording.notice` to the sentence and put `{{recording.notice}}` in the
+  greeting where it should be spoken; it plays uninterruptibly, needs recording
+  on and a cascade pipeline, and `null` means no notice.
 
   Both are personalized per session: `{{userdata.field}}` is substituted from
   the session's userdata when the agent starts, so *"You are speaking with
@@ -55,22 +57,28 @@ An agent is a single object, `config`, plus what you attach to it:
   Two more roots are filled in from outside the session, and nothing inside one
   can write either. They differ in who fills them.
 
-  **`{{system_vars.…}}` — ours.** Six keys, and any other is rejected at save;
-  `GET /v1/catalog` returns them as `system_vars`.
-
-  - `{{system_vars.human_phone_number}}` — the other party, the caller inbound
-    and the person you called outbound
-  - `{{system_vars.agent_phone_number}}` — your number on this call
-  - `{{system_vars.direction}}` — `inbound` or `outbound`
+  **`{{system_vars.…}}` — ours.** Seven keys, and any other is rejected at save;
+  `GET /v1/catalog` returns them as `system_vars`, each with the `channels` it
+  has a value on.
+
+  - `{{system_vars.human_phone_number}}` — the person's number: who called or
+    wrote to you, or whom you called or wrote to
+  - `{{system_vars.agent_phone_number}}` — your number in this session
+  - `{{system_vars.direction}}` — `inbound` when they started the call or chat,
+    `outbound` when you did
+  - `{{system_vars.channel}}` — where the session is happening: `phone_call`,
+    `whatsapp_call`, `whatsapp_message`, `web_call`, `chat`, `telegram` or `stream`
   - `{{system_vars.now}}` — `2026-08-19T19:26:59+05:30`, the machine format;
     send it to an API, never read it aloud
   - `{{system_vars.date}}` — `Wednesday, 19 August 2026`
   - `{{system_vars.time}}` — `7:26 PM`
 
-  The first three come from the call, so they are empty on web calls and on text
-  conversations — do not make one the only source of a fact the agent needs. One
+  The first three come from a phone number — phone calls, WhatsApp calls,
+  WhatsApp chats and media streams — so they are empty on web calls, API chats
+  and Telegram; do not make one the only source of a fact the agent needs. One
   agent can greet a caller and someone it called differently by branching on
-  `{{system_vars.direction}}`. The last three come from the agent's
+  `{{system_vars.direction}}`, and one agent on several channels can adapt by
+  branching on `{{system_vars.channel}}`. The last three come from the agent's
   **`timezone`** and work on every channel; using one without setting `timezone`
   is a save error. In a prompt or greeting the clock is frozen at the moment the
   agent started (re-resolving would throw away the model's prompt cache); inside
@@ -107,8 +115,9 @@ An agent is a single object, `config`, plus what you attach to it:
   Four things to get right:
 
   - **They are visible to the model.** Anything in `vars` may be read aloud or
-    repeated back. A credential belongs in a workspace secret, read as
-    `{{secrets.NAME}}` from a tool, where the model never sees it.
+    repeated back. A credential belongs in `secrets` on the same request when it
+    is per session, or in a workspace secret when it is shared — either is read
+    as `{{secrets.NAME}}` from a tool, where the model never sees it.
   - **`required: true` refuses the session** that supplies no value for a
     variable with no `default` — the call token, the dial, the batch and the chat,
     before anything is compiled and before any provider is called.
@@ -649,17 +658,21 @@ states what to add; do not try to turn the derived silence off.
 this tool run's own state, `{{userdata.field}}` the session's state,
 `{{system_vars.field}}` what the platform knows about this session,
 `{{vars.field}}` what the tenant supplied for it, and `{{secrets.NAME}}` a
-workspace secret. A string that is exactly one template token keeps the resolved
-value's type. Every one of these works in a URL, in the query, in the body **and
-in headers**. A token whose root is not one of those six is an error at save,
-not text.
-
-`system_vars` is read-only, and its six keys are the same ones the agent's prompt
-reads: `human_phone_number`, `agent_phone_number`, `direction`, `now`, `date`,
-`time`. So a tool can POST the caller's number to a CRM, stamp a record with
-`{{system_vars.now}}`, or branch an `if` on the direction without the agent
-having to ask. The phone-call keys are empty on web calls, on text conversations
-and in a dashboard test run; the clock keys resolve wherever the agent has a
+secret — the session's own if it brought one of that name, else the workspace's.
+A string that is exactly one template token keeps the resolved value's type.
+Every one of these works in a URL, in the query, in the body **and in headers**.
+A token whose root is not one of those six is an error at save, not text.
+**A secret may only be sent by an `http` operation or read by a `code`
+operation**: `{{secrets.…}}` in any other operation (`say`, `set_variable`,
+`if`, `frontend_rpc`, `generate_reply`, a handoff…) is refused at save, because
+it would be spoken, shown or stored.
+
+`system_vars` is read-only, and its seven keys are the same ones the agent's prompt
+reads: `human_phone_number`, `agent_phone_number`, `direction`, `channel`, `now`,
+`date`, `time`. So a tool can POST the person's number to a CRM, stamp a record
+with `{{system_vars.now}}`, or branch an `if` on the direction or the channel
+without the agent having to ask. The phone keys are empty on web calls, API chats,
+Telegram and in a dashboard test run; the clock keys resolve wherever the agent has a
 `timezone`, and read the time the **tool ran** rather than the time the call
 started.
 
@@ -897,15 +910,15 @@ same lifecycle hooks as an agent — minus everything that belongs to a
 *session*, because a task never owns one.
 
 **It runs two ways, and declares nothing that ties it to either.** On its own —
-`POST /v1/tasks/{task_id}/runs`, or an email batch drafting a row — it is an LLM
-with tools and nobody to talk to. Attached to an agent through
+`run_task` (`POST /v1/task-runs`), or an email batch drafting a row — it is an
+LLM with tools and nobody to talk to. Attached to an agent through
 `AgentConfig.tasks`, it takes over that conversation for as long as the job
-takes, on the call's own voice and ears, and hands its result back as a tool
-result.
+takes, on the call's own voice and ears, and hands its result back to the
+calling agent as a JSON tool result.
 
 It is its own noun with its own operations (`list_tasks`, `create_task`,
-`get_task`, `update_task`, `delete_task`, `run_task`, `list_task_runs`) — not a
-fourth agent channel. Use one wherever the work has an input and an answer
+`get_task`, `update_task`, `delete_task`, `run_task`, `list_task_runs`, …) — not
+a fourth agent channel. Use one wherever the work has an input and an answer
 rather than a conversation: research a company from a domain, classify a
 message, draft an opening line, take a shipping address mid-call.
 
@@ -916,7 +929,7 @@ message, draft an opening line, take a shipping address mid-call.
   reads `{{vars.name}}` for the values the run was given, and
   `{{system_vars.now}}` / `.date` / `.time` when `timezone` is set. It does
   **not** read `{{system_vars.human_phone_number}}` / `.agent_phone_number` /
-  `.direction` — there is no call.
+  `.direction` / `.channel` — there is no session.
 - **`llm`** — one model, with the same `fallback`, `reasoning_effort`,
   `priority` and `builtin_tools` an agent's LLM has. A provider tool runs inside
   a step rather than as one, so it costs no steps and real seconds. It is the
@@ -943,17 +956,31 @@ message, draft an opening line, take a shipping address mid-call.
   refused too, rather than silently dropped — which is the one difference from an
   agent, whose key space is open.
 
+  Two input kinds exist for tasks only. **`type: "file"`** takes a PDF (text or
+  scanned, up to 20 MB and 100 pages), supplied under the run's `files`; it has
+  no `default`. **`untrusted: true`** marks third-party text — a CV, an email, a
+  transcript. Both are **never templated**: `{{vars.cv}}` in the prompt, or an
+  untrusted value in a tool's URL, query or headers, is refused at save (a tool's
+  request body may carry untrusted text; nothing may carry a file). The run hands
+  them to the model as JSON in its opening message, under a line saying they are
+  data, not instructions — so the prompt should name them and say how to treat
+  them. Scanned pages reach the model as images, so they need a model with
+  vision. A task with either kind cannot be attached to an agent.
+
   **They are also the schema of the tool an agent enters the task with**, minus
   every name that agent declares and every name the session was started with. So
   declare a variable only for what the caller or the model must supply: anything
   the task can read for itself — `{{userdata.order_id}}`, `{{vars.region}}`,
   `{{system_vars.date}}` — belongs in the prompt. Declare it instead and the
   model is asked to invent it, and it will.
-- **`output`** — a flat list of the fields the model must produce, each with a
-  `name`, a `type` (`string`, `boolean`, `integer` or `number`) and a
-  `description`. At most 25, and at least one **to publish** — a draft may have
-  none. No arrays and no nested objects: a task that wants to return five
-  talking points returns one string containing them.
+- **`output`** — the fields the model must produce, each with a `name`, a
+  `type` and a `description`. Types are `string`, `boolean`, `integer`,
+  `number`, `object` (takes `fields`, a list of the same shape) and `array`
+  (takes `items`: `{type, description, enum?, fields?, items?}` — an element has
+  no name and is never null). A `string` may take `enum`, 1–50 allowed values.
+  At most 25 top-level fields, 4 levels deep and 100 fields in all, and at least
+  one **to publish**. A grader returns `criteria: [{name, verdict, quote}]`
+  rather than one string to be parsed.
 - **`max_steps`** (default 25, max 50) — how many LLM → tools → LLM **rounds**
   a STANDALONE run may take. A round, not a tool call: four tools in one reply
   cost one step. This is the runaway-loop guard. Entered by an agent the task
@@ -985,7 +1012,7 @@ trees, and the email batches already drafting with this task. Run it before
 are worth reporting but never block.
 
 **Build order:** create the draft → write the prompt, `vars` and `output` →
-`run_task` with `version: "draft"` to try it → fix → `validate_task` →
+`run_task` with `task_id` and `task_version: "draft"` to try it → fix → `validate_task` →
 `publish_task` **when the person asks you to**. Publishing is their call, not
 yours: it changes what every run and every live email batch does.
 
@@ -1002,7 +1029,7 @@ job is done enough to call it. It is required and
 non-empty; a new task starts with `"Submit results if you are sure that you have achieved the goal of this task"`. **Make it specific**: what
 "achieved" means for this task (e.g. "once the caller has confirmed the address").
 
-Every output field is a **required argument** of that tool — an optional one lets
+Every output field is a **required argument** of that tool, at every depth — an optional one lets
 the model silently omit the address it failed to find, and "omitted" and "not
 generated yet" then look identical to whoever reads the row. A field's own
 `required` flag (default `true`) decides whether `null` is accepted: turn it off
@@ -1020,21 +1047,51 @@ IS how a task reports failure, so never add a success/failure boolean to `output
 a value it may legitimately not find is a field with `required` off. Publishing
 refuses either description blank.
 
-### Reading a run
+### Running one
 
 `run_task` **executes for real**: the tools call the tenant's endpoints with
 their secrets, the MCP servers spend their credits, and the model spends their
 tokens. A task that books, charges or sends will do so.
 
-It runs the published version unless `version` says otherwise. Pass
-`version: "draft"` to try the unpublished config — that is the loop you build
-in, and it is refused with the publish errors when the draft does not hold
-together.
+**What runs** is named like an agent on a call: `task_id` (the published
+version, an int `task_version`, or `task_version: "draft"` — the loop you build
+in, refused with the publish errors when the draft does not hold together), or
+a whole inline `task`. `task_override` changes anything for this run only
+(objects merge, lists replace, null clears) — a different model, say. The run
+stores the exact resolved config as `config`.
+
+**Inline or background.** By default the call waits and answers with the
+finished run. `background: true` queues it and answers `202` at once; the
+workspace runs up to 3 background runs at a time, oldest first, and queues the
+rest — it never refuses for load. `run_task_batch` queues up to 1000 runs of one task in one
+call, all or nothing: one invalid item refuses the batch, naming `runs[i]`. Give
+each run `metadata` (≤16 string labels, e.g. `{candidate_id: "c_42"}`) and an
+`idempotency_key`: resending a key returns the existing run (`deduplicated`)
+instead of starting another — even after the task was republished — and the same
+key with a different request is a `409`. Read results with `list_task_runs`
+(filter by `task_id`, `status`, `metadata=key:value`, a creation window) and
+`get_task_run`, or subscribe a webhook to `task_run.completed`, sent once per run
+as it finishes.
+
+**Retries.** A background run is tried again — at most 3 tries — when its
+worker stopped under it, or when the model provider failed transiently before
+any tool ran, so a side-effecting tool never runs twice. Everything else settles
+on the first try. `tries` says how many there were; cost adds up across them.
+
+`cancel_task_run` stops a queued run at once and a running background one
+within seconds; an inline run cannot be canceled. `delete_task_run` (and
+`delete_task_runs` by metadata) erases a run's inputs, files, output, trace and
+config, keeping its cost and metadata — and a workspace's retention policy does
+the same on schedule (`content_expires_at`).
+
+### Reading a run
 
-The response is the whole run — `output`, a `trace` of every tool call and
-everything the model wrote (secrets redacted, long fields truncated and marked),
-`steps_used` against `max_steps`, the tokens each model spent and
-`provider_cost`.
+`get_task_run` is the whole run — `config`, `vars`, `files` (each PDF's
+extracted text and its scanned pages, exactly what the model saw), `output`, a
+`trace` of every tool call and everything the model wrote (secrets redacted,
+long fields truncated and marked), `steps_used` against `max_steps`, the tokens
+each model spent and `provider_cost`. A result over 64 KB is refused back to the
+model, which is told to shorten it.
 
 **`attempts` is worth reading.** A run that ends without calling `submit_result`
 is re-prompted rather than failed, and **each re-prompt starts the step budget
@@ -1043,28 +1100,28 @@ the third go, having used up to three times the rounds `steps_used` shows.
 `steps_used` is the busiest attempt's count, because that is the number the cap
 governs; `timeout_seconds`, not `max_steps`, is what actually bounds a run.
 
-A failure carries `error.type`, and it is a closed vocabulary that says whose
-problem it is:
+`status` is `queued`, `running`, `completed`, `failed` or `canceled`. A failure
+carries `error.type`, a closed vocabulary that says whose problem it is:
 
-- `missing_vars` — a required input had no value and no default. Caught before
-  anything ran, so it cost nothing.
+- `invalid_input` — a required input was missing, a file could not be
+  downloaded or read, or the model cannot see scanned pages. Caught before the
+  model ran, so it cost nothing.
 - `no_output` — the model finished without calling `submit_result`, twice; the
   framework already re-prompted it once. **Fix the prompt**: say what the task
   is for and that finishing means calling the tool.
 - `step_limit` — every round of an attempt was used and no result came back.
   **Fix `max_steps`**, or narrow what the task does. Reported apart from
   `no_output` precisely so nobody rewrites a prompt that was never the problem.
-- `timeout` — `timeout_seconds` elapsed.
+- `timeout` — `timeout_seconds` elapsed (reading the files counts).
 - `provider_error` — the model or an MCP server failed. Not yours to fix.
 - `configuration` — yours to tell them: a missing BYOK key, a tool version this
   publish pinned that has since been deleted, an integration whose credential no
   longer resolves.
 - `platform` — ours.
-- `canceled` — a deploy or restart stopped the run. A batch row is drafted again
-  automatically; a run started by hand is run again.
+- `canceled` — someone canceled it, or a deploy stopped an inline run.
 
-Each run records `task_version` — which published definition ran it, and null
-for a `version: "draft"` run. That is what makes two runs either side of an edit
+Each run records `task_version` — which published definition was its base, null
+for a draft or inline task. That is what makes two runs either side of an edit
 tell apart.
 
 Task runs are **not** in the Observability charts, which are built on calls and
@@ -1269,7 +1326,7 @@ collides with an output field name (one of the two would be unreachable); a
 `from_email` whose domain is not verified on that Resend account right now.
 
 **A header that exists but is blank on some rows still passes create** and fails
-those rows at draft time with `missing_vars` — one row, not the batch, and with
+those rows at draft time with `invalid_input` — one row, not the batch, and with
 no tokens spent. Flag blank cells in a required column before creating.
 
 **A row that can never be sent is never drafted.** If a mapped column the task
@@ -1407,11 +1464,47 @@ Replies are answered by the agent on the sender's
 `{{userdata.<column>}}` and the whole template, buttons included, as its own
 first message — so write that agent's prompt against the CSV's column names.
 
+A tapped quick-reply button reaches the agent as its text; the item's `content`
+keeps the button's `payload` (never shown to the agent) and `replied_to`, the
+template it answers. Photos reach an agent whose model has `vision: true`; any
+other agent is told to ask for a description, so pick a vision model for a
+number people send photos to. Voice notes, video and documents are not read.
+
+**One message to one person** is `create_conversation_item`, not a batch. `to`
+is a `conversation_id`, or `number` (your WhatsApp sender, E.164) plus `peer`
+(their number) to reach someone with no conversation yet. Four `type`s:
+
+- `template` — an approved template with every variable filled
+  (`template.variables`); may go any time.
+- `agent_text` — free text sent as the agent's own message.
+- `note` — background for the agent, never delivered (any contact, PSTN ones too).
+- `instruct` — the agent writes and sends the next message itself, in the
+  conversation's language, without ever saying it was instructed. Refused with
+  `voice_session_live` while they are on a call with the agent.
+
+WhatsApp allows free text only within **24 hours of their last message or
+call** (`ref.whatsapp_window_expires_at`). Outside it `agent_text` and
+`instruct` are refused with `whatsapp_window_closed`, unless
+`on_window_closed: {opener: {id, variables}}` names a template to send first:
+the text is then `held` until they reply, and `expired` after 7 days. Prefer an
+opener over a bare template when what you want to say is free-form.
+`userdata` on a post joins the contact's and is what the agent answering their
+reply starts from. Send an `idempotency_key` when retrying is possible. A
+provider refusal still stores the item, `delivery_status: failed` (nothing resends it). While
+they have an open chat, post anything but a note into that chat's conversation:
+another one is refused with `chat_open_elsewhere`.
+
 ## Secrets, keys and webhooks
 
 **Secrets** are workspace values referenced as `{{secrets.NAME}}` from tool
 operations and integration config. They are write-only: once stored, only the
-runtime resolves them.
+runtime resolves them. A session can also bring its own, as `secrets` on the
+request that starts it; for that session they join the workspace's under the
+same `{{secrets.NAME}}`, the session's value winning. A tool that reads a name
+that is not a workspace secret saves with a warning, and starting a session
+without supplying it is refused — an inbound call or chat, which has no
+request, gets one only from the inbound webhook below. Integration and carrier
+credentials and MCP server headers must be workspace secrets.
 
 **BYOK.** Talqing runs agents on the workspace's own provider API keys and has
 none of its own. `list_provider_keys` says which providers are configured, and
@@ -1422,7 +1515,21 @@ there, tell them the key has to be added before the agent can publish.
 
 **Webhooks** are workspace-wide and fire for every agent. `event_types` lists
 what can be subscribed to, and `webhook_deliveries` is where to look when one
-seems silent.
+seems silent. `session.refused` fires for every inbound call or channel chat
+turned away before an agent ran.
+
+**The inbound webhook** is how an inbound PSTN call, WhatsApp call or new
+WhatsApp/Telegram chat gets what an outbound request would carry. An agent with
+`inbound_webhook: true` has Talqing POST `session.request` (channel, numbers,
+`contact_key`, the opening message) to the workspace's one URL
+(`set_inbound_webhook`) before the session starts; the answer may set `vars`,
+`secrets`, `agent_override`, `metadata` and `userdata`, each meaning what it
+means on `create_outbound_call`. No valid answer within 3 s **refuses the
+session** (`inbound_webhook_failed`, reason in `error`), so publishing such an
+agent needs the webhook set, and `test_inbound_webhook` checks a reply before
+real callers depend on it. A chat asks once, when it opens. `metadata` — the
+caller's own labels — appears on the call or chat and filters `list_calls` and
+`list_chats` (`metadata=key:value`).
 
 ## Running an agent, and reading what happened
 
@@ -1445,9 +1552,14 @@ every agent the session runs and is gone when the session ends. Use `userdata`
 for facts about the person and `vars` for configuration of the session; unlike
 `userdata`, `vars` is never written onto the caller's contact record and no tool
 can change it mid-session. An empty string is a deliberate blank, not a request
-for the default. The model can see the values, so credentials stay in workspace
-secrets. On a batch it is one bag for the whole campaign, copied onto every call
-it places — per-person data is what a recipient's `userdata` is for.
+for the default. The model can see the values, so credentials go in secrets. On
+a batch it is one bag for the whole campaign, copied onto every call it places —
+per-person data is what a recipient's `userdata` is for.
+
+All three (not batches) also take `secrets`, `{NAME: value}`: credentials for
+that one session, read by its tools as `{{secrets.NAME}}` and never shown to the
+model or returned. A web call's `resume_call` keeps them, and its own `secrets`
+adds or replaces.
 
 **Per-call configuration.** All three — and `create_call_batch` — also take four
 fields that change what runs on that one call:
@@ -1494,7 +1606,13 @@ rather than as two messages. The agent's model must have `vision` (see *Images*
 above) or the call is refused naming the model.
 
 **Reading it back.** A *conversation* is the thread with a person, on any
-surface; a *call* is one voice or video session. `list_conversations` and
+surface; a *call* is one voice or video session. A person is one **contact**
+(`contact_key`) per business number: `phone:<your number>:<their number>` spans
+phone calls, WhatsApp messages and WhatsApp calls on that number, with one
+`userdata`. Which thread a session writes to is the answering agent's
+`conversation.context` (`transcript` joins their newest thread), except that a
+WhatsApp call always joins their open WhatsApp chat. Every item carries the
+`channel` it arrived on. `list_conversations` and
 `list_conversation_items` are the transcript; `list_conversation_sessions` lists
 its calls and chats, and `get_chat` gives one chat's cost and analysis.
 `list_calls` and `get_call` cover phone and web calls — `get_call` gives the transcript with every tool call and
@@ -1506,6 +1624,13 @@ What a run costs is the provider spend on the workspace's own keys plus
 Talqing's platform fee, which `get_catalog` gives: per minute on voice and
 video, and $0.0001 per answered message on text.
 
+Items posted through `create_conversation_item` carry `post_type` and the
+`author` you gave (shown to people, never to the agent or the contact). Notes and
+instructions have no `channel`. Outbound WhatsApp and Telegram messages move
+through `delivery_status` (`queued`, `sent`, `delivered`, `read`, or
+`undelivered`/`failed` with `delivery_error`), and each move fires the
+`conversation.item.status` webhook.
+
 When an agent misbehaves, read the actual run before theorizing. The transcript
 and the final `userdata` usually name the cause.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talqing/mcp",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "MCP server for building Talqing AI voice, video and text agents from Claude Code, Codex, or any MCP client.",
   "license": "MIT",
   "homepage": "https://talqing.com",

package/tools.json

@@ -395,7 +395,7 @@
       "role": "write"
     },
     {
-      "description": "Run the task once with the variables you supply, and wait for the result.",
+      "description": "Run a task for real: its tools, MCP servers and model all act and spend.",
       "method": "POST",
       "name": "run_task",
       "parameters": {
@@ -404,12 +404,26 @@
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/tasks/{task_id}/runs",
+      "path": "/v1/task-runs",
       "read_only": false,
       "role": "write"
     },
     {
-      "description": "This task's runs, newest first, each with its output, trace and cost.",
+      "description": "Queue up to 1000 runs of one task, in the background. One invalid item refuses all.",
+      "method": "POST",
+      "name": "run_task_batch",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('run_task_batch').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/task-runs/batch",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Task runs, newest first, without traces or inputs.",
       "method": "GET",
       "name": "list_task_runs",
       "parameters": {
@@ -418,12 +432,12 @@
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/tasks/{task_id}/runs",
+      "path": "/v1/task-runs",
       "read_only": true,
       "role": "read"
     },
     {
-      "description": "One run in full: what it produced, every tool it called on the way, and what it cost.",
+      "description": "One run in full: its config, inputs, output, trace and cost. Secrets are redacted.",
       "method": "GET",
       "name": "get_task_run",
       "parameters": {
@@ -432,10 +446,52 @@
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/tasks/{task_id}/runs/{run_id}",
+      "path": "/v1/task-runs/{run_id}",
       "read_only": true,
       "role": "read"
     },
+    {
+      "description": "Cancel a queued or background run. A running one stops within seconds.",
+      "method": "POST",
+      "name": "cancel_task_run",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('cancel_task_run').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/task-runs/{run_id}/cancel",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Delete a run's inputs, files, output and trace; its cost and metadata stay.",
+      "method": "DELETE",
+      "name": "delete_task_run",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('delete_task_run').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/task-runs/{run_id}",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Delete the content of every run whose metadata matches, as `delete_task_run` does.",
+      "method": "POST",
+      "name": "delete_task_runs",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('delete_task_runs').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/task-runs/delete",
+      "read_only": false,
+      "role": "write"
+    },
     {
       "description": "List the workspace's integrations with their provider, status and config.",
       "method": "GET",
@@ -1878,6 +1934,20 @@
       "read_only": false,
       "role": "write"
     },
+    {
+      "description": "Post a template, agent text, note or instruction into a conversation, or start one with a person.",
+      "method": "POST",
+      "name": "create_conversation_item",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('create_conversation_item').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/conversations/items",
+      "read_only": false,
+      "role": "write"
+    },
     {
       "description": "Workspace analytics: volume, endings, recordings, response time and spend. One snapshot of a date range, up to 7 days.",
       "method": "GET",
@@ -2046,6 +2116,76 @@
       "read_only": true,
       "role": "read"
     },
+    {
+      "description": "Get the workspace's inbound session webhook.",
+      "method": "GET",
+      "name": "get_inbound_webhook",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('get_inbound_webhook').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/inbound-webhook",
+      "read_only": true,
+      "role": "read"
+    },
+    {
+      "description": "Set the URL asked for an inbound session's configuration.",
+      "method": "PUT",
+      "name": "set_inbound_webhook",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('set_inbound_webhook').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/inbound-webhook",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Remove the inbound session webhook.",
+      "method": "DELETE",
+      "name": "delete_inbound_webhook",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('delete_inbound_webhook').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/inbound-webhook",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Issue a new signing secret; the old one stops working at once.",
+      "method": "POST",
+      "name": "rotate_inbound_webhook_secret",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('rotate_inbound_webhook_secret').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/inbound-webhook/rotate-secret",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Send a sample request and check the reply against the response schema.",
+      "method": "POST",
+      "name": "test_inbound_webhook",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('test_inbound_webhook').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/inbound-webhook/test",
+      "read_only": false,
+      "role": "write"
+    },
     {
       "description": "The provider catalog: every LLM, STT, TTS, realtime and avatar model that agents may use.",
       "method": "GET",