Prepare a hosted Heddle agent for production

Identity and authorization

• Authenticate before constructing a Heddle run address or repository scope.
• Derive tenant, account, and user identity on the trusted server. Never trust a browser-supplied account ID.
• Authorize start, subscribe, cancel, approval resolution, session read, reset, and artifact access independently.
• Use stable product conversation IDs and enforce tenant isolation in both the application service and storage adapter.
• Treat an unknown or wrong-scope runId as not found; possession is not authorization.

Credentials, capabilities, and policy

• Resolve model credentials server-side for the authenticated product context.
• Choose model, reasoning effort, system context, product tools, MCP extensions, and capability policy at the composition root.
• Review tool schemas and outputs for tenant and data boundaries.
• Define who can approve each sensitive action and how the approval UI proves the approver's identity.
• Keep denial and timeout behavior predictable. A missing approval UI must not silently become approval.

Durable storage

The default JSON session repository is suitable for one-machine, local-first products. Point stateRoot at durable application data with normal local locking and atomic rename semantics. Do not place it on an eventually consistent object-store mount.

Hosted or multi-process products should inject an async, revisioned ChatSessionRepository. Database updates and deletes must compare the expected revision atomically so concurrent writers cannot silently overwrite newer state. Adapters must distinguish missing records, already-existing records, and revision conflicts, and paginate with a deterministic cursor.

Inject ArtifactRepository when generated content belongs in object or blob storage. Make content addressing, tenant scope, retention, encryption, backup, and deletion explicit.

Traces and memory still persist below stateRoot today. They do not yet have the same injectable repository boundary. Plan the host filesystem and retention policy accordingly rather than assuming every Heddle record is in your database.

Public contract and transport security

• Validate every untrusted request and response with strict schemas.
• Expose only authorized activity and terminal fields. Exclude tool input and output, filesystem paths, traces, provider messages, credentials, and internal session records unless the product explicitly requires and authorizes them.
• Configure payload limits, CORS, rate limits, request timeouts, secure headers, and audit logging.
• Project internal failures to stable public codes and safe messages while preserving original diagnostics server-side.
• Version the public API and event schemas when independent clients depend on them.

Replay and client recovery

• Persist the last sequence only after the application has handled that event.
• Persist the cursor with the visible projection it represents; otherwise reload can skip content.
• Test duplicate replay, sequence gaps, stream termination without terminal, malformed stored checkpoints, offline recovery, and exhausted retry budgets.
• Keep reconnect bounded and visible. Do not retry authorization or validation failures as transient server errors.
• Refresh durable conversation state after terminal settlement.

Process topology and delivery

ConversationRunService replay is process-local and bounded. It is not restart recovery or a distributed broker.

• Decide which process owns a run and how every operation reaches it.
• For multiple instances, define sticky routing or shared routing and delivery infrastructure.
• Define shutdown and draining behavior. Stop accepting new runs, keep active result projection from racing shutdown, and either finish or explicitly cancel work.
• Size replay limits and retention against event volume, reconnect expectations, and memory use.
• Verify behavior across deploys, crashes, provider stalls, storage failures, and client disconnects.

Product finalization

Use projectResult to persist or reconcile authorized product state before Heddle publishes success. Use projectError to prevent internal diagnostics from entering retained public replay. Decide whether product finalization is idempotent, how retries are detected, and what happens if persistence succeeds but a later response delivery fails.

Observability and operations

• Correlate product conversation ID, Heddle session ID, run ID, trace, and public request ID without exposing sensitive values.
• Record run acceptance, terminal kind, latency, cancellation, approval wait, model failure category, storage conflict, reconnect exhaustion, and projection failure.
• Alert on stuck active runs, repeated lease conflicts, replay exhaustion, authentication failures, and provider quota or rate-limit categories.
• Keep traces and public activities distinct: traces are diagnostic evidence; activities are user-facing progress.
• Provide support tooling to inspect safe run/session status without granting broad filesystem or tenant access.

Release gate

Before deployment, verify at minimum: two turns reuse one durable session; concurrent writers cannot lose updates; disconnect does not cancel; cursor reconnect does not duplicate or restart work; wrong-scope access is denied; cancellation reaches a terminal; approval decisions target the exact run; storage and projection failures remain failures; only intended public fields cross the transport; and active runs behave predictably during shutdown.