Timeout

Set deadlines for HITL responses so workflows don't wait indefinitely.

HITL timeouts set a deadline for human responses. When the timeout expires, the workflow auto-resolves the pending requirement based on the on_timeout policy.

1from kern.workflow import Workflow
2from kern.workflow.step import Step
3from kern.workflow.types import OnTimeout
4from kern.db.sqlite import SqliteDb
5
6workflow = Workflow(
7    name="timeout_workflow",
8    db=SqliteDb(db_file="workflow.db"),
9    steps=[
10        Step(
11            name="draft_email",
12            agent=draft_agent,
13            requires_output_review=True,
14            output_review_message="Review the draft (auto-approves in 5 minutes)",
15            hitl_timeout=300,
16            on_timeout=OnTimeout.approve,
17        ),
18        Step(name="send_email", agent=send_agent),
19    ],
20)

Timeout is checked at continue_run() time. There is no background timer. If the timeout has elapsed when continue_run() is called, the requirement is auto-resolved.

Parameters

Parameter	Type	Default	Description
`hitl_timeout`	`int`	`None`	Seconds before auto-resolving. `None` = no timeout
`on_timeout`	`OnTimeout`	`None`	Action when timeout expires

OnTimeout Options

Value	Behavior
`OnTimeout.approve`	Auto-confirm the output
`OnTimeout.skip`	Skip the step
`OnTimeout.cancel`	Cancel the workflow

Timeout Flow

1run_output = workflow.run("Draft an email about the team lunch")
2
3if run_output.is_paused:
4    for req in run_output.steps_requiring_output_review:
5        print(f"Draft: {req.step_output.content}")
6        print(f"Timeout at: {req.timeout_at}")
7        print(f"On timeout: {req.on_timeout}")
8
9    # If called after timeout expires, auto-resolves based on on_timeout
10    run_output = workflow.continue_run(run_output)

The timeout_at datetime is available on the StepRequirement for frontend countdown display.

With Output Review

Timeout is most useful with output review. If a reviewer doesn't respond in time, the workflow proceeds automatically.

1Step(
2    name="generate_report",
3    agent=report_agent,
4    requires_output_review=True,
5    output_review_message="Review the report",
6    hitl_timeout=600,           # 10 minutes
7    on_timeout=OnTimeout.approve,  # Auto-approve after 10 minutes
8)

With Confirmation

Timeout also works with pre-execution confirmation:

1Step(
2    name="deploy",
3    agent=deploy_agent,
4    requires_confirmation=True,
5    confirmation_message="Deploy to production?",
6    hitl_timeout=120,            # 2 minutes
7    on_timeout=OnTimeout.cancel,  # Cancel if no response
8)

Choosing an OnTimeout Policy

Policy	Use When
`approve`	Output is low-risk and delays are costly. The step's output is likely acceptable
`skip`	The step is optional. Skipping doesn't break the workflow
`cancel`	The step is critical. Proceeding without review is unacceptable