io.github.Harflow-Dev/harflow-mcp

Wait for a task to finish, giving up after a timeout without disturbing the run. Args: task_id: Identifier of the task to await. timeout_seconds: How long to hold, 0..3600 (default 50; 0 observes once without sleeping). Honoured as asked, never silently clamped; out of range is INVALID_PARAMS. Breaking change: values above 3600 are now rejected (0 is newly accepted). Your MCP client applies its own request deadline, and exceeding it fails the *call* even though the task keeps running — see docs/multi-task-waiting.md before asking for long holds. include_tail: If True, include the full last_output_tail (20 lines × 2000 chars each); if False (default), the tail is omitted for running/completed tasks and shortened to 5 lines × 500 chars for failed tasks. detail: "compact" (default) omits static execution metadata and detailed outcome probes; "full" returns complete MCP status. Both preserve the complete summary/report, approval attention, failure diagnostics and wait fields. include_tail=True retains the full tail in either mode. until: "timeout" (default) returns when the task settles or timeout_seconds elapses. "terminal" holds until the task settles, bounded only by a 6 hour server ceiling; timeout_seconds must then be omitted (passing both is INVALID_PARAMS). ctx: Injected by the server; not a caller argument. The result is the task status plus `requested_timeout_seconds`, `effective_timeout_seconds`, `until`, `timed_out`, `stop_reason` (terminal, attention, timeout, ceiling or observation_unavailable), `elapsed_seconds` and `polling_guidance`. If the task is still going when the wait ends, the status is "running" with a `next_step` hint: call this again, or poll get_task_status. The dispatched process is never signalled, written or resumed by a wait, so waiting is always safe and repeating it costs nothing. For a task recovered from an earlier server…

Observe 1..32 unique task IDs, returning compact statuses in requested order. mode any returns when at least one requested task is settled; all waits for every task. timeout_seconds accepts 0..3600 (default 30) and is honoured as asked, never silently clamped; out of range is INVALID_PARAMS. Zero polls immediately. until="terminal" holds until the mode is satisfied, bounded by a 6 hour server ceiling, and requires timeout_seconds to be omitted. Your MCP client's own request deadline still applies. Prefer holds <=50 seconds after remote "device did not respond" or "connection closed" errors; see docs/multi-task-waiting.md. All IDs must exist and pass caller read authorization before waiting. Existence checks and initial metadata share a two-second I/O budget; undecidable existence rejects the request. A final metadata observation can add up to two more seconds. Returns terminal_task_ids, bounded summaries and get_task_status diagnostic references; no output tails. A recovered task whose process is confirmed gone without an observed exit is listed in undecidable_task_ids (status unknown) and counts as settled in both modes, as in wait_for_task, after a short grace if its owning harflow_mcp server is still alive; an uncertain identity keeps waiting. Under until="terminal", targets that stay unobservable for 3 rounds stop the wait with stop_reason observation_unavailable. Rows carry a bounded failure_diagnostic (category, reason) when one exists. Also returns requested/effective timeout, until, timed_out, stop_reason, elapsed_seconds and polling_guidance. Progress is sent every 5 seconds. Timeout and caller cancellation never cancel or signal the observed tasks.

Wait for a workflow run to need attention or finish; read-only and resumable. timeout_seconds accepts 0..3600 (default 30; 0 reads once). It is honoured as asked, never silently clamped; out of range is INVALID_PARAMS. Breaking change: values above 300 used to be rejected, and 46..300 were silently held for only 45 seconds. until="terminal" holds until the run stops needing the wait, bounded by a 6 hour server ceiling, and requires timeout_seconds to be omitted. Your MCP client's own request deadline still applies. Prefer holds <=50 seconds after remote "device did not respond" or "connection closed" errors; see docs/multi-task-waiting.md. Returns when the run is completed, failed or cancelled and has finished settling (stop_reason terminal), or reaches needs_input, needs_attention or paused (stop_reason attention), or the hold ends (timeout, ceiling). If reading the run keeps failing for 3 rounds the last good snapshot comes back with stop_reason observation_unavailable, as does an until="terminal" wait on a terminal run that stays settling with its run file unchanged for 300 seconds. Also returns requested/effective timeout, until, timed_out, elapsed_seconds and polling_guidance. Approval read errors alone do not stop the wait for attention; inspect approval_summary.read_errors for incomplete sources. Known unanswered requests and uncertain approval ownership still stop for attention. Progress is sent every 5 seconds, best effort. A wait never changes, resumes or cancels a run.

