@talqing/mcp 0.10.0 → 0.11.0

package/SKILL.md

@@ -897,15 +897,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.
 
@@ -943,17 +943,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 +999,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 +1016,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 +1034,50 @@ 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, 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 +1086,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 +1312,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talqing/mcp",
-  "version": "0.10.0",
+  "version": "0.11.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",