@vercel/factory 0.0.14 → 0.0.16

package/CHANGELOG.md

@@ -0,0 +1,356 @@
+# @vercel/factory
+
+## 0.0.16
+
+### Patch Changes
+
+- 3951f20: Document persistence, dispatch, client-session, and storage-driver behavior at the public API, and
+  validate NodeNext, browser bundler, and optional storage declarations from strict clean consumers.
+  Classify stale sweep snapshots as changed Tasks and reject invalid Blob retry bounds.
+- 3951f20: Ship and verify runnable consumer recipes for authenticated Eve completion, typed workflow
+  results, human input and resumption, dependent agents, local execution, cancellation, hook-driven
+  retry recovery, and authenticated Task messaging. Add atomic state-and-execution fences for
+  provider-initiated workflow completion.
+- 512d109: Document existing Slack PR settings as covering all Factory-produced PRs, including human-requested work.
+- ad627a9: Allow factories to disable spending gates and budget alerts while retaining reservation, usage and settlement accounting. Disabled reconciliation reports spending with an explicit disabled status.
+- 5831134: Stream Git bundles in bounded binary chunks with digest verification instead of buffering base64 payloads. Keep trusted transfers open through stream consumption and initialize PR checkouts during the ref fetch.
+- 3951f20: Export TaskAttemptConflictError from @vercel/factory/tasks so consumers can identify stale-attempt
+  failures with instanceof and inspect the expected and actual attempts.
+- ff268af: Add repository-scoped Vercel-managed GitHub issue reads and initial Git Data/pull-request publication without exposing provider tokens.
+- 8cf7f91: Add optional provider-neutral workspace file browsing with a public client, immutable revisions,
+  complete text/image responses, and a configurable committed-Git reader.
+- 3951f20: Document persistence, dispatch, execution, and Eve recovery contracts in the public declarations,
+  harden exact-session Eve forwarding and bounded history reads, document Postgres migration
+  coordination, and ship a verified Postgres restart-recovery recipe.
+- 4bef24a: Add validated Slack PR notification defaults and durable workspace-scoped overrides with retry-safe settings commands. Preserve human provenance when investigations admit repair work.
+- b630985: Generate concise review summaries from the verdict and inline findings. Require findings for comment and request-changes reviews, support multiline GitHub review comments and suggested edits, and allow callers to suppress the separate finding-summary comment when findings are published inline.
+- 624ad28: Make Slack replies concise with temporary progress, direct chat links, PR cards, and useful completion summaries. Fix session completion parsing and distinguish normal planner continuations from failure retries.
+- ad627a9: Recognize Vercel Blob conditional-operation conflicts as version conflicts so concurrent session catalog writes reread the winning snapshot instead of failing dashboard requests. Preserve ETag fencing and the winning writer's data.
+- 8f3fde0: Let applications validate supported intake sources when operators retry stopped reviews.
+- b1b3f96: Add `POST /api/v1/repositories/:id/security-scan` and a matching `FactoryClient.runSecurityScan`, so an operator can start a deepsec scan without the CLI. The endpoint creates the same `security_scan` task `factory scan` does and returns the already-active scan for a repository instead of queueing a duplicate.
+- 3951f20: Document the operational contracts, defaults, failure semantics, and typed examples for the core
+  store, workflow, dispatch, Eve authentication, lifecycle hook, tool, and completion APIs. Compile
+  the examples against the built package and enforce their detailed API-reference coverage.
+- 4bc0c79: Fix active conversation messages and provider input replies failing with HTTP 500 because the Eve forwarding helper rejected the API's empty session-endpoint suffix.
+- b2ab6e5: Publish explicitly requested GitHub reviews and reliably report their completion to the original conversation, including Slack threads.
+- cc8c8f0: fix loading saved transcripts that contain timestamps
+- 21e375c: refresh stale active transcripts, stop snapshot reads at their durable boundary, and clear chat activity when turns end or their execution is unavailable.
+- 17a33c8: Keep issue signals pending when delegated Task admission fails, and expose the existing current-execution authorization check for application publication tools.
+- 710e542: Add explicit GitHub credential mode and replaceable Factory commit attribution to the configuration contract.
+- 828c4a8: Add authenticated, paginated PR discussion discovery and threaded replies so review follow-ups can find author feedback without comment IDs. Report published approvals explicitly in the original conversation.
+
+  Preserve comments and review verdicts when GitHub returns unavailable author or historical commit metadata, while rejecting missing authors for operations that require repository write access. Expose inline-comment account types so applications can distinguish human requests from bot activity.
+
+  Expose review ownership metadata and opt-in inline reply candidates. Bind delegation to its authenticated Signal attempt, and let applications validate supported intake retries so PR replies retain recoverable admission and human-request provenance.
+
+- 1a8935d: Bind change recording and completion replay to the authenticated Task execution and recorded pull request. Recheck publication associations and fence completion against replaced executions.
+- 3e13b63: Identify unresolved-turn questions from the exact completed Eve execution so application recovery can distinguish them from genuine requests for human input. Scope usage deduplication to each session so replacement attempts with repeated turn IDs update cost and progress.
+- e2180ee: Add optional provider-neutral session preview readers and a browser client for preview links, availability, expiry, and practical testing instructions.
+- 1d569c9: Add trusted Vercel-managed Git reads and signed publication with exact leases, authorization fencing, and reconciled commit identity.
+- ab01e5c: Add optional per-agent model catalogs, authorized repository defaults, and persisted model choices for sessions and Tasks.
+- 4677e3e: Add an idempotent GitHub repository label helper and reuse an existing open Task PR when retrying publication after a metadata failure.
+- 4bc0c79: Preserve exact question references and explicit same-factory TUI handoffs, and report missing associations without inventing session links.
+- 91fb6f0: Add an optional provider-neutral external activity reader and public client for operator inboxes, with validated repository scope, source links, evidence, and partial results.
+- 4bef24a: Make operator Slack DMs an explicit opt-in independent of authorization and PR announcements. Keep software task questions in their original conversation unless an additional notification destination is configured.
+- 6e02c7b: Preserve failed verification evidence and recover interrupted completion and result presentation from an immutable attempt-bound report. Recover saved outcomes before Eve lifecycle escalation or retry and before stall replacement. Admit fresh verifiers for authorized producer retries and fence obsolete results.
+- 1e855a9: Preserve producing Task associations when GitHub intake records a PR first, and support repository-scoped Slack PR notification preferences and configuration.
+
+  Continue explicitly linked PRs without replacing or inventing their original producing Task association.
+
+- c38fd24: Reject review check reuse and completion for a different commit so a requested review cannot report results against an older PR head.
+- 17a33c8: Accept opaque session pagination cursors in the shared client so session lists with multiple pages load correctly.
+- 5237246: Add an optional provider-neutral session review reader and browser client for recorded checks,
+  screenshots, and unresolved issues, with session access and execution identity checks.
+- 41e7db0: Ship version-matched consumer guides with the package, add a credential-free local Task
+  quickstart, and map common integration goals to their canonical imports and declarations.
+- 7294320: preserve transcript event timestamps for compact activity timing in operator clients
+- c107228: Update the supported Eve runtime to 0.57.0.
+- 245c3f7: Correct the local Task README example and verify in CI that its exact code compiles against the
+  built public package and completes its parent and worker Tasks at runtime.
+- d90e302: Clarify GitHub suggestion replacement ranges and full-file validation requirements in review tool
+  descriptions, with prose-only advice when validation is unavailable or fails.
+
+## 0.0.15
+
+### Patch Changes
+
+- 8d85ea1: Require actionable needs_human reasons, preserve legacy reads and public schema introspection, and recover question delivery and confirmation stamps across interruptions and retries.
+- 09e3fce: Make All work the default operator home page, open it in board view, and expose task graphs as a tab in task conversations.
+- 5c863bd: Prevent oversized receipt summaries from stranding completed tasks between lifecycle transitions.
+- 40aaba6: Expose authorized automatic Tasks as stable operator conversations. Support separately budgeted follow-up investigations after completion, linked specialist work, retained execution history and recovery context, and idempotent follow-up retries in the shared clients.
+- 70c487e: Bound abandoned review-check reconciliation by paging terminal Task candidates before reading their
+  code-review effect records, while rotating pages so older unresolved checks remain reachable.
+- e91d987: Configure repository-wide formatting with oxfmt.
+- edcc29d: Replace Task, Change, and session-discovery scans with fixed-shard catalogs, using durable pre-write repair markers so interrupted projections remain visible and heal on read. Reuse one Task snapshot throughout each dispatcher pass, batch pinned-session summaries, and cap overlapping Blob downloads. Avoid scanning all Receipts during browser/TUI polling and current execution checks. Report unexpected API failures with request context, distinguish read recovery from mutation retries, and preserve redacted server exception details in generated factories.
+- 9aabbc7: Classify missing execution output for workflow-owned retry policy and surface failed workflow work in conversation attention without replacing its agent execution.
+- d1548d6: Add a `closePullRequest` GitHub helper that closes an open pull request without merging it.
+- 54932f6: Record the check run a code review opens on its Task, and conclude that run when the review ends without a verdict. A cancelled, superseded, or failed review no longer leaves a check pending on the pull request, including the superseded case whose run sits on a head the pull request has already moved past.
+- d0d9bdd: Remove the obsolete `selectSlackRepository`, `selectSlackRepositories`, and `selectSlackPullRequest` exports from the Slack communication entry point. Slack repository and pull-request selection now belongs to conversational triage, and none of the deterministic text parsers had a remaining production caller.
+- e2ad1a2: Document every public Factory export with a source-level JSDoc summary and enforce complete export-summary coverage in the generated API reference.
+- 4a30ea3: Add validated execution contracts and workflow operations for confirmed-live reattachment, attempt-fenced result inspection and usage, and retryable cancellation. Fence dispatch execution binding and launch-failure recovery against replaced attempts, and surface failed execution binding instead of reporting acceptance.
+
+  Require adapters to identify ambiguous launch acceptance explicitly, stop launches that lose their Task binding, and record unresolved cost or cancellation discovery without preventing lifecycle transitions or treating unknown cost as zero.
+
+- a6c6707: Project retry, failure, cancellation, no-change success, and coordination receipts into the durable communication outbox through each task's original reply destination.
+- de1381e: Expose post-commit work notifications and planner turn-finished wakeups for durable event-driven scheduling. Prevent blocked dependencies from consuming dispatch capacity and preserve factory-wide budget checks when dispatching a single graph.
+- df54728: Expose read-only external conversations through stable session bindings, authorized discovery, original transcripts, and transcript-driven Inbox attention while preserving external reply destinations.
+
+  Store external projections in separate snapshot and discovery collections so older deployments sharing the store never decode the new session fields.
+
+- 44a42ee: Expose reusable repository admission, credential-redacted diagnostics, Eve Task/session and
+  transcript integration, GitHub intake, communication, App-token, and bounded publication helpers,
+  Vercel Queue and scoped Sandbox credential adapters, and an explicit software-development preset
+  over capability-owned operations. Add semantic Eve session bindings and lifecycle operations,
+  credential-injected GitHub checkout mechanics, explicit repository metadata admission, and
+  software-development preset recovery assembly. Concrete factories retain credential-source,
+  repository, routing, prompt, and workflow policy.
+- 70c487e: Expose retry-safe Vercel Sandbox execution and content-addressed Blob artifacts as optional
+  capabilities, with application-owned prompt, evidence, pricing, model, and seeding policy. Isolate
+  the supplied cross-capability Eve composition under
+  `@vercel/factory/presets/software-development`.
+- 47dab70: Add credential-injected GitHub publication clients and pull-request capability helpers for Task-
+  and session-owned pull requests, checkpoint recovery, record-change gating, and task-aware labels,
+  plus the code-review GitHub reporter. Expose DeepSec normalization and its Eve scanner together at
+  the canonical `/integrations/deepsec` provider path.
+- bf91d0e: Add filtered, cursor-paginated session summaries, materialize automatic interactions only for the requested page, and avoid redundant session and receipt reads during listing.
+- beb3995: Add a `find_existing_work` triage tool factory and the GitHub listing helper behind it, so Foreman can detect an open pull request or in-flight change already covering a signal before delegating duplicate work.
+- 54f9675: Keep pending human questions actionable when a conversation selects newer queued work. Resume the answered question's parent, prioritize its dispatch recovery, and keep cancellation scoped to the selected task's own question.
+- 3134944: Distinguish directly startable conversation agents from delegated specialists in the operator API and reject disallowed direct creation before durable writes.
+- 8d85ea1: Fix review follow-ups on the needs_human guarantees: normalize legacy needs_human tasks that predate `needsHumanAction` instead of failing to parse; persist the operator Slack DM intent atomically with the needs_human transition and deliver it from the outbox instead of enqueuing it afterward; retain the full `needsHumanAction` derived from question text and run a QuestionTask's own first transition inside its cleanup path so an oversized question can never orphan it; stop swallowing storage errors when stamping delivery so a failed stamp is retried; guard a parent's delivery stamp by question identity so a stale confirmation can't apply to a superseded question; and have the owner DM point to where an answer is actually accepted instead of accepting inline replies.
+- f1c5ddd: Strengthen public TypeScript construction contracts with typed workflow and message bindings, distinct constrained identifiers, exact agent routes, named operation inputs, readonly caller data, discriminated lifecycle and integration results, and inspectable source-relative declaration files. Bind credentialed review and human-input tools to the authenticated Task, attempt, execution, Change, repository, and pull-request comment scope, and allow one open human question per execution. Migrate every first-party caller to the clearer pre-1.0 API.
+- f5a0cba: Enforce the specialist turn contract and stop the stall watchdog from misreporting superseded work as a stall.
+
+  - `createFactoryHooks`'s `turn.completed` handler now escalates a bound task straight to `needs_human` when the turn finishes cleanly but nothing was recorded, instead of waiting out the stall window across every replacement attempt.
+  - `taskQuestionSchema` gains an optional `closingOptions` list: answering a question with one of these exact replies resolves the parent task instead of requeuing an identical retry.
+  - `record_post_review` resolves its own task as superseded when the pull request advanced past the reviewed head, instead of throwing and leaving the task running.
+  - `sweepCodeReviewStalls` reports a stalled `code_review` task as superseded when a newer, still-active review task already exists for the same change.
+
+- 426155d: Recover explicit Eve execution failures immediately and give each retry a fresh session identity.
+- 9aabbc7: Expose delegated workflow failures independently of pending questions and keep cancellation available after the conversation Task completes.
+- ad27bb3: Persist pre-task Foreman triage attempts and safe failure categories. Expose operator-authorized intake reads and fenced retries, with repository checks and no provider payload disclosure.
+- daa76e5: Keep GitHub credentials in fresh trusted transfer sandboxes, use read-only fetch tokens, and exchange bounded Git bundles with agent workspaces. Bind Task completion, verification, pull-request fetching, and merge-conflict resolution to the authenticated Task attempt and execution, and reject unrelated Change, Signal, or repository associations before provider access or mutation.
+- 7f9a661: Expose the durable Task state values through the browser-safe client for status-driven operator views.
+- eba7887: Drop the generic "Work completed" headline from successful Slack messages so they lead with the result, while keeping the "succeeded" → "Work completed" status-label mapping for other Slack views.
+- aeb708d: Stream live events for the exact task selected in the operator DAG after hydrating its saved transcript. Expose the main conversation's current task so clients can distinguish a waiting planner from its active child without changing the selected node implicitly.
+- ad27bb3: Allow the software-development preset to load through Next.js config require resolution.
+- 6ead1fd: Show reasoning by default in the reference web operator and automatically expand each reasoning block.
+- 18e0792: Add individually authorized approval APIs and migrate CLI queue and decisions off production storage credentials. Preserve immutable decision attribution across retries and concurrent requests, with a browser approval queue in the reference factory.
+
+  Support authorized approval search and priority/decision ordering before pagination, with matching counts for the browser review queue.
+
+  Retain the public `findingFingerprint` export while keeping browser schemas free of Node dependencies. Restore CLI queue guidance and use action-specific empty results. Document approval search scaling limits.
+
+- b424591: Add authorized, read-only operator task graph and exact-task transcript endpoints with browser-safe client methods for inspecting nested work from the Kanban board.
+- 0b8ff31: Replace ESLint with Oxlint for package linting.
+- c6f7c0f: Identify the verified actor in approval access denials so clients can explain per-user configuration mismatches.
+- c75a8f8: Compare the web Changes view's current branch HEAD with its pinned base SHA instead of the latest main workspace, and expose both comparison SHAs in workspace diff responses.
+- be558e8: Add authorized session search, repository, agent, source, status, and attention filters before pagination, with optional total counts and derived Inbox attention.
+- 2738d50: Add a browser-safe public HTTP client, session schemas, transcript projection, and reconnecting event stream shared by terminal and web clients. Include repository ID-to-slug details in operator discovery without changing the existing repository list.
+- a275061: Support durable, authenticated image attachments in operator conversations, including multimodal
+  Eve input, structured transcript replay, and attachment-aware admission and follow-up recovery.
+- 9aabbc7: Show and answer workflow-owned questions in their originating operator conversation without changing its agent execution. Conversation cancellation also cancels its delegated workflow work.
+
+  Normalize weak read ETags for conditional writes through the public Vercel Blob client, including execution ledgers and worker leases.
+
+  Preserve empty artifact uploads instead of letting the Blob SDK reject them as missing bodies.
+
+  Attribute conversational question answers to the current authenticated actor and require both current and original conversation bindings.
+
+- 9d6347f: Hide creation and follow-up recovery prompts while their requests are still in flight.
+- b1bbc63: Precompute and persist browser-safe transcript projections at durable Eve response boundaries. Serve completed conversations without replaying their event logs, rebuild legacy cache misses once, load earlier executions concurrently, publish snapshots atomically, and follow live events from the exact durable cursor. Include the response-boundary materializer in generated factories.
+- 44800ac: Expose authenticated workspace diff inspection through the operator API and shared browser client. Add the web conversation Changes tab and keep scaffold synchronization scoped to the reference operator adapter.
+- df233a8: Add a bounded recursive planner workflow with authenticated decisions, terminal-child handoffs, fresh execution attempts, replay recovery, and reconciled cancellation.
+- 1eb065b: Require every pull request to include a committed patch changeset for its changed publishable packages.
+- 3caecd2: Reset the concrete Factory deployment into a fresh Blob namespace.
+- 9aabbc7: Retain the current failed Task's exact transition receipt independently of communication delivery, and clear its reference when the Task leaves the failed state. Issue workflow notices can retrieve the committed reason directly after retries and delivery acknowledgment.
+- e56dbf5: Retry transient Vercel Blob failures (5xx, 429, network errors) with bounded backoff on both reads and writes, not only on version conflicts. `recordUsage` and `recordExecution` now retry the same transient failures too, bounded by attempts and elapsed time, so a Blob outage surfaces as a failure instead of silently starving a healthy running task.
+
+  Retrying a write is only safe if it can't be mistaken for a different writer's conflict: a transient failure can happen after the write actually lands (the response is what got lost), so the retry's own create-if-absent or ETag-precondition write then legitimately collides with its own prior success. `insert` and `update` now recognize that case — by reading the record back and comparing it to what this call tried to write — and treat it as success instead of surfacing a spurious `RecordExistsError` or `VersionConflictError` for a write that actually succeeded.
+
+- fc45434: Add a server-side top-level Task filter and show only Task entrypoints on the default Kanban board.
+- 1469b88: Index open questions by reply destination so connectors can persist answers from repository writers without scanning tasks.
+- d29c5b9: Reject repository traversal and reserved Git directory names while preserving safe punctuation in names such as `.github`. Cover whitespace, path separators, and dependency slug validation.
+- daa76e5: Replace the broad software namespace with capability-first entry points for changes, findings,
+  remediation, verification, code review, pull requests, merge resolution, multi-repository work,
+  triage, and delivery metrics. Keep supplied policy under the software-development preset, remove
+  the superseded paths and names, merge Eve tools into their owning capability paths and the package
+  root, require the Eve peer, make public barrels explicit, and enforce the package's naming and
+  single-owner export rules.
+- 70c487e: Move GitHub review-check state out of the generic Task schema into a namespaced task-effect store,
+  preserving write-once provider references and race-safe reconciliation stamps for supplied software
+  workflows without teaching the core Task lifecycle about GitHub. Separate durable communication and
+  stall mechanics from the supplied software presentation and review-supersession policies. Add
+  explicit delegation, completion, and dispatcher communication policy hooks. Publish supplied
+  software policies and stall results only through their canonical names and capability paths, while
+  making omitted approval neutral and requiring concrete software factories to select their supplied
+  policy explicitly.
+- 7d52404: Add native Slack proposal approvals, evidence views, and rejection-reason modals backed by shared operator checks and immutable receipts. Preserve originating scan threads, pass configured scanner approval policy, and reconcile decisions through the durable communication outbox.
+
+  Preserve rejection notices when decisions precede initial proposal delivery and stop notification retries for repositories outside the configured scope. Document hosted recovery assumptions, smoke tests, and reconciliation scaling limits.
+
+- f26201d: Retry transient Blob download failures with bounded backoff so temporary storage errors do not immediately fail session discovery and other snapshot reads.
+- a6895ca: Preserve structured tool inputs, outputs, errors, and execution state in the shared client transcript while retaining the text projection for terminal clients. Add shell-specific collapsed command and expanded output views in the reference web UI.
+- 6e37276: Move budgets, signals, receipts, Task approvals, entity identifiers, and server session contracts
+  from the package root to their canonical capability paths. Consolidate finding remediation into
+  `/findings`, change verification and multi-repository coordination into `/changes`, and merge
+  conflict resolution into `/pull-requests`.
+  Move GitHub, Slack, DeepSec, and Vercel provider APIs under their `/integrations/<provider>` entry
+  points.
+- 8356e75: Allow conversational agents to select a grounded single- or multi-repository subset authorized by a connector and ask for clarification when the complete set is not identified.
+- 4d0bc54: Replace the prototype Task model with required versioned work contracts, canonical dependency graphs, exact execution routes, and validated results. Add durable typed Task messages, leased processing, replayable decisions, and explicit recovery operations.
+
+  Update factory clients, agent tools, and generated scaffolds to the unified contracts. This is a breaking pre-release change: existing Task snapshots require an explicit migration or reset before deployment; no live data is changed automatically.
+
+- b5c4218: Wrap long lines in the web workspace diff viewer while keeping line numbers aligned with the first visual line.
+
+## 0.0.14
+
+### Patch Changes
+
+- 0577b0b: Allow executable Tasks to reference the Change they concern without making the Task kind define the association.
+- 2ca9c71: Bound Blob collection read concurrency and queued dispatch work so scheduled reconciliation completes predictably as the ledger grows.
+- e61a491: Add the public operator-session HTTP API and durable session bindings. Agent selection,
+  idempotent Signal admission, task dispatch, streaming proxies, human answers, and cancellation
+  preserve Factory lifecycle, ownership, and budget boundaries. Persist API notifications through
+  the store engine and expose the contracts through `@vercel/factory/api`.
+- 1ba6747: Let code-change tasks continue a canonical existing pull-request Change without opening a second pull request.
+- fbcb50b: Make Blob the production durability layer with immutable answer events, directly routed blocked-task answers, ETag-CAS task projections, and a sharded durable communication outbox.
+- d8fe5a3: Keep ledger inspection failures in the turn-completion hook from failing and replaying user-facing turns.
+- 0904927: Fail queued executable tasks with invalid recovery routing instead of silently retaining them, and surface eligible tasks that remain queued past the dispatch window in repository health.
+
+## 0.0.13
+
+### Patch Changes
+
+- 4cc5042: Budget reserve-before-execution and settlement. The store engine gains a `budgets` collection (one non-disableable budget per month, write-once warning and exhaustion notices) and `tasks.settle`. Dispatch reserves `budget.perTaskReservationUsd` in the same write that wins queued -> running and definitively fails tasks once the month's derived spend cannot fit another reservation. A per-minute sweep settles reserved terminal tasks at zero after ten minutes without measured usage, and budget notices deliver once per month to the Slack owner.
+
+  Enforcement is on by default: `factory.config.ts` gains a `budget` field defaulting to `{ totalUsd: 500, investigationUsd: 100, perTaskReservationUsd: 5, warningPercent: 80 }`. Once a month's spend crosses the cap, queued tasks fail permanently until an operator retries them in a later month; raise `budget.totalUsd` in `factory.config.ts` to lift the cap. `investigationUsd` and `perRepositoryUsd` are stored but not yet enforced.
+
+- f769cf6: Add application-owned agent route registries, registry-validated Foreman delegation, and bounded question/result presentation hooks.
+- d525870: Add stable finding identities and pull request conversation-comment helpers for deduplicated code review summaries.
+- f5b593f: Support factories without an independent verifier and report pull-request creation before any optional verification result.
+- d07755b: Allow Slack repository selection by unique short name or GitHub repository URL.
+- 44b1684: Measure task cost from real model usage. The factory hook now records each model step's tokens and AI Gateway cost on the session's task (`task.usage`, via `stores.tasks.recordUsage`, idempotent per turn and step), and the recorded total settles when the task ends, at turn end or by the settlement sweep, instead of always settling at zero. `factoryHooks` accepts an optional `taskIdAttribute` (default `factoryTaskId`).
+- 42e06f7: Render Slack communication events with readable spacing and safe clickable links.
+- 8367bab: Allow code review tools to report results through completion callbacks without publishing GitHub reviews.
+- 04a4f1f: Read task records written by deployments carrying execution progress metadata.
+- 7c6082c: Detect and replace stalled tasks. Tasks gain a `stalled` state, `lastProgressAt` (stamped at dispatch and by every recorded model step), and `execution: { provider, sessionId }` recorded through the new `stores.tasks.recordExecution` when a launcher returns it. `sweepStalled` marks a running task stalled once it passes its window without progress, re-queues it for a replacement attempt while `attempt < maxAttempts`, and fails it after; tasks whose result is already recorded are never retried. Limits come from a new `execution` block in `factory.config.ts` (`maxAttempts` 3, `stallMinutes` 45, `stallMinutesByKind` for long single-step work). The never-written `devbox` task field is removed in favour of `execution`.
+- 6772b0a: Compare pull requests from their merge base during verification to avoid false failures when the default branch advances.
+- dda8f5a: Make every human-blocked task produce a surfaced QuestionTask. The new `request_human_input` tool
+  covers both requested information and requested human action, compensates failed presentation
+  instead of leaving a silent wait, and the abandoned-turn hook creates the same surfaced recovery
+  question. Remove the overlapping `ask_question` and `report_blocked` agent tools from the framework
+  and generated factories. Mentioned Slack follow-ups carry persisted waiting QuestionTask ids into
+  Foreman's turn context so a reply can be attributed without relying on notification history.
+
+## 0.0.12
+
+### Patch Changes
+
+- 9be5e97: Create idempotent verification tasks for recorded code changes so workflow reconciliation, rather than the coding agent, owns mandatory verification dispatch.
+
+## 0.0.11
+
+### Patch Changes
+
+- 5ee2960: Create and reconcile multi-repository coordination parents with repository-scoped child tasks, and accept coordinated Slack requests in generated factories.
+- 67bb5ab: Pass dispatched tasks to agent handoff headers and scaffold task-scoped repository checkout.
+
+## 0.0.10
+
+### Patch Changes
+
+- 1ebb237: Require executable tasks to target exactly one repository and coordination tasks to scope at least two distinct repositories without executing directly.
+- 00aa4fe: Add composable GitHub check-run primitives with lifecycle state, rich output, annotations, correlation metadata, commit lookup, and a post-review composition hook.
+- 6060928: Add computeLedgerMetrics and computeRepositoryHealth: the product metrics (landed with a 7-day provisional hold, stick rate, human time per review bucket, cost per landed, filtered) and the green/yellow/red repository health roll-up, computed from ledger rows alone. The engine now writes a ready receipt when a change becomes ready so human time is measurable.
+- 1ebb237: Require changes to reference an existing repository and a matching code-change task.
+- f3b495a: Add public primitives for composing webhook-driven post-PR code review bots.
+
+## 0.0.9
+
+### Patch Changes
+
+- e4ca257: Move `buildFactory` out of the root entry into `@vercel/factory/next`. The root
+  entry could reach `eve/next` through `buildFactory`'s lazy import, so any Next.js
+  route importing the package root (the scaffold's cron dispatch route) pulled
+  eve's sandbox backends into the bundle and failed the deploy build with
+  unresolvable optional dependencies (`just-bash`, `microsandbox`). Local builds
+  never caught it because `link:` workspace dependencies are externalized. Import
+  `buildFactory` from `@vercel/factory/next` in `next.config.ts`; runtime imports
+  from the root are unchanged.
+
+## 0.0.8
+
+### Patch Changes
+
+- 082f99c: Document the FDK product contract and V1 runtime architecture.
+- 421ec26: Support communication events that concern multiple repositories.
+
+## 0.0.7
+
+### Patch Changes
+
+- c0ad80f: Publish @vercel/factory with public access on npm. Generated factories install
+  the package at deploy time, and build containers can only reach the public
+  registry; restricted access made every deploy outside the internal network fail
+  with a 404 on `npm install`.
+- a73a49f: Add Slack rendering and thread delivery for channel-neutral communication events.
+
+## 0.0.6
+
+### Patch Changes
+
+- 16b1d4d: Observe production deployments: a new @vercel/factory/vercel entrypoint verifies the x-vercel-signature header and normalizes deployment.succeeded and deployment.promoted webhooks, Changes record the merge commit sha when their pull request merges, and a production deployment built from that commit moves the Change from merged to deployed.
+- 3e58550: Remove the built-in factory web UI and its Next.js page exports.
+
+## 0.0.5
+
+### Patch Changes
+
+- 4739764: Fix serialized review-comment tool context, adopt external pull requests, and let agents suggest medium-confidence fixes or apply high-confidence fixes to an existing pull request.
+- 5cbdb3e: Add normalizeGitHubPullRequestClosed so a factory can observe merged and closed pull requests from the pull_request webhook and drive Change state with the merging or closing human recorded as decidedBy.
+- 948b40d: Add Slack signal normalization and repository selection for Vercel Connect and Eve Slack intake.
+
+## 0.0.4
+
+### Patch Changes
+
+- 9a83def: Add a provider-neutral webhook normalization contract and apply it to GitHub signals.
+- 984d5ac: Make the Blob-backed ledger and task dispatch reliable under real conditions:
+
+  - Blob driver reads the ledger uncached and guards updates with the object's
+    ETag, stripping the weak-validator (`W/`) prefix the read API returns so
+    conditional writes are accepted; a lost race now surfaces as a
+    `VersionConflictError` instead of silently overwriting or failing forever.
+  - `admitFinding` is idempotent when two overlapping scanner sessions record
+    the same finding: it matches the lost-race error by name (the Blob driver is
+    a separate entry point, so `instanceof` never matched across the bundle),
+    and treats an already-decided signal as a duplicate rather than throwing.
+  - A refused agent launch re-queues the task and retries (up to 45 sweeps)
+    instead of failing the task on the first refusal, so a freshly deployed
+    factory's first scan survives the platform's identity warm-up.
+
+- 115be76: Switch the package build from tsup to tsdown and publish its native ESM output extensions.
+- 40c04d7: Allow pull request fetch and review comment tools to operate while a change is ready for human review.
+
+## 0.0.3
+
+### Patch Changes
+
+- e85a696: Add ledger-bound Eve tools for reading and answering authorized GitHub review comments.
+- 52957b2: Add GitHub connector operations for pull requests, review comments, and labels.
+- 30e0df9: Add a channel-neutral communication event and adapter router for connector-owned delivery.
+- 000e41a: Add GitHub merge-conflict discovery and ledger-bound tools for safely updating factory pull requests.
+- 71ec154: Move the GitHub integration API from `@vercel/factory/connectors/github` to `@vercel/factory/github`.
+
+## 0.0.2
+
+### Patch Changes
+
+- 1d939f3: Add a package README with a concise framework overview.
+
+## 0.0.1
+
+### Patch Changes
+
+- fe5cc25: Build the package before packing it for publication.

package/README.md

@@ -8,5 +8,99 @@ state transitions, retries, and external effects while agents and coding harness
 results. The V1 reference runtime uses Blob, AI SDK `HarnessAgent`, and Vercel Sandbox,
 with independent verification and human-owned merges.
 
-See the [repository README](../../README.md) for development instructions and the
-[architecture](../../docs/factory-architecture.md) for the complete contract.
+## Requirements and installation
+
+Factory requires Node.js 24 or newer and publishes ESM. Install the package with its required
+`eve` and `zod` peers:
+
+```sh
+pnpm add @vercel/factory eve zod
+```
+
+Optional storage, sandbox, and harness integrations declare additional peer dependencies. Install
+them only when using the corresponding capability path.
+
+The published declarations are checked with TypeScript 5.9.3 and 7.0.2. Core workflows and the Blob
+adapter use `nodeNext` resolution with library checking enabled; the browser-safe `/client` entry
+point uses `bundler` resolution without loading Node, Eve, Blob, or Drizzle types. The Postgres
+adapter is checked with its Drizzle peer and `skipLibCheck` because Drizzle's declaration graph
+includes declarations for optional database drivers.
+
+Start with the shipped [Eve agent integration recipe](docs/recipes/eve-agent.md), which shows how
+Factory dispatches a route-bound Task into Eve and how the agent mounts Factory authentication,
+tools, and hooks. The [local Task quickstart](docs/getting-started.md) isolates the durable state
+model without running an agent. The [consumer documentation index](docs/index.md) maps common goals
+to import paths and version-matched declaration files. For complete runtime assembly boundaries,
+read [runtime composition](docs/runtime-integration.md).
+
+Runnable, credential-free recipes cover [Eve agent integration](docs/recipes/eve-agent.md),
+[typed Eve workflow results](docs/recipes/typed-eve-result.md),
+[human input and resumption](docs/recipes/human-input.md),
+[dependent Eve agents](docs/recipes/dependent-tasks.md),
+[custom workflows and local execution](docs/recipes/custom-workflow.md),
+[persistent restart recovery](docs/recipes/persistence-recovery.md),
+[cancellation](docs/recipes/cancellation.md), [retry recovery](docs/recipes/retry-recovery.md), and
+[typed Task messaging](docs/recipes/task-messaging.md). Each published example is compiled and
+executed against the package before release.
+
+The optional Vercel-managed Git transport uses fresh trusted Sandboxes for reads and signed
+publication. These transfer Sandboxes run no repository code or models; agent and harness Sandboxes
+remain credential-free. The managed transport returns the reconciled signed commit SHA. Initial Git Data API
+publication remains an application-selected adapter.
+
+## Public import paths
+
+Use the narrowest capability entry point that owns an API. This keeps optional integrations and
+browser/server boundaries visible and keeps dependencies aligned with the capability in use.
+
+Factory targets Eve agents, and `eve` is a required peer dependency. Eve-specific APIs live with
+their semantic owner instead of under a parallel `/eve` namespace.
+
+| Import path                                                     | Use for                                                                               |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `@vercel/factory`                                               | Configuration, shared primitives, and generic Eve sessions, hooks, and Task tools     |
+| `@vercel/factory/tasks`                                         | Tasks, graphs, messages, effects, and their stores                                    |
+| `@vercel/factory/workflows`                                     | Workflow definitions, work contracts, and agent routes                                |
+| `@vercel/factory/execution`                                     | Provider-neutral dispatch, execution lifecycle, and sweeps                            |
+| `@vercel/factory/planning`                                      | Provider-neutral planner contracts and runtime                                        |
+| `@vercel/factory/budgets`                                       | Budget schemas, capacity policy, settlement, and maintenance sweeps                   |
+| `@vercel/factory/signals`                                       | Signal records, intake creation, decisions, and lifecycle                             |
+| `@vercel/factory/receipts`                                      | Immutable audit records, costs, identifiers, and append inputs                        |
+| `@vercel/factory/storage`, `/storage/blob`, `/storage/postgres` | Store engine and optional persistence adapters                                        |
+| `@vercel/factory/communication`                                 | Inbound normalization, routing, and outbox contracts                                  |
+| `@vercel/factory/client`, `/api`, `/next`                       | Browser client, server handlers, and Next.js integration                              |
+| `@vercel/factory/changes`                                       | Change lifecycle, verification, and multi-repository coordination                     |
+| `@vercel/factory/findings`                                      | Finding records, remediation, fingerprints, and agent reporting                       |
+| `@vercel/factory/code-review`                                   | Review policy, contracts, and agent tools                                             |
+| `@vercel/factory/pull-requests`                                 | Publication and merge-conflict contracts and tools                                    |
+| `@vercel/factory/work-triage`                                   | Existing-work lookup and its agent tool                                               |
+| `@vercel/factory/delivery-metrics`                              | Delivery ledger metrics and repository health                                         |
+| `@vercel/factory/presets/software-development`                  | Supplied software-development policy and Eve composition                              |
+| `@vercel/factory/integrations/github`                           | GitHub API helpers and communication, review, publication, label, and triage adapters |
+| `@vercel/factory/integrations/slack`                            | Slack communication delivery adapter                                                  |
+| `@vercel/factory/integrations/deepsec`                          | DeepSec normalization and its Eve scanner tool                                        |
+| `@vercel/factory/integrations/vercel`                           | Vercel Queue and trusted Git transport adapters                                       |
+| `@vercel/factory/sandbox`                                       | Optional isolated execution integration                                               |
+
+The package root owns common configuration, cross-cutting primitives, and generic Eve integration
+that have no narrower capability owner. Each public declaration has one canonical owner. The
+browser client and server API re-export shared HTTP wire contracts at both consumption boundaries
+from the same source declarations.
+
+Ordinary public values and functions use `camelCase`; type-like declarations, constructors, and UI
+components use `PascalCase`; fixed constant-style values may use `UPPER_CASE`. Schemas use a
+`thingSchema` / `Thing` pair; configuration objects, operation results, and error classes use
+`*Options`, `*Result`, and `*Error`. Factories use `create*`, while declarative validators and
+registries use `define*`. Provider and protocol payload keys retain their required wire spelling.
+Oxlint is the repository's sole JavaScript and TypeScript linter and enforces the allowed
+identifier shapes. Declaration-specific casing follows the conventions above in code and review.
+
+## API stability and repository development
+
+This package is pre-1.0: replaced paths and names can be removed during alpha API cleanup rather
+than retained as deprecated aliases. Check the shipped [changelog](CHANGELOG.md) before upgrading
+persisted factories.
+
+Repository setup, architecture, and contribution instructions live in the
+[Agent Factory repository](https://github.com/vercel-labs/agent-factory). They are maintainer
+documentation rather than prerequisites for using the installed package.

package/dist/agent-routes.d.mts

@@ -0,0 +1,113 @@
+import { AgentRouteBinding, AgentRouteBindingInput, agentRouteBindingSchema, parseAgentRouteBinding } from "./schema/agent-route.mjs";
+import { JsonValue, TaskWork } from "./schema/work.mjs";
+import { TaskKind } from "./schema/task.mjs";
+import { z } from "zod";
+//#region src/agent-routes.d.ts
+/** Validates an exact-version route from workflow work to one configured agent. */
+declare const agentRouteSchema: z.core.$ZodBranded<z.ZodObject<{
+  id: z.ZodString;
+  version: z.ZodDefault<z.ZodNumber>;
+  agent: z.ZodString;
+  taskKind: z.ZodType<TaskKind, unknown, z.core.$ZodTypeInternals<TaskKind, unknown>>;
+  description: z.ZodString;
+  permissions: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>, "AgentRouteBinding", "out">;
+/** Canonical `id@version` lookup key for one exact agent route. */
+type AgentRouteKey<Id extends string = string, Version extends number = number> = `${Id}@${Version}`;
+/** Validated immutable route describing an agent, Task kind, purpose, and permissions. */
+type AgentRoute = Readonly<Omit<z.infer<typeof agentRouteSchema>, "permissions"> & {
+  readonly permissions: readonly string[];
+}>;
+/** Caller input accepted when registering an agent route, before defaults are applied. */
+interface AgentRouteInput {
+  /** Stable lowercase route identifier selected by workflows. */
+  readonly id: string;
+  /** Positive exact version. Defaults to `1` during registration. */
+  readonly version?: number;
+  /** Internally addressable Eve agent name used by the application launcher. */
+  readonly agent: string;
+  /** Descriptive Task kind created for work on this route; it does not control routing. */
+  readonly taskKind: TaskKind;
+  /** Model-facing explanation of when this route is appropriate. */
+  readonly description: string;
+  /** Inspectable capability labels; the application still enforces actual authorization. */
+  readonly permissions?: readonly string[];
+}
+/** Task work with a required exact agent-route binding. */
+type RoutedTaskWork<Input extends JsonValue = JsonValue, Route extends AgentRouteBinding = AgentRouteBinding> = Omit<TaskWork<Input>, "route"> & {
+  readonly route: Route;
+};
+/** Named fields for constructing generic work bound to an exact agent route. */
+interface RouteTaskWorkOptions<Route extends AgentRouteBinding = AgentRouteBinding, Input extends JsonValue = JsonValue> {
+  readonly route: Route;
+  readonly title: string;
+  readonly input?: Input;
+  readonly workflow?: never;
+  readonly completionCriteria?: never;
+}
+/** Produces the canonical `id@version` lookup key for a route binding. */
+declare function routeKey<const Binding extends AgentRouteBinding>(binding: Binding): AgentRouteKey<Binding["id"], Binding["version"]>;
+/** Constructs generic Task work bound to the selected exact agent route. */
+declare function routeTaskWork<const Route extends AgentRouteBinding, const Input extends JsonValue = JsonValue>(options: RouteTaskWorkOptions<Route, Input>): RoutedTaskWork<Input, AgentRouteBinding<Route["id"], Route["version"]>>;
+type RegisteredAgentRoute<Input extends AgentRouteInput> = Input extends AgentRouteInput ? AgentRouteBinding<Input["id"], Input extends {
+  readonly version: infer Version extends number;
+} ? Version : 1> & Readonly<Omit<Input, "version" | "permissions"> & {
+  readonly version: Input extends {
+    readonly version: infer Version extends number;
+  } ? Version : 1;
+  readonly permissions: readonly string[];
+}> : never;
+/** Immutable registry for exact agent-route lookup and unambiguous admission selection. */
+interface AgentRouteRegistry<out Route extends AgentRoute = AgentRoute> {
+  /** Immutable validated routes in registration order. */
+  readonly routes: readonly Route[];
+  /**
+   * Returns only the exact route binding supplied; never defaults a version.
+   *
+   * @param binding - Exact route ID and version to resolve.
+   * @returns The registered route, or `undefined` when that exact version is absent.
+   */
+  get<const Binding extends AgentRouteBinding>(binding: Binding): (Route & Readonly<Binding>) | undefined;
+  /**
+   * Lists every registered route for a descriptive Task kind in registration order.
+   *
+   * @param kind - Descriptive Task kind to filter by.
+   * @returns Matching routes; an empty array when none were registered.
+   */
+  listForTaskKind<const Kind extends string>(kind: Kind): readonly (Route & {
+    readonly taskKind: Kind;
+  })[];
+}
+type RegisteredAgentRoutes<Input extends readonly AgentRouteInput[]> = [Input[number]] extends [never] ? AgentRoute : RegisteredAgentRoute<Input[number]>;
+/**
+ * Builds an immutable registry whose exact bindings are the routing authority.
+ *
+ * @remarks
+ * Descriptions and permissions are inspectable guidance. They do not authorize execution and a
+ * Task kind never selects a route. Persist the exact route binding on work and recover that same
+ * binding after retries. Omitted versions and permissions become `1` and an empty array.
+ *
+ * @param inputs - Application-owned routes available to workflow and agent policy.
+ * @returns A registry supporting exact lookup and descriptive Task-kind listing.
+ * @throws A Zod validation error for an invalid route or an error for duplicate `id@version` keys.
+ *
+ * @example
+ * ```ts
+ * import { defineAgentRoutes } from "@vercel/factory/workflows";
+ *
+ * const routes = defineAgentRoutes([
+ *   {
+ *     id: "incident-worker",
+ *     agent: "worker",
+ *     taskKind: "incident",
+ *     description: "Investigate one admitted incident.",
+ *     permissions: ["read-repository"],
+ *   },
+ * ]);
+ * const route = routes.routes[0];
+ * ```
+ */
+declare function defineAgentRoutes<const Input extends readonly AgentRouteInput[]>(inputs: Input): AgentRouteRegistry<RegisteredAgentRoutes<Input>>;
+//#endregion
+export { AgentRoute, type AgentRouteBinding, type AgentRouteBindingInput, AgentRouteInput, AgentRouteKey, AgentRouteRegistry, RouteTaskWorkOptions, RoutedTaskWork, agentRouteBindingSchema, agentRouteSchema, defineAgentRoutes, parseAgentRouteBinding, routeKey, routeTaskWork };
+//# sourceMappingURL=agent-routes.d.mts.map