Generate a workflow, or refine the current canvas into an unsaved validated proposal. Orchestrator instructions belong in orchestrator.instructions; Start/End are structural. Optional on_demand_nodes are a separate ordered list with globally unique local id, title, required nonempty instructions, optional call_condition (When to call guidance), agent, freedom, network, session_mode agent_decides|fresh|resume and execution_mode. They have no position, role or connections. max_on_demand_calls defaults to 5 (1–50) per routing/question checkpoint; no per-node or per-run call cap exists. Write prompt in plain prose: preserve spaces and word boundaries rather than concatenating words to save tokens. The caller's prompt is retained unchanged before builder input assembly. Keep node and connection instructions concise and task-specific. HarflowMCP owns runtime retries, budget enforcement, configured fallback dispatch and user interaction; use existing configuration fields for limits and fallback candidates, and orchestrator needs_input for clarification or approval. End means intentional workflow termination, not waiting for user input. Preserve legitimate task branches and revision loops. Layout uses top-left logical point coordinates with x/y >= 0 and a 10-point dot grid. Agent nodes are 200 x 92 points (reserve 20 x 10 grid cells); Start/End are 72 x 72 (reserve 8 x 8 cells). Leave at least 40 points (4 cells) between node edges and avoid overlaps. Arrange forward steps left to right and parallel branches on separate rows. Use routing_mode="explicit". Ordinary outgoing paths are exclusive alternatives. Parallel execution requires paired parallel_start/parallel_end structural nodes with a shared parallel_group_id; every branch must reach its matching end. Parallel start defaults to `branch_selection: "all"`. With `branch_selection: "orchestrator"`, the orchestrator selects applicable issued branch continuations, assigns each selected entry through `branch_assignments…

Provider usage-limit hits and blocking recoveries of workflow runs, from persisted run evidence. Read-only: nothing is retried, switched or continued. Evidence is only an attempt's failure_diagnostic with category usage_limit (headless and Codex-native attempts alike) and the run's orchestrator or worker usage-limit recovery checkpoint; node results and prose are never read. Direct callers read every run; a workflow orchestrator reads its own run and descendants verified through persisted invocation links; workers and builders are refused. current lists runs blocked on a usage-limit recovery (at most 100), reported on the owning run even while its root is running. latest is the newest hit per (backend, requested_model, observed_model) among the newest 500 hits matching the window bound: the first of root_workflow_run_id (not supported for managed callers), workflow_id and repo that is set, plus the since (inclusive) and before (exclusive) ISO8601 range with timezone; the other filters apply inside that window and there is no pagination. At most 50 keys are returned. current_only reports only current. Each hit carries root_workflow_run_id, workflow_run_id, node_id, execution_id, attempt, task_id, transport_task_id, observed_at (when the attempt settled; observed_at_source names the field), diagnostic, reset {raw, at, state} (a numeric reset is epoch seconds; elapsed does not say the provider is available again), an accepted recovery {accepted, answer} when one answered it, and detail_ref, the get_workflow_run_detail arguments for execution:<id>. Each attempt is its own hit: native children that share a transport report it in transport_task_id. unavailable lists up to 20 runs whose document could not be read. scan.complete is false when a cap was reached, runs are unavailable or the index is still preparing (index_state), so retry while it is preparing. See docs/usage-limits.md.