@talqing/mcp 0.3.1 → 0.3.2

package/SKILL.md

@@ -161,6 +161,35 @@ An agent is a single object, `config`, plus what you attach to it:
   not this list. As with `tools`, an entry may instead carry `{"mcp": {name,
   url, headers, allowed_tools, tools_namespace}}`, which is created as a
   `custom_mcp` integration and replaced by its id.
+- **`tasks`** — jobs this agent can enter and come back from, each
+  `{"name": "collect_shipping_address", "task_id": "...", "description": "...",
+  "message": "..."}`. Each becomes one ordinary tool the model can call: the
+  task takes over the conversation, speaks with THIS agent's voice and ears,
+  and hands its typed `output` back as the tool's result. Use one for a bounded
+  job inside a longer call — taking an address, qualifying a lead — and a
+  `handoffs` entry when the caller should belong to someone else from then on.
+
+  `name` is yours, not the task's, so renaming the task never changes the tool
+  name a published prompt was written against. The task must be **published**;
+  publishing the agent pins the version. An entry may instead carry `{"task":
+  {...whole TaskConfig...}}`, which on the agent endpoints is created and
+  published as a real task, exactly as an inline tool is.
+
+  **The task's `vars` are this tool's schema, minus every variable the call can
+  answer for itself** — every name the CALLING AGENT declares, plus every name
+  the session was started with. Those are filled in automatically and never
+  shown to the model, a declared-but-blank one included. So a task declaring
+  `customer_id` on an agent declaring `customer_id` shows the model nothing to
+  invent. Anything left over becomes a model argument, which is why a task
+  should declare only what the caller or the model must supply: a value already
+  in `{{userdata.*}}` belongs in the task's prompt, not in its `vars`.
+  Publishing warns on the bad shape.
+
+  A task inherits the call's whole media stack, so one task fits every agent and
+  every channel. It cannot contain a `handoff` (publish refuses it), the calling
+  agent's own tools are NOT available while it holds the floor, and
+  `timeout_seconds` on the task is the only bound on how long it may hold the
+  caller.
 - **`handoffs`** — where this agent may pass the conversation next, each
   `{"name": "Billing", "agent_id": "...", "description": "...", "context":
   "transcript" | "summary" | "none", "recent_turns": 2, "summary_prompt": "...",
@@ -520,8 +549,13 @@ A tool is one capability the agent's LLM can call mid-conversation. It has:
   to get it out of the conversation, and a bare `{"type": "string"}` is how a
   tool ends up called with the wrong value. Mark the ones the tool cannot run
   without as `required`, and use an `enum` wherever the set of values is closed.
-- **`long_running_task`** — voice and video agents keep talking while it runs;
-  text agents wait for the result either way.
+- **`long_running_task`** — voice and video agents keep talking while it runs and
+  share the result when it lands; a run finishing within a second answers inline
+  instead. Text agents wait either way. There is no fixed line — steer it from
+  the description, phrased conditionally ("if it is still running, say you are on
+  it; if the result is already there, give it"), because an unconditional "say
+  you have started it" makes the agent announce work it has already finished.
+  Cannot be `silent`, or contain a `transfer` or `handoff`.
 - **`silent`** — no immediate reply after it runs. You rarely need to set it: a
   tool in which no operation can return a response (see below) is silent
   automatically, and so is any run that reaches `end_call`.
@@ -550,7 +584,8 @@ LLM — use it for noisy intermediate steps.
 
 **Silence is derived, not defaulted.** If no operation in the tree can return a
 response, the tool is silent whatever `silent` says — including operations inside
-`if` branches. So a tool that is just `say "Your appointment is confirmed"` says
+`if` branches, and including any `background_execution` one, which has no
+response to hide. So a tool that is just `say "Your appointment is confirmed"` says
 that once, rather than saying it and then improvising a second sentence on top.
 If the agent should add a closing line, add a `generate_reply` operation that
 states what to add; do not try to turn the derived silence off.
@@ -796,17 +831,23 @@ Each hook points at a **published tool id**, or null.
 
 ## Agent tasks
 
-An **agent task** is an agent nobody talks to. Same prompt, same model, same
-tools, same MCP servers — minus every conversational organ (speech, greeting,
-turn-taking, handoffs, knowledge bases), plus the one thing a conversation
-cannot have: a **typed structured output**. It takes named inputs, does some
-work, and returns a value. `POST /v1/tasks/{task_id}/runs` runs one and waits.
+An **agent task** takes named inputs, does some work, and returns a **typed
+structured output**. Same prompt, same model, same tools, same MCP servers, same
+knowledge and 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
+`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.
 
 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
 rather than a conversation: research a company from a domain, classify a
