Skip to content

Add <Time> to measure an executable region #791

Description

@taras

Story

As an executable-document author, I want to measure how long a region takes, so
the document can report completed durations without implementing its own clock
logic.

Example

<Time as="elapsed">
  <Prompt as="draft">
    Create an XMD program.
  </Prompt>
</Time>

The Agent completed its response in {elapsed} milliseconds.

as has its ordinary meaning: it binds the duration and suppresses <Time>'s
output. Without as, <Time> emits the duration where it is written.

Current gap

Executable documents can bound work with <Timeout>, but have no component that
measures completed work. xmd plan announces that an Agent turn is starting,
then cannot report how long it took when the turn finishes.

The Agent provider already produces live events, but this issue does not expose
or stream them. Measurement is based on the complete timed region.

Contract

<Time> is a paired component that expands its body once and returns the
elapsed duration in milliseconds as a finite, non-negative number.

Measurement begins immediately before the body starts and ends only after its
structured work and cleanup complete. If the body fails or is cancelled, that
outcome propagates normally and no successful duration is produced.

A completed measurement replays with the same duration and does not consult the
clock again. An interrupted measurement that never committed a duration has no
completed value to restore.

<Time> does not alter the body's authority, failure handling, output rules, or
lifetime. It introduces no deadline and never cancels work; <Timeout> remains
the component for bounding execution.

Acceptance

  • A successful paired <Time> executes its body once and returns a finite,
    non-negative millisecond duration.
  • With as, the duration is bound and <Time> emits nothing. Without as, the
    same value is emitted through ordinary component output.
  • A controlled clock proves that advancing time while the body runs changes the
    returned duration by the same amount.
  • Body failure and cancellation propagate, structured cleanup completes, and no
    successful duration is returned.
  • A completed durable replay restores the original duration without executing
    the body or reading the clock again.
  • A negative control proves <Time> does not impose a deadline or cancel a slow
    body.
  • Syntax documentation describes <Time> independently from <Timeout> and
    distinguishes measurement from enforcement.
  • The packaged Plan workflow wraps every Agent <Prompt> turn in <Time>.
    xmd plan --verbose reports the formatted completed duration through
    <PlanProgress> after the turn settles.
  • Plan timing appears only on stderr. It never enters the approved Plan source,
    an embedded <Plan> result, or stdout.
  • Plan does not stream draft text, counters, thought, tool, or status events as
    part of this issue.

Dependencies and scope

#788 may establish shared duration parsing or clock conventions, but <Time>
does not depend on timeout enforcement.

The active #762 implementation remains unchanged. Its Plan loop may continue to
announce Prompt phases, but it does not add <Time>, elapsed-time bookkeeping,
or Prompt streaming. Plan.md adopts timing when this issue is delivered.

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