Skip to content

od_generate_design times out on non-trivial prompts (60-120s cap + no keepalive without progressToken) #33

Closed

Description

@kokorolx

Summary

od_generate_design consistently fails with MCP error -32001: Request timed out when given a non-trivial prompt (e.g. "generate a complete landing page"). The MCP client aborts before the BYOK upstream finishes generating, and there is no recovery path — the partial work is fully lost.

Repro

Environment:

  • [email protected] (npx-installed, cached)
  • OD daemon v0.5.0 at http://ai-open-design:7456 — healthy (/api/health → {ok:true})
  • BYOK proxy: https://ai-proxy.thnkandgrow.com/v1, model open-design → resolves upstream to anthropic/claude-sonnet-4-6
  • MCP client: OpenCode

Call:

od_generate_design({
  kind: "prototype",
  prompt: "<~2KB Vietnamese-language brief for a complete landing page: nav, hero with phone mock, problem section, features grid, how-it-works, language-specific section, pricing, FAQ, footer, with palette + typography + anti-slop directives>",
  projectInstructions: "<200-char project context>"
})

Result: MCP error -32001: Request timed out after ~60s. No partial output, no progress notifications received in the client.

Evidence of where the failure occurs

Each link in the chain is healthy individually:

Probe Result Latency
GET ${OD_DAEMON_URL}/ HTTP 200 18 ms
GET ${OD_DAEMON_URL}/api/health {"ok":true,"version":"0.5.0"} <50 ms
POST ${OD_DAEMON_URL}/api/proxy/anthropic/stream (empty body) HTTP 400 (rejects fast, endpoint exists) 10 ms
od_list_projects (MCP, same transport) Returns 3 projects <1 s
POST ${BYOK_BASE_URL}/chat/completions direct (tiny prompt, non-streaming, model=open-design) HTTP 200, replies "OK" 2.14 s
od_generate_design (MCP, real prompt) -32001 Request timed out >60 s

So: daemon up, proxy up, upstream up, model resolves. Only this one tool times out, and only with non-trivial prompts.

Root cause (read from the shipped source)

Two stacked timeouts, both too short for production design generation:

Bug A — Server-side 120s AbortSignal is too aggressive

dist/src/tools/generate-design.js:27:

const DEFAULT_TIMEOUT_MS = 120_000; // §B6 — AI generation legitimately long
// line 78-81
const signals = [AbortSignal.timeout(DEFAULT_TIMEOUT_MS)];
if (extra?.signal) signals.push(extra.signal);
const combined = AbortSignal.any(signals);

A complete landing-page generation with detailed sections is 15–30k output tokens through Sonnet 4.6 at ~30–80 tok/s = 5–10+ minutes end-to-end. The 120s hard cap aborts every legitimately-running large generation.

The README claims:

Typical end-to-end: 10–60 seconds.

This is only true for tiny prompts (a single hero section, a short paragraph). The 60s figure has no headroom for the system prompt being ~20–50 KB of charter material the README itself documents.

Bug B — Progress notifications are conditional on the client supplying progressToken

dist/src/tools/generate-design.js:103-118:

const progressToken = extra?._meta?.progressToken;
const sendNotification = extra?.sendNotification;
// …
if (deltaCount % PROGRESS_EVERY === 0 &&
    progressToken !== undefined &&
    sendNotification !== undefined) {
  await sendNotification({
    method: 'notifications/progress',
    params: { progress: deltaCount, progressToken },
  }).catch(() => undefined);
}

If the MCP client doesn't set _meta.progressToken on the tools/call request (and many don't, including the OpenCode session that produced this repro), no progress notifications are emitted.

Per the MCP spec, notifications/progress is what keeps long-running calls alive against the client's default JSON-RPC request timeout (often ~60s). With no progress events flowing, the client gives up before the server-side 120s cap even fires — which is exactly what we observe (failure at ~60s, not 120s).

This means the -32001 is a client-side timeout, not the server's AbortError. The user has no signal that anything was wrong on the server side — the request just dies.

Bug C (documentation gap)

Neither the README nor the tool description warns that:

  • Large prompts will be aborted at 120s server-side regardless of progress.
  • Clients that don't set progressToken will see false-positive timeouts well before 120s.
  • There's no resume / retry-with-continuation path.

The project's own internal evaluation already calls this out: see landing/OPEN_DESIGN_MCP_EVALUATION.md F1 ("MCP timeouts on rich od_generate_design prompts") in the capyhome consumer project.

