Skip to content

Add <Timeout> to bound an executable document region #788

Description

@taras

Story

As an XMD author, I want to put a time limit around a document region, so one
slow or stuck operation cannot hold the rest of the workflow indefinitely.

<Timeout duration="10s">
  <Glob include={["**/*.md"]} as="files" />
</Timeout>

When the body completes within ten seconds, it behaves like the same body
without <Timeout>. When the limit expires, the body is cancelled and its
resources finish cleanup before the timeout failure reaches the enclosing
document.

Current gap

Individual surfaces such as executable code blocks, Agent prompts, and Fetch
have their own timeout options, but an author cannot apply one deadline to an
arbitrary composed XMD region. Adding a one-off deadline to xmd plan would not
provide that general document capability.

Contract

  • <Timeout> is structural middleware: it bounds the complete execution and
    teardown of its body.
  • duration uses the shared XMD duration grammar. A missing, zero, negative, or
    malformed duration refuses before the body begins.
  • Expiry cancels the whole body, waits for its structured cleanup, and then
    emerges as a typed execution failure. It does not return a successful partial
    result.
  • Output produced before failure follows the ordinary failed-region output
    rules; <Timeout> does not introduce a separate truncation or rollback model.
  • Outer cancellation remains cancellation rather than being reported as expiry,
    and cleanup failure is not hidden by the timeout failure.
  • Nested time limits compose: the first enclosing deadline to expire cancels the
    work once, with one cleanup sequence.
  • Continuation does not rerun effects that already settled or wait out a
    historical completed deadline.
  • The component supplies no retry or fallback behavior. Authors compose those
    policies separately.

Acceptance

  • A body that settles before its duration has the same output, bindings, and
    effects as an unwrapped body.
  • A body that exceeds its duration is cancelled, and a lifecycle probe shows
    cleanup completes before surrounding work can continue or observe the failure.
  • Invalid durations execute no body effects.
  • Tests distinguish expiry, outer cancellation, body failure, and cleanup
    failure, including nested deadlines.
  • Replay and continuation tests prove completed effects are not repeated and a
    retained outcome does not wait for the elapsed wall-clock interval again.

Relationship to Plan

#762 intentionally ships without a per-information-request deadline. If
unbounded information requests become a practical problem, this reusable
component can be prioritized and composed around the request.

Activity

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

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions