@talqing/mcp 0.3.0 → 0.3.1

package/SKILL.md

@@ -817,15 +817,14 @@ message, draft an opening line, pull a field out of a document.
   **not** read `{{system_vars.human_phone_number}}` / `.agent_phone_number` /
   `.direction` — there is no call.
 - **`llm`** — one model, with the same `fallback`, `reasoning_effort`,
-  `priority` and `builtin_tools` an agent's LLM has. 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.
+  `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.
 - **`tools`** / **`mcps`** — exactly an agent's, attached by id or defined
-  inline. **A task never pins a tool version**: republishing a tool changes
-  every task that uses it, immediately, with no step in between. That is
-  defensible for a bounded job and would not be for a live call, which is why
-  agents pin and tasks do not.
+  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.
 - **`vars`** — the task's **inputs**, declared exactly as an agent's variables
   are: a `name`, a `description`, an optional `default` and `required`. A run
   supplies values by name; one it omits falls back to the `default`, and a
@@ -835,25 +834,39 @@ message, draft an opening line, pull a field out of a document.
   agent, whose key space is open.
 - **`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 least one, at most 25. No arrays and no nested objects: a
-  task that wants to return five talking points returns one string containing
-  them.
+  `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 120, max 600) — the real time budget.
+- **`timeout_seconds`** (default 300, max 600) — the real time budget.
 
 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.
 
-**There is no draft and no publish step.** One config, strict at save: an
-invalid one is refused with a 400 listing every problem and nothing is stored,
-so a task that exists can always run. An edit takes effect on the next run with
-nothing in between — there are no versions, so there is no earlier wording to go
-back to and nothing records which definition produced an earlier run.
-`create_task` and `update_task` also return **`warnings`**: the problems that
-are real but not fatal, such as a prompt reading a variable nothing declares.
-There is no publish screen to show them on, so read them where they are.
+### Draft, publish, versions
+
+**A task has the same lifecycle an agent has**, and the same four functions.
+`create_task` and `update_task` write the **draft**, checked only for what a
+half-written task can be judged on — so a task saves before it has a model key,
+a prompt or an output field, and the person can keep building. `publish_task`
+freezes that draft as an immutable version, pins every attached tool to the
+version live at that moment, and makes it what runs. `get_task_version` reads a
+frozen one back and `rollback_task_version` puts one back into production,
+replacing the draft.
+
+`validate_task` is the publish-grade check without the publish: a workspace API
+key for the model, at least one `output` field, the attached tools' operation
+trees, and the email batches already drafting with this task. Run it before
+`publish_task` — its `errors` are what a publish would refuse with, and its
+`warnings` (a prompt reading a variable nothing declares, a task with no prompt)
+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` →
+`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.
 
 ### The output tool
 
@@ -876,6 +889,11 @@ about what belongs there.
 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.
+
 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
@@ -901,9 +919,16 @@ problem it is:
   `no_output` precisely so nobody rewrites a prompt that was never the problem.
 - `timeout` — `timeout_seconds` elapsed.
 - `provider_error` — the model or an MCP server failed. Not yours to fix.
-- `configuration` — yours to tell them: a missing BYOK key, a deleted or
-  unpublished tool, an integration whose credential no longer resolves.
+- `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.
+
+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
+tell apart.
 
 Task runs are **not** in the Observability charts, which are built on calls and
 conversations. `list_task_runs` is where a task's own history lives.
@@ -1035,9 +1060,11 @@ 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 as it stands right now.** Editing it while a batch
-  is drafting changes every row generated after that moment, and there is no way
-  to get the old wording back.
+- **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
+  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.
 - **Talqing reports what it sent, not what landed.** Deliveries, bounces and
   spam complaints live in the Resend dashboard, and watching them there is how a
   sending domain survives.
@@ -1067,26 +1094,46 @@ no tokens spent. Flag blank cells in a required column before creating.
 
 ### Two jobs, and a human between them
 