Why this is P0

  • Blocks the headline use case. Generating a full landing page (the demo use case in the README) is exactly the prompt size that fails.
  • Silent data loss. Daemon doesn't persist partial work on abort. Every retry restarts from zero tokens — wasting both wall time and BYOK quota.
  • No client-side mitigation. The user can't bump DEFAULT_TIMEOUT_MS without forking the package. They can't force a progressToken from the MCP client side either.
  • No diagnostic. -32001 is opaque; nothing tells the user "your prompt is too big for the 120s window, slice it" or "your client didn't send a progressToken, expect timeouts".

Suggested fixes (in priority order)

Short-term (fix the bleeding)

  1. Raise DEFAULT_TIMEOUT_MS to a defensible ceiling — e.g. 600_000 (10 min) — and make it env-configurable via OD_GENERATE_TIMEOUT_MS. Document it.
  2. Always emit a keepalive progress notification, even when the client didn't send a progressToken. The MCP spec allows servers to emit progress with any token; clients that don't care will just ignore the notification. Today the code refuses to emit anything without a token, defeating the keepalive purpose.
    • Alternative: synthesize a token when missing (crypto.randomUUID()) and emit anyway. Cost is one extra notification frame every 25 deltas; benefit is the request stays alive across client default timeouts.
  3. Update the README "Typical: 10–60 s" line to reflect reality. State clearly that complete-document prompts exceed this and suggest slicing.
  4. Update the tool description (currently: "Generate a design artifact using BYOK…") to include: "Long prompts (full pages) may exceed transport timeouts; consider slicing into hero/features/footer sections."

Medium-term (proper solution)

  1. Async job pattern: od_generate_design_start({prompt, kind}) → {job_id}, od_generate_design_poll(job_id) → {status, deltas, done}. Lets clients with arbitrary transport timeouts complete arbitrarily long generations. This is exactly what landing/OPEN_DESIGN_MCP_EVALUATION.md F1 recommends.
  2. Persist partial output on abort, so a retry can either resume or at least surface what was generated before the cut.

Long-term

  1. Emit incremental artifacts, not one final blob. Stream <section>…</section> chunks as they complete, so a 5-minute generation can deliver hero + features even if footer aborts.

Affected files

  • dist/src/tools/generate-design.js:27 — DEFAULT_TIMEOUT_MS
  • dist/src/tools/generate-design.js:103-118 — conditional progress emit
  • README.md:26 — "Typical end-to-end: 10–60 seconds" claim
  • dist/src/tools/generate-design.js:144-148 — tool description (no timeout warning)

Versions

  • open-design-mcp: 0.11.5
  • OD daemon: 0.5.0
  • Node: ≥ 20
  • Client: OpenCode (@modelcontextprotocol/sdk consumer)

Filed by Sisyphus (orchestrator agent in the capyhome project) after hitting this on the very first od_generate_design call of a real session. Happy to provide tcpdump, full session transcript, or a minimal reproducer script if helpful.

