Skip to content

feat(core): add experimental Hook token expiration#2865

Draft
NathanColosimo wants to merge 13 commits into
mainfrom
codex/hook-retention-core
Draft

feat(core): add experimental Hook token expiration#2865
NathanColosimo wants to merge 13 commits into
mainfrom
codex/hook-retention-core

Conversation

@NathanColosimo

@NathanColosimo NathanColosimo commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • add experimental_expires to createHook(), accepting the same duration strings, millisecond numbers, and absolute Dates as sleep()
  • store the absolute tokenReusableAfter time on hook_created and forward it through the Vercel event wire
  • keep active Hooks working even after the configured time; once the run ends, keep the token reserved only until it expires
  • make dispose() and using expire the token immediately, and exclude webhooks
  • document unsupported Worlds, timing limits, and that expiration does not cache workflow results

This PR defines and transports the portable contract only. It does not implement expiration in a World. A stacked follow-up adds the Local World implementation and integration coverage.

Closes part of #2376.

Verification

  • merged and conflict-resolved against origin/main at 48fcc4e
  • builds: @workflow/world, @workflow/core, and workflow
  • tests: 1,444 @workflow/core tests, 232 @workflow/world-vercel tests, and 8 combined @workflow/world event-schema tests
  • docs: 54 changed-page samples pass; 20 intentionally skipped samples remain skipped

Docs Preview

Page Preview
createHook() expiration Open
Hook token design Open
Run idempotency Open

@changeset-bot

changeset-bot Bot commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 7549626

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 20 packages
Name Type
@workflow/core Minor
@workflow/world Minor
@workflow/world-vercel Minor
@workflow/builders Patch
@workflow/cli Patch
@workflow/next Patch
@workflow/nitro Patch
@workflow/vitest Patch
@workflow/web-shared Patch
@workflow/web Patch
workflow Minor
@workflow/world-testing Patch
@workflow/world-local Patch
@workflow/world-postgres Patch
@workflow/astro Patch
@workflow/nest Patch
@workflow/nuxt Patch
@workflow/rollup Patch
@workflow/sveltekit Patch
@workflow/vite Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@vercel

vercel Bot commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
example-nextjs-workflow-turbopack Ready Ready Preview, Comment Jul 10, 2026 7:05pm
example-nextjs-workflow-webpack Ready Ready Preview, Comment Jul 10, 2026 7:05pm
example-workflow Ready Ready Preview, Comment Jul 10, 2026 7:05pm
workbench-astro-workflow Ready Ready Preview, Comment Jul 10, 2026 7:05pm
workbench-express-workflow Ready Ready Preview, Comment Jul 10, 2026 7:05pm
workbench-fastify-workflow Ready Ready Preview, Comment Jul 10, 2026 7:05pm
workbench-hono-workflow Ready Ready Preview, Comment Jul 10, 2026 7:05pm
workbench-nitro-workflow Ready Ready Preview, Comment Jul 10, 2026 7:05pm
workbench-nuxt-workflow Ready Ready Preview, Comment Jul 10, 2026 7:05pm
workbench-sveltekit-workflow Ready Ready Preview, Comment Jul 10, 2026 7:05pm
workbench-tanstack-start-workflow Ready Ready Preview, Comment Jul 10, 2026 7:05pm
workbench-vite-workflow Ready Ready Preview, Comment Jul 10, 2026 7:05pm
workflow-docs Ready Ready Preview, Comment, Open in v0 Jul 10, 2026 7:05pm
workflow-swc-playground Ready Ready Preview, Comment Jul 10, 2026 7:05pm
workflow-tarballs Ready Ready Preview, Comment Jul 10, 2026 7:05pm
workflow-web Ready Ready Preview, Comment Jul 10, 2026 7:05pm

@github-actions

github-actions Bot commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🧪 E2E Test Results

✅ All tests passed

Summary