-message, draft an opening line, pull a field out of a document.
+message, draft an opening line, take a shipping address mid-call.
 
 `config` is:
 
@@ -818,10 +859,18 @@ message, draft an opening line, pull a field out of a document.
   `.direction` — there is no call.
 - **`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. There is no
-  `stt`, `tts`, `realtime`, `greeting`, `turn_handling`, `avatar`, `handoffs`,
-  `recording`, `analysis`, `kb_ids` or lifecycle hook — a task has nobody to
-  hear, nobody to greet, nothing to hand over and one turn to hook.
+  a step rather than as one, so it costs no steps and real seconds. It is the
+  one media slot a task keeps, because an LLM is stateless per request and
+  swapping one in rebuilds nothing.
+- **`kb_ids`**, **`on_enter`**, **`on_exit`**, **`on_user_turn_completed`** —
+  exactly an agent's. `on_user_turn_completed` only ever fires when an agent
+  entered the task; a standalone run has nobody to take a turn.
+- There is no `stt`, `tts`, `realtime`, `language`, `turn_handling`, `channel`,
+  `greeting`, `avatar`, `recording`, `analysis`, `conversation` or `handoffs`.
+  A task runs on the media of the session that entered it, or on no media at
+  all — which is what lets one task serve a voice agent and an email batch.
+  `handoffs` is refused with a reason: a task hands control back to whoever
+  entered it, so handing the conversation on would strand that return.
 - **`tools`** / **`mcps`** — exactly an agent's, attached by id or defined
   inline, and pinned by publish exactly as an agent's are: republishing a tool
   does not change a published task until that task is published again.
@@ -832,15 +881,26 @@ message, draft an opening line, pull a field out of a document.
   that failure costs nothing. A value for a name the task does not declare is
   refused too, rather than silently dropped — which is the one difference from an
   agent, whose key space is open.
+
+  **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.
 - **`max_steps`** (default 25, max 50) — how many LLM → tools → LLM **rounds**
-  the run may take. A round, not a tool call: four tools in one reply cost one
-  step. This is the runaway-loop guard.
-- **`timeout_seconds`** (default 300, max 600) — the real time budget.
+  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
+  runs on the calling session's budget instead — three rounds per reply on
+  voice and video, twenty-five on text, refreshed on every user turn.
+- **`timeout_seconds`** (default 300, max 600) — the real time budget, and the
+  one setting that applies both ways. Entered by an agent it is the only bound
+  on how long the task may hold the caller: keep it short on a voice agent.
 
 A name may not appear in both `vars` and `output`: a run's inputs and its output
 are read side by side, so a collision would make one of the two unreachable.
@@ -872,9 +932,15 @@ yours: it changes what every run and every live email batch does.
 
 The model does not "return" the output. At compile time the task gains one
 generated tool, **`submit_result`**, whose arguments are exactly the `output`
-fields, and one generated paragraph telling it that calling that tool is how the
-run finishes. Both are written for you: never declare a tool named
-`submit_result`, and never write that paragraph into the prompt yourself.
+fields. Never declare a tool of that name yourself.
+
+**Nothing is appended to a task's prompt.** `submit_result_description` is the
+whole of what the model is told about how a run ends, so it has to say that
+calling the tool IS the ending — a written answer produces nothing — and that a
+value the model could not determine goes in as `null`. It is required and
+non-empty, but a new task only carries the one-line stub
+`"Submit the result and finish."`: **replace it.** A task whose finishing is
+described by that stub is a task relying on the model to guess.
 
 Every output field is **required and nullable** in that tool. The model must say
 something about every field, including "I could not find it" — an optional field
@@ -883,6 +949,15 @@ generated yet" then look identical to whoever reads the row. Say so in each
 field's `description`: that description is the only instruction the model gets
 about what belongs there.
 
+A task an agent enters also gets **`finish_without_result`**, which abandons the
+job and fails the calling agent's tool call.
+`finish_without_result_description` — required and non-empty too, and starting as
+the stub `"Give up and finish without a result."` — is the only thing saying when
+that is allowed: **a task that gives up on work it should have finished is fixed
+there, not in the prompt.** Narrow it to the caller actually changing their mind;
+"I could not work out a value" is a `null`, not a reason to abandon. Publishing
+refuses either description blank.
+
 ### Reading a run
 
 `run_task` **executes for real**: the tools call the tenant's endpoints with
@@ -1060,8 +1135,8 @@ afterwards will not forgive us:
   opted in. This runs on *their* Resend account under *their* agreement.
 - **Nothing is sent that they have not reviewed and selected.** Creating a batch
   only drafts.
-- **Every row runs the task's CURRENT PUBLISHED version**, re-read every pass, so
-  publishing mid-batch changes every row drafted after that moment. Which version
+- **Every row runs the task's CURRENT PUBLISHED version**, re-read as drafting
+  goes, so publishing mid-batch changes every row drafted after that moment. Which version
   wrote which rows is on the batch as `drafted_versions`, and
   `redraft_email_batch_recipients` with `selection: "stale_version"` is how the
   older ones are rewritten.
@@ -1114,9 +1189,10 @@ returns a **send** you can steer:
   another send. It is also the ONLY way to change what a scheduled send
   contains: a send's rows are fixed when it is created, and there is no verb for
   pulling rows out of one.
-- `get_email_send` carries `next_send_at`, which is how "waiting for Monday" is
-  told apart from "stuck", and covers a start time, a shut window and a spent
-  daily cap alike.
+- `get_email_send` carries `next_send_at` and `next_send_reason` (`start`,
+  `window`, `daily_cap`, `retry`, `gap`), which is how "waiting for Monday" is
+  told apart from "stuck". `patch_email_send` reaches a live send within five
+  minutes, so raising a spent cap or removing a window needs no cancel.
 
 **The safeguard here is a RATE, not a row count.** `send_daily_cap` (200 by
 default, per batch, `null` for uncapped) is what stands between a 5 000-row list
@@ -1158,15 +1234,16 @@ ours — Resend keeps one and auto-suppresses hard bounces and complaints.
 ### Watching it
 
 `get_email_batch` carries live counts, `failure_reason`, `sent_today` (against
-`send_daily_cap`), `drafted_versions` and the drafting cost so far. A batch that
-stops itself did so after ten consecutive drafting failures, or on the first
-`configuration` failure — a deleted task, a field map an edit broke — because
-those will fail identically for every remaining row.
-
-**A send fails on its own, and never takes the batch with it.** Ten consecutive
-provider failures, or one account-level refusal (a revoked key, an unverified
-domain, an exhausted quota), stop that send and return its untouched rows to the
-review table as drafts. Fix the cause and create another send; the drafts are
+`send_daily_cap`), `drafted_versions`, `stale_redraftable` and the drafting cost
+so far.
+
+**Stopping itself comes in two shapes, and they need different advice.** Ten
+consecutive failures **pause** a batch or a send: everything is where it was and
+`resume` continues, so say that rather than suggesting the work be rebuilt.
+`failed` is the deterministic stop — a deleted task, a field map an edit broke, a
+revoked key, an unverified domain — where trying again cannot help until
+something outside Talqing changes. A failed SEND returns its untouched rows to
+the review table as drafts and never takes the batch with it; the drafts are
 still there. In the other direction, pausing or cancelling the *batch* stops
 drafting and does not touch a send that is already scheduled or going out.
 

package/package.json

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

@@ -954,6 +954,76 @@
       "read_only": false,
       "role": "write"
     },
+    {
+      "description": "List WebSocket media-stream connections a partner can dial.",
+      "method": "GET",
+      "name": "list_stream_connections",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('list_stream_connections').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/streams",
+      "read_only": true,
+      "role": "read"
+    },
+    {
+      "description": "Create a connection a streaming partner can dial.",
+      "method": "POST",
+      "name": "create_stream_connection",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('create_stream_connection').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/streams",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "One stream connection, with the URL to hand the partner.",
+      "method": "GET",
+      "name": "get_stream_connection",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('get_stream_connection').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/streams/{connection_id}",
+      "read_only": true,
+      "role": "read"
+    },
+    {
+      "description": "Rename a connection, point it at another agent, or disable it.",
+      "method": "PATCH",
+      "name": "patch_stream_connection",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('patch_stream_connection').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/streams/{connection_id}",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Delete a stream connection. Calls it already carried are kept.",
+      "method": "DELETE",
+      "name": "delete_stream_connection",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('delete_stream_connection').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/streams/{connection_id}",
+      "read_only": false,
+      "role": "write"
+    },
     {
       "description": "Dial a real phone number and have a published agent take the call.",
       "method": "POST",
@@ -1235,7 +1305,7 @@
       "role": "write"
     },
     {
-      "description": "Take drafted rows out of consideration. Reversible with `restore`.",
+      "description": "Take rows out of consideration. Reversible with `restore`.",
       "method": "POST",
       "name": "skip_email_batch_recipients",
       "parameters": {
@@ -1752,6 +1822,20 @@
       "read_only": true,
       "role": "read"
     },
+    {
+      "description": "Search the language models a provider offers too many of to list.",
+      "method": "GET",
+      "name": "search_models",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('search_models').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/catalog/models",
+      "read_only": true,
+      "role": "read"
+    },
     {
       "description": "The Anam avatar gallery \u2014 the faces a video agent can wear.",
       "method": "GET",