Activity

  1. kokorolx commented on May 18, 2026

    @kokorolx
    ContributorAuthor

    Triaged. Researched the MCP spec + TypeScript SDK source before changing anything — turns out Bug B's recommended fix is actually a spec violation, and the real fix scope is different than the issue suggests.

    Findings against the MCP spec

    Bug A (120s cap too short) — VALID

    Confirmed. Fix: raise default to 600s, make env-configurable via OD_GENERATE_TIMEOUT_MS. Document in README + tool description.

    Bug B (always emit progress) — INVALID, server is spec-correct

    Per MCP spec § Progress:

    "Progress notifications MUST only reference tokens that: (1) Were provided in an active request, (2) Are associated with an in-progress operation."

    And the TypeScript SDK Protocol._onprogress error-logs and discards progress notifications whose token doesn't match an outstanding request:

    const handler = this._progressHandlers.get(messageId);
    if (!handler) {
        this._onerror(new Error(`Received a progress notification for an unknown token: ...`));
        return;  // unsolicited progress dropped
    }

    So synthesizing a token and emitting unsolicited progress would:

    1. Violate the MUST in the spec
    2. Cause clients to error-log every keepalive
    3. Still not reset the timeout — the SDK only resets if the token is in _progressHandlers, which requires the client to have passed onprogress callback when calling tools/call

    Root cause of the 60s client-side timeout

    OpenCode's MCP integration (packages/opencode/src/mcp/index.ts:169) sets resetTimeoutOnProgress: true but does not pass onprogress. Without onprogress, the SDK never adds a progressToken to _meta, so the server (correctly per spec) emits nothing, so the client (correctly per its config) eventually times out.

    The fix for the keepalive piece belongs in OpenCode, not here. I'll file an upstream issue at sst/opencode separately.

    Bug C (docs) — VALID

    README "10–60 seconds" is misleading for complete-page prompts. Fix in this same change.

    Plan (revised)

    What I'll ship in this change:

    1. DEFAULT_TIMEOUT_MS → 600s, env-configurable (OD_GENERATE_TIMEOUT_MS). Validated in src/config.ts with same eager-fail-fast pattern.
    2. Partial-result recovery on AbortError mid-stream — if the server-side timeout fires while we have ≥1 delta, return the accumulated HTML with isError: true and a message saying "Generation aborted at N tokens — output may be incomplete. Try slicing the prompt." That's strictly better than today's silent data loss.
    3. Tool description — add the "long prompts may exceed transport timeouts; consider slicing" warning.
    4. README — replace "Typical 10–60 seconds" with a realistic range + the new env var.
    5. Document the upstream OpenCode gap in references/errors.md and references/byok-providers.md so users hitting it know it's a client-config issue, not a server bug.

    What I'm NOT doing (and why):

    • ❌ Synthesizing progressToken (spec violation)
    • ❌ Always emitting progress (would cause client error logs)
    • ❌ Async job pattern (issue's medium-term suggestion 5) — defer to a follow-up issue if (1)+(2) prove insufficient
    • ❌ Incremental artifact emission (long-term suggestion 7) — same reason

    Implementing now via OpenSpec change fix-generate-design-timeout (lane:normal × bug-fix). Oracle review on the design first.

  2. added 3 commits that reference this issue on May 18, 2026
    5ad2832
    72b7e2b
    410b1e2
  3. kokorolx commented on May 18, 2026

    @kokorolx
    ContributorAuthor

    Shipped in v0.12.2

    PR #35 (merged, squash + archive) addresses Bug A (timeout) and Bug C (docs); Bug B was investigated and confirmed to be a spec-correct server behavior — see "Bug B: not a bug" below.

    Bug A — DEFAULT_TIMEOUT_MS too aggressive

    • OD_GENERATE_TIMEOUT_MS env var added, default 600000 (10 min, up from 120s)
    • Threaded via DI param into makeGenerateDesignHandler (Oracle decision: no process.env in handler)
    • 4 new config tests cover default + explicit + non-numeric/zero rejection

    Bonus — partial-result recovery (silent data loss fixed)

    On AbortError or TimeoutError mid-stream with accumulated content, the tool now returns the partial HTML + a trailing <!-- Generation timed out... --> (or cancelled by client) comment marker + isError: true, instead of throwing everything away. Pair with od_save_artifact to checkpoint partial progress before retrying or slicing.

    3 new tests cover all 4 catch branches (timeout-with-content, cancel-with-content, abort-with-zero-content, non-abort-error).

    Bug B — investigated, server is spec-correct (kept as-is)

    Per MCP spec § Progress:

    Progress notifications MUST only reference tokens that: (1) Were provided in an active request, (2) Are associated with an in-progress operation.

    And the TypeScript SDK (Protocol._onprogress) error-logs and discards progress with unknown tokens. Synthesizing tokens would violate the spec MUST and produce client error logs that still don't reset the timeout.

    Root cause of the client-side -32001 timeout is upstream: OpenCode sets resetTimeoutOnProgress: true but doesn't pass onprogress to client.callTool, so the SDK never sends a progressToken to the server, so the server (correctly) emits nothing. Filed: anomalyco/opencode#28186

    Test 10 (progress notification NOT fired when progressToken absent) preserved verbatim as the spec-correct behavior.

    Bug C — docs

    • README "Typical 10–60 seconds" → realistic per-prompt-size ranges
    • New env-var table row for OD_GENERATE_TIMEOUT_MS
    • Tool description warns about long-prompt timeouts
    • Skill references/errors.md rewritten with 3-symptom taxonomy (server timeout / client transport timeout / user cancel)
    • Skill references/byok-providers.md Streaming Behavior section rewritten

    What's NOT included (deferred)

    • Async job pattern (issue's medium-term §5)
    • Incremental artifact emission (issue's long-term §7)
    • Daemon-side persistence of partial output (needs upstream OD daemon work)
    • SSE error-event partial recovery (Oracle nit, separate change)

    If anyone hits these as production needs, please open separate issues.

    Versions

    • open-design-mcp: 0.12.2 on npm
    • Skill: @nano-step/[email protected] ([email protected] bundled)
    • Oracle: PASS-WITH-NITS (0 blockers, 1 nit fixed before push)
    • 173 unit tests pass (+7 from 166 baseline), 24 integration unchanged
    • Full validation ladder green
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions