@talqing/mcp 0.3.1 → 0.3.3

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": "...",
@@ -180,6 +209,10 @@ An agent is a single object, `config`, plus what you attach to it:
   Leaving it out resolves `name` against the team defined on the call that runs
   the agent, which publishes with a warning rather than an error.
 
+  One model cannot be handed off from at all: `openai/gpt-live-1` refuses new
+  instructions once a call is connected, so an agent with both that realtime
+  model and a handoff destination is refused on save. Every other model is fine.
+
   **`context` is what the next agent starts from** — the same three words an
   agent's own `conversation.context` uses for what a new *call* starts from.
 
@@ -293,10 +326,11 @@ voice. Read it before choosing; do not assume a model exists.
 People can attach a photo to a web chat, a web voice call or a web video call,
 and the agent sees it. **There is no setting for this** — whether an agent can
 read images is decided by the model it runs, and `vision` on that model's catalog
-entry is where it says so. Every LLM entry today reads images; the two
-`grok-voice-*` realtime entries do not, and an agent on one of them cannot be
-sent a photo at all. If a user wants image input, check `vision` before picking
-the model rather than changing anything on the agent.
+entry is where it says so. Most entries read images; `gemini-3.8-flash`,
+`gemini-3.7-flash`, `openai/gpt-live-1` and the two `grok-voice-*` realtime
+entries do not, and an agent on one of them cannot be sent a photo at all. If a
+user wants image input, check `vision` before picking the model rather than
+changing anything on the agent.
 
 A phone call carries no files, so this is web only.
 
@@ -476,7 +510,7 @@ do not promise the user one — change the models or the language instead:
   Saaras endpoint on their own schedule and ignore that window entirely, so on
   those two the setting is a floor.
 - **Batch speech-to-text** (`streaming: false` — xAI `xai-stt-batch`, ElevenLabs
-  `scribe_v2`, OpenAI `gpt-4o-transcribe`) → it has no endpointer at all, so
+  `scribe_v2`, OpenAI `gpt-transcribe`) → it has no endpointer at all, so
   LiveKit's audio end-of-turn model takes over when `config.language` is one of
   the fourteen it was trained on: Arabic, Chinese, Dutch, English, French,
   German, Hindi, Indonesian, Italian, Japanese, Korean, Portuguese, Spanish,
@@ -520,8 +554,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 +589,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 +836,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 +864,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 +886,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 +937,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 +954,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 +1140,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.
@@ -1092,6 +1172,12 @@ collides with an output field name (one of the two would be unreachable); a
 those rows at draft time with `missing_vars` — 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
+does NOT write is blank (or `to` is not an address), the row is `skipped` with
+`skip_reason: "unfillable"` the moment the batch is created, and costs nothing.
+`skips.unfillable` counts them. Filling the cell in with
+`patch_email_batch_recipient` brings the row back to drafting.
+
 ### Two jobs, and a human between them
 
 **Drafting** starts on `start_at` (or immediately), runs `draft_concurrency` rows
@@ -1102,21 +1188,29 @@ the last row lands. It has no business-hours window: nobody receives a draft. It
 to review"*, never "finished": it says nothing about what has been sent.
 
 **Sending** is separate, only ever happens when a person asks, and is its own
-row. `create_email_send` takes `recipient_ids` or `selection: "all_drafts"` and
-returns a **send** you can steer:
-
+row. `create_email_send` takes a `scope` and returns a **send** you can steer:
+
+- `scope: "selected"` with `recipient_ids` sends exactly those rows.
+- `scope: "all"` is a standing send: every row of the batch as it finishes
+  drafting, including rows not drafted yet — so **it mails drafts nobody has
+  read**. Say so, and get an explicit yes, before creating one. It waits while
+  drafting runs (`next_send_reason: "drafting"`) and ends once drafting has and
+  every draft has gone. It cannot be live beside any other send of the batch —
+  that is a 409 naming the live send.
 - `start_at` schedules it, `window` (on its own `timezone`) holds it to business