Passed Failed Skipped Total
✅ ▲ Vercel Production 1453 0 230 1683
✅ 💻 Local Development 1617 0 219 1836
✅ 📦 Local Production 1617 0 219 1836
✅ 🐘 Local Postgres 1617 0 219 1836
✅ 🪟 Windows 153 0 0 153
✅ 📋 Other 894 0 177 1071
Total 7351 0 1064 8415

Details by Category

✅ ▲ Vercel Production
App Passed Failed Skipped
✅ astro 126 0 27
✅ example 126 0 27
✅ express 126 0 27
✅ fastify 126 0 27
✅ hono 126 0 27
✅ nextjs-turbopack 150 0 3
✅ nextjs-webpack 150 0 3
✅ nitro 126 0 27
✅ nuxt 126 0 27
✅ sveltekit 145 0 8
✅ vite 126 0 27
✅ 💻 Local Development
App Passed Failed Skipped
✅ astro-stable 128 0 25
✅ express-stable 128 0 25
✅ fastify-stable 128 0 25
✅ hono-stable 128 0 25
✅ nextjs-turbopack-canary 134 0 19
✅ nextjs-turbopack-stable 153 0 0
✅ nextjs-webpack-canary 134 0 19
✅ nextjs-webpack-stable 153 0 0
✅ nitro-stable 128 0 25
✅ nuxt-stable 128 0 25
✅ sveltekit-stable 147 0 6
✅ vite-stable 128 0 25
✅ 📦 Local Production
App Passed Failed Skipped
✅ astro-stable 128 0 25
✅ express-stable 128 0 25
✅ fastify-stable 128 0 25
✅ hono-stable 128 0 25
✅ nextjs-turbopack-canary 134 0 19
✅ nextjs-turbopack-stable 153 0 0
✅ nextjs-webpack-canary 134 0 19
✅ nextjs-webpack-stable 153 0 0
✅ nitro-stable 128 0 25
✅ nuxt-stable 128 0 25
✅ sveltekit-stable 147 0 6
✅ vite-stable 128 0 25
✅ 🐘 Local Postgres
App Passed Failed Skipped
✅ astro-stable 128 0 25
✅ express-stable 128 0 25
✅ fastify-stable 128 0 25
✅ hono-stable 128 0 25
✅ nextjs-turbopack-canary 134 0 19
✅ nextjs-turbopack-stable 153 0 0
✅ nextjs-webpack-canary 134 0 19
✅ nextjs-webpack-stable 153 0 0
✅ nitro-stable 128 0 25
✅ nuxt-stable 128 0 25
✅ sveltekit-stable 147 0 6
✅ vite-stable 128 0 25
✅ 🪟 Windows
App Passed Failed Skipped
✅ nextjs-turbopack 153 0 0
✅ 📋 Other
App Passed Failed Skipped
✅ e2e-local-dev-nest-stable 128 0 25
✅ e2e-local-dev-tanstack-start- 128 0 25
✅ e2e-local-postgres-nest-stable 128 0 25
✅ e2e-local-postgres-tanstack-start- 128 0 25
✅ e2e-local-prod-nest-stable 128 0 25
✅ e2e-local-prod-tanstack-start- 128 0 25
✅ e2e-vercel-prod-tanstack-start 126 0 27

📋 View full workflow run

@github-actions

github-actions Bot commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

📊 Workflow Benchmarks

commit 7549626 · Fri, 10 Jul 2026 19:21:05 GMT · run logs

Backend: vercel · app: nextjs-turbopack

Metric Scenario Avg (ms) P75 (ms) P90 (ms) P99 (ms) Samples
TTFS stream 1156 (-20%) 1668 🔴 1724 🔴 2167 🔴 30
TTFS hook + stream 1605 (±0%) 1951 🔴 2027 🔴 2167 🔴 30
STSO 1020 steps (1-20) 238 (-17%) 256 🔴 347 🔴 350 🔴 19
STSO 1020 steps (101-120) 388 (-7.4%) 392 🔴 508 🔴 620 🔴 19
STSO 1020 steps (1001-1020) 884 (-6.3%) 947 🔴 1194 🔴 1224 🔴 19
WO stream 1156 (-20%) 1668 1724 2167 30
WO hook + stream 1605 (±0%) 1951 2027 2167 30
SL stream 4321 (-13%) 5716 🔴 5802 🔴 6123 🔴 30
SL hook + stream 4948 (+2.1%) 5569 🔴 5689 🔴 5804 🔴 30
📜 Previous results (2)

