> ## Documentation Index > Fetch the complete documentation index at: https://growthx-changeset-release-main.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # v0.10.0 → v0.11.0 > Upgrading Output.ai projects from v0.10.0 to v0.11.0: HTTP clients, hook event envelopes, API request logging, Temporal rollout safety, shared activity names, child workflow activity-option precedence, Temporal TypeScript SDK v1.20.3, CLI workflow test rename, and strict prompt Liquid rendering. This guide covers customer-facing changes to `@outputai/http`, hooks and workflow execution in `@outputai/core`, prompt rendering in `@outputai/llm`, the `@outputai/cli` workflow test command name, and API request logging in `output-api`. ## API HTTP request logging The API server was refactored to remove the `morgan` dependency and emit richer request logs. The public HTTP API contract is unchanged, but the shape, level, and message of the per-request log lines the server emits are different. This only affects you if you consume `output-api` logs in an observability tool (Datadog, CloudWatch, Loki, etc.) or match on them in scripts. ### Log level now derives from response status This is the most impactful change. Previously every request was logged at the `http` level regardless of outcome. Now the level is chosen from the response status: | Status | Level (before) | Level (after) | | --------- | -------------- | ------------- | | 2xx / 3xx | `http` | `http` | | 4xx | `http` | `warn` | | 5xx | `http` | `error` | If you have alerts or filters keyed on winston log levels, they will now behave differently: any alert on `error` or `warn` will fire on 4xx/5xx HTTP responses that previously logged at `http`. ### The `status` field was renamed to `statusCode` The structured metadata field carrying the numeric response status changed name, for consistency with the other fields the logger emits. ```diff theme={null} - "status": 200 + "statusCode": 200 ``` If you use Datadog, map `statusCode` to the standard `http.status_code` attribute with a remapper in your log pipeline. That keeps the built-in HTTP status facet working without emitting a dotted field name from the application. ### The log message changed from a constant to a request summary Previously the message was the constant string `"HTTP request"`, with all detail in the metadata. Now the message is a human-readable summary and the structured record is still attached as metadata. ```diff theme={null} - "HTTP request" + "POST /workflow 200 12ms" ``` ### `responseTime` is now an integer `responseTime` is now whole milliseconds (measured with `Date.now()`) rather than a sub-millisecond float. ```diff theme={null} - "responseTime": 12.347 + "responseTime": 12 ``` ### Before and after A successful request, before (v0.10.0): ```json theme={null} { "level": "http", "message": "HTTP request", "method": "POST", "url": "/workflow", "status": 200, "contentLength": "42", "responseTime": 12.347, "requestId": "8f3c...", "workflowName": "simple" } ``` The same request, after (v0.11.0): ```json theme={null} { "level": "http", "message": "POST /workflow 200 12ms", "method": "POST", "url": "/workflow", "statusCode": 200, "contentLength": "42", "responseTime": 12, "requestId": "8f3c...", "workflowName": "simple" } ``` A server error, before — logged at `http`: ```json theme={null} { "level": "http", "message": "HTTP request", "status": 500, "errorType": "Error", "errorMessage": "Something went wrong" } ``` After — logged at `error`, with the renamed field: ```json theme={null} { "level": "error", "message": "POST /workflow 500 34ms", "statusCode": 500, "errorType": "Error", "errorMessage": "Something went wrong" } ``` ### Migration steps #### Update alerts and level-based filters If you alert or filter on winston levels, audit those rules. HTTP 4xx now arrives at `warn` and 5xx at `error`. Decide whether that is what you want: * To keep alerting only on application errors, scope alerts to exclude HTTP request logs (for example, filter on the presence of `statusCode`). * To alert on failing requests, this is now available directly from the log level with no extra query. #### Update queries and facets that reference `status` Anywhere you query, facet, or dashboard on the request-log `status` field, switch to `statusCode`. ```diff theme={null} # Datadog / log query - @status:500 + @statusCode:500 ``` In Datadog, add a remapper in your log pipeline to map `statusCode` onto the standard `http.status_code` attribute. That attribute maps to the built-in HTTP status facet, so once the remapper is in place you can query on `@http.status_code:500` and reuse the standard facet instead of defining a custom one. #### Update anything that matches the message string Scripts, log processors, or saved searches that match the literal message `"HTTP request"` will no longer match. Match on a structural field instead (for example, the presence of `statusCode` or `requestId`), or update the matcher to the new summary format ` ms`. #### Adjust `responseTime` consumers expecting sub-millisecond precision If a dashboard or aggregation relied on fractional milliseconds in `responseTime`, note that values are now whole milliseconds. ### API logging checklist * Review winston level-based alerts and filters; 4xx now logs at `warn`, 5xx at `error`. * Rename `status` to `statusCode` in log queries, facets, and dashboards; in Datadog, add a remapper from `statusCode` to `http.status_code`. * Replace any match on the constant message `"HTTP request"` with a structural field or the new summary format. * Confirm `responseTime` consumers tolerate integer milliseconds. ## Hook event changes This section applies to hook files that import from `@outputai/core/hooks`. ### `on()` now receives an event envelope In v0.10.x, SDK event fields were merged into the same object as framework metadata. In v0.11.0, framework metadata remains at the top level and event-specific data is available under `payload`. This affects every handler registered with `on()`, including: * `http:request` * `cost:http:request` * `cost:llm:request` * Custom events Lifecycle hooks such as `onWorkflowStart`, `onActivityEnd`, and `onError` remain flat. #### Before ```ts theme={null} import { on } from '@outputai/core/hooks'; import type { HttpRequestEvent } from '@outputai/http'; on( 'http:request', event => { console.log( event.eventId, event.workflowDetails.workflowId, event.method, event.url ); } ); ``` #### After ```ts theme={null} import { on } from '@outputai/core/hooks'; import type { HttpRequestEvent } from '@outputai/http'; on( 'http:request', event => { if ( !event.workflowDetails || !event.payload ) { return; } console.log( event.eventId, event.workflowDetails.workflowId, event.payload.method, event.payload.url ); } ); ``` The envelope has this shape: ```ts theme={null} { eventId: string; eventDate: number; activityInfo?: Info; workflowDetails?: WorkflowDetails; outputActivityKind?: string; payload: T | undefined; } ``` The generic passed to `on()` still describes the event-specific data. The difference is that `T` now types `event.payload` instead of fields on `event` itself. Because custom events can omit their payload, check `event.payload` before reading its fields. SDK events such as `http:request` and cost events always supply one, but the public handler type still represents the optional case. v0.11.0 also adds `emit(eventName, payload?)` for publishing custom events from an Output activity: ```ts theme={null} import { emit, on } from '@outputai/core/hooks'; emit( 'company:enriched', { companyId: 'company-123' } ); on<{ companyId: string }>( 'company:enriched', event => { if ( !event.payload ) { return; } console.log( event.payload.companyId ); } ); ``` When an event is emitted outside an activity context, `activityInfo`, `workflowDetails`, and `outputActivityKind` are omitted. These fields are therefore optional on `ExternalHookPayload`; check any context field before using it. ### Update imported hook payload types The exported base and envelope types were simplified in v0.11.0. If your hook files import these types directly, make the following replacements: * Replace `OnHookPayload` with `ExternalHookPayload`. * Replace `OnHookEnvelope` with `ActivityPayloadBase`. * Replace `ActivityHookPayload` with `ActivityPayloadBase`. `HookPayloadBase` now contains only `eventId` and `eventDate`. Use `WorkflowPayloadBase` when you also need `workflowDetails`, or `ActivityPayloadBase` when you need the workflow and activity context fields. #### Before ```ts theme={null} import type { ActivityHookPayload, OnHookEnvelope, OnHookPayload } from '@outputai/core/hooks'; type CompanyEnrichedEvent = OnHookPayload<{ companyId: string }>; ``` #### After ```ts theme={null} import type { ActivityPayloadBase, ExternalHookPayload } from '@outputai/core/hooks'; type CompanyEnrichedEvent = ExternalHookPayload<{ companyId: string }>; ``` ### Activity lifecycle hooks include internal activities `onActivityStart`, `onActivityEnd`, and `onActivityError` now run for internal activities as well as steps and evaluators. Internal activity payloads have: ```ts theme={null} { outputActivityKind: 'internal_step' } ``` If your handler should keep the v0.10.x behavior, add an explicit filter: ```ts theme={null} import { onActivityStart } from '@outputai/core/hooks'; onActivityStart( event => { if ( event.outputActivityKind === 'internal_step' ) { return; } // Handle steps and evaluators. } ); ``` Review metrics, logs, webhooks, and state updates triggered by activity lifecycle hooks. Without a filter, internal activities now contribute to those side effects. ### `onError` excludes the internal catalog workflow The internal `$catalog` workflow was already excluded from `onWorkflowStart`, `onWorkflowEnd`, and `onWorkflowError`. In v0.11.0, its workflow and activity errors are also excluded from `onError`. No migration is needed unless an `onError` handler explicitly relied on `$catalog` failures. Worker startup and catalog-manager failures still surface as runtime errors. Monitor Temporal or API catalog health if you need to detect the catalog workflow being terminated after startup. ### Hook migration checklist * Update every `on()` handler to read event-specific fields from `event.payload`. * Guard `event.payload` before accessing its fields. * Keep framework fields such as `eventId`, `workflowDetails`, and `activityInfo` at the top level. * Filter `outputActivityKind === 'internal_step'` in activity lifecycle hooks when internal activities should remain hidden. * Remove assumptions that `onError` reports `$catalog` workflow failures. ## HTTP client changes `@outputai/http` now exposes two explicitly named, instrumented clients: * `outputFetch` for Fetch-compatible requests. * `createKyClient` for a Ky client backed by `outputFetch`. Ky was upgraded from v1 to v2 and both Ky and Undici are now peer dependencies. Most projects using the previous `httpClient` need import, option, and dependency updates. ### Upgrade and resolve the HTTP peers Ky and Undici were previously private dependencies of `@outputai/http` and are now peers. Current npm and pnpm versions install compatible peers automatically, so upgrading the Output package is normally enough: ```bash theme={null} npm install @outputai/http@^0.11 ``` Use the equivalent command for your package manager, then commit the updated lockfile. Install `ky@^2` or `undici@^8` explicitly only if you need to pin a version or resolve a peer-version conflict. ### Rename HTTP exports Update imports using this mapping: | v0.10.x | v0.11.0 | | ------------------- | ------------------------------------------- | | `fetch` | `outputFetch` | | `httpClient` | `createKyClient` | | `HTTPError` | `ky.HTTPError` | | `TimeoutError` | `ky.TimeoutError` | | `HttpClientOptions` | `ky.Options` | | `RequestInfo` | `undici.RequestInfo` or a native Fetch type | | `RequestInit` | `undici.RequestInit` or a native Fetch type | For example: ```diff theme={null} - import { httpClient, HTTPError, TimeoutError } from '@outputai/http'; + import { createKyClient, ky } from '@outputai/http'; - const client = httpClient( { + const client = createKyClient( { timeout: 30_000 } ); try { await client.get( url ); } catch ( error ) { - if ( error instanceof HTTPError ) { + if ( error instanceof ky.HTTPError ) { console.log( error.response.status ); } - if ( error instanceof TimeoutError ) { + if ( error instanceof ky.TimeoutError ) { console.log( 'Request timed out' ); } } ``` The complete Ky and Undici namespaces are available as `ky` and `undici` from `@outputai/http`. ### Update Ky v2 options Replace Ky's `prefixUrl` option with `prefix`: ```diff theme={null} - const client = httpClient( { - prefixUrl: 'https://api.example.com', + const client = createKyClient( { + prefix: 'https://api.example.com', timeout: 30_000 } ); ``` Review other Ky options against Ky 2 when upgrading. This is especially important for shared client factories that expose Ky's `Options` type. See [Ky's official v2.0.0 migration guide](https://github.com/sindresorhus/ky/releases/tag/v2.0.0#migration-guide) for the complete list of changes, including empty-response JSON parsing, `beforeError` behavior, hook option normalization, `searchParams` merging, and `HTTPError.data`. ### Update Ky hook callbacks Ky 2 passes one state object to every hook. Ky 1 `beforeRequest`, `beforeError`, and `afterResponse` callbacks commonly used positional arguments. ```diff theme={null} - const beforeRequest = request => { + const beforeRequest = ( { request } ) => { request.headers.set( 'x-api-key', apiKey ); }; - const beforeError = error => { + const beforeError = ( { error } ) => { console.error( error.response?.status ); return error; }; - const afterResponse = async ( request, options, response ) => { + const afterResponse = async ( { request, options, response } ) => { await recordUsage( request, response ); }; ``` Types for hooks are also available through the Ky namespace: ```ts theme={null} import { ky } from '@outputai/http'; const afterResponse = async ( { response }: ky.AfterResponseState ) => { // ... }; ``` Audit hook functions passed indirectly through shared option objects as well as inline hooks. ### Replace custom wrappers around the old fetch export If your project created its own Ky factory solely to inject Output's old `fetch`, use `createKyClient` directly: ```diff theme={null} - import ky from 'ky'; - import type { Options } from 'ky'; - import { fetch } from '@outputai/http'; + import { createKyClient, ky } from '@outputai/http'; - export const createHttpClient = ( options: Options = {} ) => - ky.create( { fetch: fetch as NonNullable, ...options } ); + export const createHttpClient = ( options: ky.Options = {} ) => + createKyClient( options ); ``` If the wrapper adds other defaults or hooks, keep the wrapper and pass those options to `createKyClient`. ### Update direct Fetch usage Rename direct imports: ```diff theme={null} - import { fetch } from '@outputai/http'; + import { outputFetch } from '@outputai/http'; - const response = await fetch( url, init ); + const response = await outputFetch( url, init ); ``` `outputFetch` accepts URL strings, `URL` objects, and both Node and Undici `Request` objects. Node inputs are normalized before entering the Undici-backed implementation. Keep `Request` and `FormData` from the same family within one call: ```ts theme={null} import { outputFetch, undici } from '@outputai/http'; const form = new undici.FormData(); form.set( 'name', 'Ada' ); await outputFetch( 'https://api.example.com/users', { method: 'POST', body: form } ); ``` The same pattern works with Node's global `FormData`. Do not combine a Node `Request` with Undici `FormData`, or an Undici `Request` with Node `FormData`. ### Remove reliance on `undici.install()` Importing `@outputai/http` no longer replaces `globalThis.fetch`, `Request`, `Response`, `Headers`, or `FormData`. Code that imports an Undici dispatcher but calls global `fetch` should choose the HTTP implementation explicitly. Use `outputFetch` when the request should be traced: ```diff theme={null} - import { undici } from '@outputai/http'; + import { outputFetch, undici } from '@outputai/http'; const dispatcher = new undici.EnvHttpProxyAgent( { headersTimeout: 15 * 60 * 1000, bodyTimeout: 15 * 60 * 1000 } ); - const customFetch = ( input: string | URL | Request, init?: RequestInit ) => - fetch( input, { ...init, dispatcher } as RequestInit ); + const customFetch = ( + input: undici.RequestInfo, + init?: undici.RequestInit + ) => outputFetch( input, { ...init, dispatcher } ); ``` Use `undici.fetch` instead when tracing is not wanted. Do not assume the npm Undici dispatcher's types or behavior apply to Node's built-in Fetch implementation. ### Configure proxy behavior explicitly Core workers no longer install a process-wide Undici dispatcher when proxy environment variables are present. * `outputFetch` and `createKyClient` continue to use an `EnvHttpProxyAgent` and honor standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` variables. * For direct npm Undici calls, pass an `undici.EnvHttpProxyAgent` or configure Undici's global dispatcher yourself. * For Node's built-in Fetch, enable Node's environment proxy support at process startup with `NODE_USE_ENV_PROXY=1` and set the standard proxy variables. Audit libraries that receive a custom `fetch` callback. Ensure the callback uses `outputFetch`, `undici.fetch`, or native Fetch intentionally rather than relying on the old import-time global replacement. ### HTTP migration checklist * Upgrade `@outputai/http` and confirm the lockfile resolved Ky 2 and Undici 8. * Rename `fetch` and `httpClient`. * Update error and option types to the `ky` and `undici` namespaces. * Replace `prefixUrl` with `prefix`. * Convert Ky hooks to state-object parameters. * Replace custom Ky factories that only injected Output's old `fetch`. * Check custom dispatchers and Fetch callbacks for reliance on `undici.install()`. * Configure proxy behavior for non-Output HTTP calls. * Run type checking and HTTP integration tests after regenerating the lockfile. ## Workflow runtime changes This section covers the workflow execution changes in `@outputai/core` v0.11.0. ### What changed * Steps, evaluators, and shared activities now use one workflow-scoped runtime dispatcher. * Shared activities are registered as `#` instead of `$shared#`. * Child workflow invocation options are passed as workflow arguments instead of being propagated through Temporal memo. * A child workflow's definition-level `activityOptions` now override inherited parent options. Invocation-level and step-level options remain more specific. ### Before upgrading running workers Do not deploy v0.10.x and v0.11.0 workers to the same Temporal task queue, and do not replace a v0.10.x worker while affected workflow executions are still open. The v0.11.0 runtime changes Temporal command attributes: * A shared activity previously scheduled as `$shared#send_event` is now scheduled as `lead_enrichment#send_event`. * A child workflow is now started with its invocation-level activity options in its argument payload instead of inherited through memo. Temporal replays a workflow's existing history when another worker processes it. If a v0.11.0 worker replays a history produced by v0.10.x and reaches one of these commands, the new command can differ from the recorded event. Temporal then reports a nondeterminism failure. A mixed-version rollout is also unsafe. The two versions use different memo and child-argument contracts, so an old parent and new child, or a new parent and old child, can lose inherited activity options even when replay does not fail immediately. #### Choose a safe rollout strategy Use one of these strategies before changing the worker version: 1. **Drain the existing task queue.** Stop starting new workflows on the v0.10.x queue, wait for affected executions to complete, and then replace the worker. 2. **Move v0.11.0 to a new task queue.** Keep the v0.10.x worker serving its existing queue while new executions are routed to a separate v0.11.0 queue. 3. **Restart affected executions.** If an execution can be safely terminated and restarted from its original input or a checkpoint, restart it after the v0.11.0 cutover. At minimum, treat executions that call shared activities or child workflows as affected. Do not rely on a normal rolling restart on the same task queue. #### Update activity-type consumers Update dashboards, alerts, history processors, and scripts that match the old `$shared` activity prefix. ##### Before ```ts theme={null} const isSharedActivity = activityType.startsWith( '$shared#' ); ``` ##### After Shared and local activities use the same workflow namespace. Match the full workflow activity type when possible: ```ts theme={null} const isSendEventActivity = activityType === 'lead_enrichment#send_event'; ``` If the workflow name is not known: ```ts theme={null} const activityName = activityType.split( '#' ).at( -1 ); const isSendEventActivity = activityName === 'send_event'; ``` ### Review child workflow activity options Activity options are merged from broad defaults to specific overrides. v0.11.0 changes the relative precedence of inherited parent options and the child workflow's definition. #### v0.10.x precedence 1. Output's default activity options 2. The child workflow's definition-level `options.activityOptions` 3. Activity options inherited from the parent workflow 4. The `activityOptions` passed to this child invocation 5. The called step's own `options.activityOptions` #### v0.11.0 precedence 1. Output's default activity options 2. Activity options inherited from the parent workflow 3. The child workflow's definition-level `options.activityOptions` 4. The `activityOptions` passed to this child invocation 5. The called step's own `options.activityOptions` This means a child definition now protects its own retry and timeout defaults from broader settings inherited through the parent. For example: ```ts theme={null} const childWorkflow = workflow( { name: 'enrich_company', options: { activityOptions: { retry: { maximumAttempts: 2 } } }, async fn( input ) { // ... } } ); ``` If the parent currently has `maximumAttempts: 8`, the child used 8 attempts in v0.10.x. In v0.11.0, the child uses 2 attempts. #### Preserve a parent-selected override Pass the policy on the child invocation when the parent must override the child's definition: ```ts theme={null} await childWorkflow( { companyId: input.companyId }, { activityOptions: { retry: { maximumAttempts: 8 } } } ); ``` Invocation-level options remain more specific than inherited parent options and the child definition. Alternatively, remove the overlapping option from the child definition when the child should always inherit that field from its parent. Step-level `options.activityOptions` still have final precedence. Review step definitions as well as parent and child workflow definitions when calculating the effective policy. ### Workflow runtime checklist * Inventory open v0.10.x executions that call shared activities or child workflows. * Drain the old task queue, keep a v0.10.x worker for old executions, or restart affected executions before the cutover. * Do not run v0.10.x and v0.11.0 workers on the same Temporal task queue. * Update dashboards and history tooling that match `$shared#`. * Audit parent and child workflows that configure the same retry or timeout fields. * Pass `activityOptions` on child invocations where the parent must override the child's definition. * Update tests that assert inherited parent options override child definition options. ## Temporal TypeScript SDK version Output now ships the Temporal TypeScript SDK (`@temporalio/*`) at **v1.20.3** (previously **v1.17.0**). Re-test any project code that imports `@temporalio/*` directly against that version. ## CLI: `workflow test_eval` renamed to `workflow test` The workflow evaluation command id is now `workflow:test`. The previous primary id `workflow:test_eval` is removed (it was only the filename-derived id; published docs already used `output workflow test`). ```bash theme={null} # Before npx output workflow test_eval # After npx output workflow test ``` `output workflow test` continues to work the same way; only the `test_eval` name stops resolving. ### CLI rename checklist * Replace any scripts, CI steps, or aliases that call `output workflow test_eval` with `output workflow test`. * No change if you already use `output workflow test`. ## Prompt Liquid rendering is strict `@outputai/llm` now renders `.prompt` files with Liquid `strictVariables: true` and `strictFilters: true` (plus `lenientIf: true`). ### What changed | Case | Before (v0.10.0) | After (v0.11.0) | | ------------------------------------------ | ------------------------------- | ----------------------------------------- | | Undefined variable (`{{ missing }}`) | Rendered as an empty string | Throws a non-retryable `FatalError` | | Unknown filter (`{{ x \| not_a_filter }}`) | Rendered without failing closed | Throws a non-retryable `FatalError` | | Falsy / missing values in `{% if %}` | Omitted / falsey as usual | Unchanged (`lenientIf` still allows this) | ### Migration steps 1. Audit `.prompt` files for placeholders that are not always passed in `variables`. 2. Pass every referenced variable (or remove / guard the placeholder). Prefer `{% if var %}` / `| default:` only when the variable is still provided or you intentionally rely on `lenientIf` conditionals. 3. Replace custom or misspelled filters with [supported Liquid filters](https://liquidjs.com/filters/overview.html). 4. Expect render failures to surface as `FatalError` (no Temporal retry) — fix the prompt or inputs rather than catching and retrying. ### Prompt strictness checklist * Grep prompts for `{{` and confirm each name is supplied by callers. * Run critical workflows once after upgrade and watch for `Prompt "…" could not be rendered` fatals. * Update any docs or tests that assumed empty-string rendering for missing variables.