-  hours, `send_gap_seconds` is the minimum wait between two emails (1 second to
-  1 hour) and `send_daily_cap` bounds how many may leave per local day. Anything
-  omitted comes from the batch.
+  hours, `send_gap_seconds` is the minimum wait between two emails of the
+  **batch** (1 second to 1 hour) and `send_daily_cap` bounds how many the batch
+  may send per local day. Anything omitted comes from the batch.
+- A draft a live send covers reads `queued`, and is still a draft: it can be
+  edited, skipped or redrafted until the send takes it.
 - `pause_email_send` stops on the next email; `resume_email_send` carries on.
-- `cancel_email_send` gives **every unsent row back as a draft**, ready for
-  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.
+- `cancel_email_send` ends it; its unsent rows are simply drafts again. A send's
+  scope never changes, so cancel and create another to change what it covers.
+- `get_email_send` carries `next_send_at` and `next_send_reason` (`start`,
+  `window`, `daily_cap`, `retry`, `gap`, `drafting`), 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
@@ -1148,7 +1242,9 @@ action that revives a batch that already finished drafting. Its `selection` is
 task wrote them), `not_sent`, or `all` — which names every row it refuses.
 **Each redrafted row runs the task again and is billed again**, so say the row
 count before running `all`. A person's edited cells survive unless
-`clear_overrides` is set.
+`clear_overrides` is set. A `queued` row is redrafted too, and its send takes
+the new draft. Read `draft_failures` before redrafting `failed`: a task that
+declined a row on purpose will most likely decline it again.
 
 **One address is mailed at most once per batch**, enforced when the row is
 claimed for sending: the second row settles `skipped` with
@@ -1157,16 +1253,20 @@ 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
+`get_email_batch` carries live counts, `skips` (why rows were skipped),
+`draft_failures` (why drafts failed, most common first), `failure_reason`,
+`sent_today` (against `send_daily_cap`), `drafted_versions`,
+`stale_redraftable` / `stale_sent` and the drafting cost so far. Measure
+progress against what can be reached: `unfillable` rows are never drafted, and
+skipped, failed or cancelled rows are never sent.
+
+**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.3",
   "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",
@@ -17,7 +17,7 @@
   ],
   "type": "module",
   "bin": {
-    "talqing-mcp": "./dist/index.js"
+    "talqing-mcp": "dist/index.js"
   },
   "files": [
     "dist",

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": {
@@ -1249,7 +1319,7 @@
       "role": "write"
     },
     {
-      "description": "Put skipped rows back. `selection: \"all_eligible\"` means every skipped row.",
+      "description": "Put skipped rows back. `selection: \"all_eligible\"` means every row a person skipped; an `unfillable` row is restored by filling in its cell instead.",
       "method": "POST",
       "name": "restore_email_batch_recipients",
       "parameters": {
@@ -1277,7 +1347,7 @@
       "role": "write"
     },
     {
-      "description": "Send these rows. **This mails real people and cannot be undone.**",
+      "description": "Send rows. **This mails real people and cannot be undone.**",
       "method": "POST",
       "name": "create_email_send",
       "parameters": {
@@ -1333,7 +1403,7 @@
       "role": "write"
     },
     {
-      "description": "Stop sending. It takes hold on the next email, and nothing is lost \u2014 the rows stay queued for whenever you resume.",
+      "description": "Stop sending. It takes hold on the next email, and nothing is lost \u2014 the rows stay queued, and editable, until you resume.",
       "method": "POST",
       "name": "pause_email_send",
       "parameters": {
@@ -1361,7 +1431,7 @@
       "role": "write"
     },
     {
-      "description": "Stop this send, and give every row it has not sent back as a draft.",
+      "description": "Stop this send for good. Every row it has not sent stays a draft, exactly as it was, ready for another send \u2014 not a destructive action.",
       "method": "POST",
       "name": "cancel_email_send",
       "parameters": {
@@ -1752,6 +1822,34 @@
       "read_only": true,
       "role": "read"
     },
+    {
+      "description": "Search the 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 hosts that can serve one OpenRouter language model; fastest first when the workspace has an OpenRouter key. Each `host` is a valid entry for `llm.hosts`.",
+      "method": "GET",
+      "name": "list_model_hosts",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('list_model_hosts').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/catalog/models/hosts",
+      "read_only": true,
+      "role": "read"
+    },
     {
       "description": "The Anam avatar gallery \u2014 the faces a video agent can wear.",
       "method": "GET",