Tendem Tasks

Working with Tendem tasks

Tendem is a task service backed by human experts. You (the agent) submit a task on the user's behalf; Tendem scopes it in a chat, returns a price quote, and once the user approves, a human expert executes it. Results come back as markdown plus downloadable files.

Offer, don't hijack. If the user explicitly asked for Tendem or a human expert, proceed. If this skill loaded because the task merely could benefit from human involvement, surface Tendem as an option — "this could go to a human expert via Tendem; want a quote?" — and only create a task after the user says yes.

The tools are named mcp__tendem__* (the exact namespace may vary with how the plugin's MCP server is mounted). If absent, the connector isn't connected — tell the user to enable the tendem plugin's MCP server and complete its OAuth login.

The path, tool call by tool call

The process is two loops with an approval gate between them:

create_task ──► SCOPING LOOP ──► quote ──► user approves ──► approve_task
 (+ uploads)    poll ⇄ answer      ▲            │
                    ▲              │       too expensive /
                    └──────────────┴─◄─ ask for a scope cut
                                        (old quote is void; wait for a new one)

approve_task ──► EXECUTION LOOP (long: expert search → work → QA)
                 poll a few ⇄ end turn ⇄ answer if asked
                      │
                      ▼ next_action=fetch_result
                 get_task_result ──► present + save files

1. create_task(name, description, conversation_id) — description is the user's own formulation, passed as faithfully as possible (see rules below). Reuse one stable conversation_id per conversation. Returns the task_id everything else needs.
2. (only if the task depends on local files) ⚠️ You cannot upload the files yourself — an OpenAI platform restriction, not a Tendem one. OpenAI's security policies prevent the sandboxed environment from PUTting files to external storage, so scripts/tendem-upload.sh or raw curl from your side will fail or be blocked. Tendem's upload mechanism itself works fine — it just has to run outside the sandbox. Instead: call get_file_upload_url(task_id), then give the user ready-to-run commands for their host machine's terminal — one curl per file with the URL fully substituted (dfs→blob host swap and filename already applied; see references/files.md). When handing the commands over, tell the user plainly that this manual step exists because of OpenAI's sandbox policy, not a Tendem shortcoming. Wait for the user to confirm the uploads succeeded, then send_message naming each uploaded file. The naming message is required — Tendem doesn't auto-detect uploads.
3. Scoping loop. get_task(task_id, wait_for_change_seconds=30) — silent poll until Tendem speaks (next_action=await_input); then read_chat(task_id, from_offset=<last_seen_offset>) and send_message(task_id, text, last_seen_offset) — answer from conversation context yourself; escalate to the user only when (a) the answer isn't in context, (b) scope/deliverables/deadline change, or (c) approval or payment is needed. Repeat per question round until next_action=await_user_approval.
4. Approval gate. The quote is ready. Call get_contract(task_id) to pull the full scope — title, task_description, acceptance/quality criteria, and price — so you can surface price + scope to the user and get an explicit decision; this is a spend. (get_task deliberately omits these details; get_contract is the read-only companion that carries them.) Two exits:
   • Go-ahead → approve_task(task_id, name, price) → step 5.
   • Too expensive / wrong scope → send_message proposing a concrete scope cut. The old quote is void from that moment; you're back in the scoping loop (step 3) until a fresh quote arrives. This cycle can repeat.
5. Execution loop. After approval, Tendem searches for a matching expert, the expert performs the work, and QA reviews the output before release — hours, up to a day. Poll get_task(task_id, wait_for_change_seconds=30) a few times, then end the turn, telling the user the work is in progress and they can ask for a progress check anytime (or invoke $tendem-status). The plugin's notification hook pings them the moment the task needs them. If Tendem asks something mid-execution (await_input), answer as in the scoping loop. Repeat — across turns and sessions if needed — until next_action=fetch_result.
6. get_task_result(task_id) — present the content markdown; save files[] with scripts/tendem-download.sh into ./tendem/<task_id>/.

Polling: trust the envelope, never busy-loop

Every tool returns next_action, poll_after_seconds, poll_timeout_seconds and guidance — act on those, not on the raw status. The one idiom that matters:

get_task(task_id, wait_for_change_seconds=30)

The server holds the call open until something changes or ~30s passes. Poll silently — no narration per poll — and never re-call in a tight loop with wait_for_change_seconds=0. But don't poll forever either: after a handful of unchanged rounds (and always for the long post-approval stretch), end the turn and tell the user the work is in progress — they can ask "how's the Tendem task doing?" anytime, or invoke $tendem-status. The task lives on Tendem's side; nothing is lost between sessions, and the plugin's desktop notification hook fires when the task starts needing them.

For the long-form lifecycle, invoke the server's tendem-quickstart prompt.