-**Drafting** starts on `start_at` (or immediately), honours `calling_window` on
-the batch's `timezone`, runs `max_concurrency` rows at a time, and stops when
-the last row lands. Its `status` is about drafting and nothing else —
-`scheduled`, `drafting`, `paused`, `drafted`, `canceled`, `failed`. A `drafted`
-batch means *"the drafts are ready to review"*, never "finished": it says
-nothing about what has been sent.
-
-**Sending** is separate and only ever happens when a person asks.
-`send_email_batch_recipients` takes **at most 50 rows, named one by one**. There
-is no `selection` shorthand on it, no bulk endpoint, and there must not be one:
-a 5 000-row batch cannot leave the building without a hundred deliberate calls,
-each of which should follow reading the fifty drafts it covers. That friction is
-the only structural safeguard this feature has — **do not offer to work around
-it.** `skip`, `restore` and `retry` *do* take `selection: "all_eligible"`,
-because they are reversible and mailing strangers is not.
-
-Each send may override `from_email` / `from_name` / `reply_to` for that call
-alone; the batch's own default is unchanged. The Resend account itself is not
+**Drafting** starts on `start_at` (or immediately), runs `draft_concurrency` rows
+at a time with at least `draft_gap_seconds` between two starts, and stops when
+the last row lands. It has no business-hours window: nobody receives a draft. Its
+`status` is about drafting and nothing else — `scheduled`, `drafting`, `paused`,
+`drafted`, `canceled`, `failed`. A `drafted` batch means *"the drafts are ready
+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:
+
+- `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.
+- `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.
+
+**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
+and a sending domain nobody trusts again. Before creating a send, say how many
+emails it is and roughly how long it will take at the pace it has — and if the
+user asks to raise or remove the cap, say what it is for rather than just doing
+it.
+
+Each send may override `from_email` / `from_name` / `reply_to` for itself alone;
+the batch's own default is unchanged. The Resend account itself is not
 overridable — a different account is a different batch.
 
+Every email carries `List-Unsubscribe: <mailto:…?subject=unsubscribe>`, pointed
+at the send's `reply_to` or its `from_email`. There is no one-click unsubscribe
+and no suppression list, so an opt-out arrives as a reply in the tenant's own
+inbox and honouring it is theirs to do.
+
 ### Fixing rows
 
 `list_email_batch_recipients` returns each row's `columns` (the merged space),
@@ -1095,8 +1142,13 @@ null when it can. `patch_email_batch_recipient` edits cells: the edit is stored
 apart from what the model wrote, merged last, and an empty value clears it. That
 is the answer to a row whose task returned `null` for the address — type one in.
 
-`retry_email_batch_recipients` re-drafts rows whose drafting failed, and is the
-one action that revives a batch that already finished drafting.
+`redraft_email_batch_recipients` writes rows again from scratch and is the one
+action that revives a batch that already finished drafting. Its `selection` is
+`failed` (drafting failed), `stale_version` (an older published version of the
+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.
 
 **One address is mailed at most once per batch**, enforced when the row is
 claimed for sending: the second row settles `skipped` with
@@ -1105,12 +1157,18 @@ ours — Resend keeps one and auto-suppresses hard bounces and complaints.
 
 ### Watching it
 
-`get_email_batch` carries live counts, `failure_reason`, `next_draft_at` (which
-is how "waiting for Monday" is told apart from "stuck") 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) or the first account-level send failure (a revoked key, an unverified
-domain) — because those will fail identically for every remaining row.
+`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
+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.
 
 ## Knowledge bases
 

package/package.json

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

@@ -297,7 +297,7 @@
       "role": "write"
     },
     {
-      "description": "Fetch one task's config and how its last run went.",
+      "description": "Fetch one task's draft config, published version, history and last run.",
       "method": "GET",
       "name": "get_task",
       "parameters": {
@@ -311,7 +311,7 @@
       "role": "read"
     },
     {
-      "description": "Replace a task's config.",
+      "description": "Replace the task's draft config with the one supplied.",
       "method": "PATCH",
       "name": "update_task",
       "parameters": {
@@ -325,7 +325,7 @@
       "role": "write"
     },
     {
-      "description": "Delete a task. Its run history survives, still named after it.",
+      "description": "Delete a task and its published versions. Its runs survive, still named after it.",
       "method": "DELETE",
       "name": "delete_task",
       "parameters": {
@@ -338,6 +338,62 @@
       "read_only": false,
       "role": "write"
     },
+    {
+      "description": "Run publish-grade validation on the draft without publishing it.",
+      "method": "POST",
+      "name": "validate_task",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('validate_task').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/tasks/{task_id}/validate",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Freeze the current draft as a new immutable version and make it live.",
+      "method": "POST",
+      "name": "publish_task",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('publish_task').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/tasks/{task_id}/publish",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Fetch what one published version of a task actually contains.",
+      "method": "GET",
+      "name": "get_task_version",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('get_task_version').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/tasks/{task_id}/versions/{version}",
+      "read_only": true,
+      "role": "read"
+    },
+    {
+      "description": "Put an earlier published version of a task back into production.",
+      "method": "POST",
+      "name": "rollback_task_version",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('rollback_task_version').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/tasks/{task_id}/versions/{version}/rollback",
+      "read_only": false,
+      "role": "write"
+    },
     {
       "description": "Run the task once with the variables you supply, and wait for the result.",
       "method": "POST",
@@ -1137,7 +1193,7 @@
       "role": "write"
     },
     {
-      "description": "Stop drafting for good. This is the only terminal action \u2014 a batch cannot be deleted, because it is the record of what was sent to whom.",
+      "description": "Stop drafting for good. A batch cannot be deleted, because it is the record of what was sent to whom.",
       "method": "POST",
       "name": "cancel_email_batch",
       "parameters": {
@@ -1179,58 +1235,142 @@
       "role": "write"
     },
     {
-      "description": "Send the rows you name. **This mails real people and cannot be undone.**",
+      "description": "Take drafted rows out of consideration. Reversible with `restore`.",
       "method": "POST",
-      "name": "send_email_batch_recipients",
+      "name": "skip_email_batch_recipients",
       "parameters": {
         "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('send_email_batch_recipients').",
+        "description": "Arguments not inlined: call describe_function('skip_email_batch_recipients').",
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/email/batches/{batch_id}/send",
+      "path": "/v1/email/batches/{batch_id}/skip",
       "read_only": false,
       "role": "write"
     },
     {
-      "description": "Take drafted rows out of consideration. Reversible with `restore`.",
+      "description": "Put skipped rows back. `selection: \"all_eligible\"` means every skipped row.",
       "method": "POST",