bd33c10

Thu, 09 Jul 2026 23:37:25 GMT · run logs

vercel / nextjs-turbopack

Metric Scenario Avg (ms) P75 (ms) P90 (ms) P99 (ms) Samples
TTFS stream 1345 (+21%) 1588 🔴 1608 🔴 2139 🔴 30
TTFS hook + stream 1439 (+12%) 1784 🔴 1842 🔴 2069 🔴 30
STSO 1020 steps (1-20) 245 (-9.7%) 277 🔴 314 🔴 321 🔴 19
STSO 1020 steps (101-120) 399 (-3.0%) 454 🔴 501 🔴 515 🔴 19
STSO 1020 steps (1001-1020) 836 (-4.3%) 899 🔴 979 🔴 1002 🔴 19
WO stream 1345 (+21%) 1588 1608 2139 30
WO hook + stream 1439 (+12%) 1784 1842 2069 30
SL stream 4712 (+0.8%) 5007 🔴 5520 🔴 5781 🔴 30
SL hook + stream 4871 (-3.2%) 5424 🔴 5618 🔴 5740 🔴 30

87b6bd9

Thu, 09 Jul 2026 22:13:25 GMT · run logs

vercel / nextjs-turbopack

Metric Scenario Avg (ms) P75 (ms) P90 (ms) P99 (ms) Samples
TTFS stream 1262 (+26%) 1639 🔴 1661 🔴 2212 🔴 30
TTFS hook + stream 1557 (+24%) 1865 🔴 1929 🔴 3542 🔴 30
STSO 1020 steps (1-20) 292 (+22%) 344 🔴 387 🔴 443 🔴 19
STSO 1020 steps (101-120) 392 (-3.2%) 437 🔴 466 🔴 489 🔴 19
STSO 1020 steps (1001-1020) 850 (-18%) 868 🔴 1021 🔴 1104 🔴 19
WO stream 1262 (+26%) 1639 1661 2212 30
WO hook + stream 1557 (+24%) 1865 1929 3542 30
SL stream 4986 (+4.3%) 5576 🔴 5631 🔴 5838 🔴 30
SL hook + stream 4796 (-4.0%) 5397 🔴 5506 🔴 5985 🔴 30

Avg deltas compare against the most recent benchmark run on main at the time of this run.

Metrics — TTFS: time to first step body execution · STSO: step-to-step overhead (gap between consecutive step bodies) · WO: workflow overhead (time outside step bodies, client start → last step body exit) · SL: stream latency (first chunk write → visible to the reader)

Scenarios — stream: one step that streams chunks back to the client; no hooks, so the run stays in turbo mode · hook + stream: registers a hook before the same streaming step, which exits turbo mode · 1020 steps: 1020 trivial sequential steps; STSO is measured between consecutive steps in the given step ranges

🟢/🔴 mark percentiles within/above target. Targets (p75/p90/p99, ms) — TTFS 200/300/600 · SL 50/60/125 · STSO (1-20) 20/30/60 · STSO (101-120) 30/45/90 · STSO (1001-1020) 40/60/120

TTFS/WO compare client vs deployment clocks and SL compares the step runner’s clock vs the client’s (NTP-synced in CI). WO ends at the last step body exit, the closest observable proxy for the final step-completion request.

@NathanColosimo NathanColosimo mentioned this pull request Jul 9, 2026
Draft
@NathanColosimo NathanColosimo force-pushed the codex/hook-retention-core branch from 87b6bd9 to bd33c10 Compare July 9, 2026 23:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ijjk ijjk Awaiting requested review from ijjk ijjk will be requested when the pull request is marked ready for review ijjk is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@NathanColosimo