@murphai/hosted-execution

Shared hosted-execution helpers for the hosted apps/web control plane and the Cloudflare execution worker.

Scope

• own shared hosted execution contract types for the greenfield mailbox, workspace checkpoint, redacted runtime log, hosted usage record, and Temporal processing/status seams
• define the shared hosted conversation.message payload shapes for supported hosted conversation channels: Linq, Telegram, and email
• define hosted execution auth header names and request-canonicalization helpers
• normalize the shared hosted execution env variables that are deployment-vendor neutral
• build stable internal route paths for hosted runtime mailbox, workspace, logging, status, and transport helpers
• provide typed shared control helpers while keeping deployed auth adapters app-local

Active public path

New hosted runtime code should import mailbox, workspace checkpoint, runtime log, and workspace invocation contracts from @murphai/hosted-execution/runtime-control. Temporal processing/status contracts live in @murphai/hosted-execution/orchestration-control. Workflow consumers also use that entrypoint for isHostedMailboxLane; its runtime graph stays independent of runtime-control and health schemas. Runtime-control retains the same exports for execution consumers. Use @murphai/hosted-execution/routes for stable route constants and builders. Runtime log and redacted-status validation is owned by src/parsers/runtime-log.ts, exported through @murphai/hosted-execution/parsers. Workspace checkpoints and runner/Web status compose that same validator; receipt-specific reserved keys remain with checkpoint parsing. Shared scalar checks stay in src/parsers/assertions.ts, while src/observability.ts owns producer sanitization. Use @murphai/hosted-execution/assistant-usage for the hosted assistant usage record contract, parser, id helper, and credential-source helper. The v2 turn profile may include knowledgeCounts on the vault-cli knowledge command aggregate: show, list, search, write, and other call counts, plus missing, invalid, conflict, and other failure counts. Counts reconcile with the existing call/failure totals; missing pages remain failed commands. Classification reads only bounded complete JSON error envelopes and persists numbers, never page slugs, arguments, paths, or error text. Older readers omit this optional field; new readers continue accepting profiles without it. These diagnostic counters do not change token metering or billing. Existing compound-command and batch family attribution stays unchanged; those calls are not reclassified as knowledge. Use @murphai/hosted-execution/plan-usage for the strict request and member plan-usage status codec. The empty request preserves the original response shape; a caller may opt into the optional nullable subscriptionActionQuote for current explicit-request terms. The thresholded recommendedAction stays separate, and neither field is consent. Use @murphai/hosted-execution/labs for the strict read-only search, show, and locations request/response codecs. These contracts carry bounded normalized provider facts and never carry the Junction credential, raw provider body, or a member identity. Use @murphai/hosted-execution/subscription for the input-bound conversational subscription-action request and response codecs. The response carries current server-owned plan terms and exposes a payment URL only when payment is required. Use @murphai/hosted-execution/clinical-records for the pointer-only clinical sync wake, bounded run/page/outcome contracts, and stable signed runtime route paths. Those contracts carry hashes, opaque cursors, sanitized FHIR page JSON, and bounded counts; they never carry OAuth credentials or raw provider URLs in mailbox or Temporal state.

Legacy generic hosted run/cursor/drain contracts and parsers are not part of the active package surface. The bounded clinical retrieval descriptor and opaque page cursor on the explicit clinical-records subpath are a separate active domain contract. Historical completed plans and migration notes may still mention the deleted generic state.

Contract

• signed callback canonicalization stays timestamped and request-bound across app-local signers and verifiers
• the shared control/status path layout stays stable between callers and the worker
• non-direct route-authorized Linq and Telegram conversation wakes may carry an optional normalized senderMemberId that Web already authenticated at admission; direct wakes reject the field, and consumers must not treat it as runtime authority or expose it to models, logs, telemetry, or UI
• vendor-neutral env naming stays canonical so hosted web and Cloudflare do not drift
• this package owns only the shared hosted-execution transport seam: mailbox, workspace checkpoint, runtime log/status codecs, hosted usage record codecs, plan-usage, Labs-discovery, and subscription-action codecs, route builders, auth header names, and canonicalization helpers; projection logic stays in apps/web
• deployment topology stays app-local: shared packages must not own worker hostnames, callback base-url defaults, or proxy-vs-server inference
• app-local auth adapters still own deployment-specific bearer token acquisition plus callback signing and verification
• operator-facing hosted public-origin fallback and Cloudflare callback-key config stay app-local and are intentionally documented in apps/web/README.md, not here
• Cloudflare operational control routes are private owner APIs, not part of this public package
• normal webhook and app paths append durable mailbox facts and signal Temporal only; they do not send user-level runner nudges directly to Cloudflare
• Temporal calls Cloudflare ensure-processing; Cloudflare returns runtime_processing_accepted or retry_later and owns runner start, wake, active-fence alarm cleanup, and execution cleanup.
• The optional positive-only conversationWorkPending ensure fact permits standby allocation for admitted conversation work in default mode. Deploy the accepting Cloudflare receiver before its Temporal producer; absent fields preserve existing behavior. It grants no consent, access, or write authority.
• device-sync runtime snapshot/apply/token contracts stay on @murphai/device-syncd/hosted-runtime; this package only carries the outer hosted runtime control seam plus the shared device-sync wake-hint shape needed by that seam
• new hosted runtime log contracts are structured and redacted: they accept event codes and allowlisted scalar metadata, not free-form messages or plaintext payload fields
• runtime-control parsers may keep explicit fail-closed guards for removed run/status fields, but those guards must reject the old fields rather than reading, translating, or otherwise supporting them as compatibility input

Ownership note

This package now hard-cuts device-sync runtime snapshot/apply/token exports. Consumers that previously imported those symbols from @murphai/hosted-execution or @murphai/hosted-execution/parsers must import them from @murphai/device-syncd/hosted-runtime instead.

Configuration request/response parsers live with the model and provider values in @murphai/hosted-execution/assistant-model. Consumers that only need those parsers should use that entrypoint to avoid initializing unrelated runtime and device-sync parsers. The existing parsers exports forward to the same functions.