-      "name": "skip_email_batch_recipients",
+      "name": "restore_email_batch_recipients",
       "parameters": {
         "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('skip_email_batch_recipients').",
+        "description": "Arguments not inlined: call describe_function('restore_email_batch_recipients').",
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/email/batches/{batch_id}/skip",
+      "path": "/v1/email/batches/{batch_id}/restore",
       "read_only": false,
       "role": "write"
     },
     {
-      "description": "Put skipped rows back. `selection: \"all_eligible\"` means every skipped row.",
+      "description": "Draft rows again from scratch. **Each one runs the task and is billed again.**",
       "method": "POST",
-      "name": "restore_email_batch_recipients",
+      "name": "redraft_email_batch_recipients",
       "parameters": {
         "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('restore_email_batch_recipients').",
+        "description": "Arguments not inlined: call describe_function('redraft_email_batch_recipients').",
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/email/batches/{batch_id}/restore",
+      "path": "/v1/email/batches/{batch_id}/redraft",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Send these rows. **This mails real people and cannot be undone.**",
+      "method": "POST",
+      "name": "create_email_send",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('create_email_send').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/email/batches/{batch_id}/sends",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Every send on this batch, newest first, with its counts and its schedule.",
+      "method": "GET",
+      "name": "list_email_sends",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('list_email_sends').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/email/batches/{batch_id}/sends",
+      "read_only": true,
+      "role": "read"
+    },
+    {
+      "description": "One send: where its rows are, and when it next does something.",
+      "method": "GET",
+      "name": "get_email_send",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('get_email_send').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/email/batches/{batch_id}/sends/{send_id}",
+      "read_only": true,
+      "role": "read"
+    },
+    {
+      "description": "Re-steer one send: its pace, its hours, its daily cap, its start time.",
+      "method": "PATCH",
+      "name": "patch_email_send",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('patch_email_send').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/email/batches/{batch_id}/sends/{send_id}",
+      "read_only": false,
+      "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.",
+      "method": "POST",
+      "name": "pause_email_send",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('pause_email_send').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/email/batches/{batch_id}/sends/{send_id}/pause",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Undo a pause and carry on from where it stopped.",
+      "method": "POST",
+      "name": "resume_email_send",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('resume_email_send').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/email/batches/{batch_id}/sends/{send_id}/resume",
       "read_only": false,
       "role": "write"
     },
     {
-      "description": "Draft rows whose first attempt failed, again.",
+      "description": "Stop this send, and give every row it has not sent back as a draft.",
       "method": "POST",
-      "name": "retry_email_batch_recipients",
+      "name": "cancel_email_send",
       "parameters": {
         "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('retry_email_batch_recipients').",
+        "description": "Arguments not inlined: call describe_function('cancel_email_send').",
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/email/batches/{batch_id}/retry",
+      "path": "/v1/email/batches/{batch_id}/sends/{send_id}/cancel",
       "read_only": false,
       "role": "write"
     },