create-qpq-app 0.1.5

package/template/docusaurus/docs/actions/core/queue/ask-queue-send-messages.md

@@ -0,0 +1,89 @@
+---
+title: askQueueSendMessages
+description: Enqueue one or more messages onto a queue for its consumer stories to process asynchronously.
+---
+
+# askQueueSendMessages
+
+Enqueues one or more messages onto a [queue](../../../config/core/queue.md). Each message is delivered asynchronously to the consumer story whose processor pattern matches the message's `type`. Sending is fire-and-forget — the action returns once the messages are accepted, not when they are processed.
+
+- **Action type:** `QueueActionType.SendMessages`
+
+```typescript
+import { askQueueSendMessages } from 'quidproquo-core';
+
+export function* scheduleWelcomeEmail(user: { id: string; email: string }) {
+  yield* askQueueSendMessages('emails',
+    { type: 'email.welcome', payload: { userId: user.id, to: user.email } },
+  );
+}
+```
+
+## Signature
+
+```typescript
+function* askQueueSendMessages<T extends QueueMessage<any>>(
+  queueName: string,
+  ...queueMessages: T[]
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `queueName` | `string` | Name of the queue to send to — must match a queue declared with [defineQueue](../../../config/core/queue.md) (or one shared via its `owner` option). |
+| `...queueMessages` | `QueueMessage<T>[]` | One or more messages to enqueue, passed as rest arguments. |
+
+### `QueueMessage<T>`
+
+```typescript
+export type QueueMessage<T> = {
+  type: string;
+  payload: T;
+  groupId?: string;
+  deduplicationId?: string;
+};
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `type` | `string` | The message type. The queue matches this against its processor patterns (from [defineQueue](../../../config/core/queue.md)) to pick the consumer story. |
+| `payload` | `T` | The message body, serialized as JSON on the wire. |
+| `groupId` | `string` (optional) | **FIFO queues only.** Messages sharing a group are processed in order. Defaults to the queue name (global ordering). Ignored on non-FIFO queues. |
+| `deduplicationId` | `string` (optional) | **FIFO queues only.** Suppresses duplicate sends within SQS's 5-minute window. Defaults to a generated uuid (no deduplication). Ignored on non-FIFO queues. |
+
+## Returns
+
+`void` — the action completes once the messages are accepted by the queue. It does not wait for the consumer stories.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `QueueSendMessagesErrorTypeEnum.AccessDenied` | The caller lacks permission to send to the queue. |
+| `QueueSendMessagesErrorTypeEnum.QueueNotFound` | The underlying queue does not exist. |
+| `QueueSendMessagesErrorTypeEnum.ServiceUnavailable` | Internal error or throttling from the messaging service. |
+
+Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
+
+```typescript
+const outcome = yield* askCatch(
+  askQueueSendMessages('emails', { type: 'email.welcome', payload: { userId } }),
+);
+
+if (!outcome.success) {
+  // outcome.error.errorType / outcome.error.errorText
+}
+```
+
+## Notes
+
+- Messages are sent with the caller's story session attached, which the pipeline restores when the consumer story runs.
+- For FIFO ordering, set `groupId` per message to control which messages must stay ordered relative to each other.
+
+## Related
+
+- [defineQueue](../../../config/core/queue.md) — declares the queue this action sends to and maps message types to consumer stories.
+- [askEventBusSendMessages](../event-bus/ask-event-bus-send-messages.md) — publish to an event bus (fan-out to many queues) instead of one queue.
+- [askProcessEvent](../event/ask-process-event.md) — the pipeline that matches each delivered message to a consumer story and preserves FIFO group ordering.

package/template/docusaurus/docs/actions/core/state/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "State",
+  "link": {
+    "type": "generated-index",
+    "description": "Redux-style in-story state: dispatch actions through reducers/effects and read the resulting state."
+  }
+}

package/template/docusaurus/docs/actions/core/state/ask-reduce-state.md

@@ -0,0 +1,160 @@
+---
+title: askReduceState
+description: Run a story purely for its dispatched effects and return the reduced state.
+---
+
+# askReduceState
+
+Runs an inner story purely for its state effects and returns the computed state. Every [askStateDispatch](./ask-state-dispatch.md) the inner story yields is captured here (it never reaches the outer runtime), fed through your `reducer`, and accumulated. Any [askStateRead](./ask-state-read.md) the story issues returns the current accumulated state. When the inner story finishes, `askReduceState` returns the final state. This is the pure-logic, backend counterpart to the React `useQPQ` reducer hooks: it lets any story run the same dispatch/read logic without a live State processor.
+
+- **Built from:** `askOverrideActions` — it intercepts the inner story's `StateActionType.Dispatch` and `StateActionType.Read` actions, handling each with your `reducer` and the accumulated state instead of letting them bubble to the runtime.
+
+```typescript
+import {
+  askReduceState,
+  askStateDispatch,
+  askStateDispatchEffect,
+  askStateRead,
+  buildMutableEffectReducer,
+  Effect,
+} from 'quidproquo-core';
+
+// 1. Model the state and the effects that change it.
+interface CounterState {
+  count: number;
+}
+
+type IncrementEffect = Effect<'counter/Increment'>;
+type AddEffect = Effect<'counter/Add', number>;
+type CounterEffects = IncrementEffect | AddEffect;
+
+// 2. Define a reducer: one handler per effect type.
+const counterReducer = buildMutableEffectReducer<CounterState, CounterEffects>({
+  'counter/Increment': (state) => {
+    state.count += 1;
+  },
+  'counter/Add': (state, amount) => {
+    state.count += amount;
+  },
+});
+
+// 3. Write a story that dispatches effects (and can read state mid-flight).
+function* countingLogic() {
+  yield* askStateDispatch<CounterEffects>({ type: 'counter/Increment', payload: undefined });
+  yield* askStateDispatchEffect<AddEffect>('counter/Add', 5);
+
+  const soFar = yield* askStateRead<CounterState>();
+  // soFar === { count: 6 }
+
+  yield* askStateDispatch<CounterEffects>({ type: 'counter/Increment', payload: undefined });
+}
+
+// 4. Reduce the story into a final state.
+export function* askComputeCount() {
+  const finalState = yield* askReduceState<CounterState, CounterEffects>(
+    { count: 0 },
+    counterReducer,
+    countingLogic,
+  );
+
+  return finalState.count; // 7
+}
+```
+
+## Signature
+
+```typescript
+function* askReduceState<State, Effect>(
+  initialState: State,
+  reducer: QpqReducer<State, Effect>,
+  story: () => AskResponse<void>,
+): AskResponse<State>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `initialState` | `State` | The starting state. Dispatched effects are reduced onto this value. |
+| `reducer` | `QpqReducer<State, Effect>` | A reducer that maps `(state, effect)` to `[nextState, handled]` — see [reducers](#reducers) below. Usually built with [`buildEffectReducer`](#buildeffectreducer--buildmutableeffectreducer) or `buildMutableEffectReducer`. |
+| `story` | `() => AskResponse<void>` | A **factory** that returns the inner story to run. Its `askStateDispatch` / `askStateRead` actions are intercepted; every other action bubbles through to the outer runtime unchanged. |
+
+## Returns
+
+`State` — the accumulated state after the inner story runs to completion. Reads inside the story see the state as-of that point; the returned value is the final state.
+
+## Reducers
+
+A quidproquo reducer is a plain function that returns a tuple of `[nextState, handled]`:
+
+```typescript
+type QpqReducer<State, Effect> = (state: State, effect: Effect) => [State, boolean];
+```
+
+The second element, `handled`, is what makes effects composable: `true` means this reducer owned the effect and `nextState` is authoritative; `false` means it ignored the effect (and returned `state` unchanged). Inside `askReduceState`, an unhandled effect (`false`) is **relayed outward** — to a parent `askReduceState` or the runtime — rather than dropped, so nested reducers can each own their own slice of effects.
+
+### `buildEffectReducer` / `buildMutableEffectReducer`
+
+You rarely write the tuple by hand. Both helpers turn a map of `{ [effectType]: handler }` into a `QpqReducer`, returning `[handledState, true]` when a handler matches the effect's `type` and `[state, false]` otherwise:
+
+- **`buildEffectReducer`** — handlers are **immutable**: each returns the next state. Good for simple, flat state.
+
+  ```typescript
+  const counterReducer = buildEffectReducer<CounterState, CounterEffects>({
+    'counter/Increment': (state) => ({ ...state, count: state.count + 1 }),
+    'counter/Add': (state, amount) => ({ ...state, count: state.count + amount }),
+  });
+  ```
+
+- **`buildMutableEffectReducer`** — handlers **mutate a draft** and return nothing; it wraps them in [Immer](https://immerjs.github.io/immer/)'s `produce`, so you get immutable updates while writing imperative code. Best for deeply nested state.
+
+  ```typescript
+  const counterReducer = buildMutableEffectReducer<CounterState, CounterEffects>({
+    'counter/Increment': (state) => { state.count += 1; },
+    'counter/Add': (state, amount) => { state.count += amount; },
+  });
+  ```
+
+In both, each handler receives `(state, payload)` — the effect's `payload` is passed directly, already narrowed to the type for that effect case.
+
+### `combineQpqReducers`
+
+Composes two reducers into one that handles the **union** of their effects. It tries the first reducer; if that returns `handled: true` it wins, otherwise the (possibly-updated) state is passed to the second:
+
+```typescript
+import { combineQpqReducers } from 'quidproquo-core';
+
+const appReducer = combineQpqReducers(counterReducer, markReducer);
+// handles CounterEffects | MarkEffects
+```
+
+Chain calls to combine more than two. The result is a `QpqReducer` you can pass straight to `askReduceState`.
+
+## `replayEffects`
+
+`askReduceState` reduces effects **live** as a story dispatches them. `replayEffects` is its synchronous, event-sourcing counterpart: given a stored **array** of effects, it reduces them into state with no story and no generator involved:
+
+```typescript
+import { replayEffects } from 'quidproquo-core';
+
+const state = replayEffects({ count: 0 }, counterReducer, [
+  { type: 'counter/Add', payload: 5 },
+  { type: 'counter/Increment', payload: undefined },
+]);
+// { count: 6 }
+```
+
+Effects the reducer doesn't handle leave the state unchanged and are skipped. Use it to rebuild current state from a persisted effect log.
+
+## Notes
+
+- The inner story runs with **no live State runtime**: because every state action is captured here, a `story` that only dispatches/reads state completes synchronously (the generator finishes on the first `next()`).
+- Non-state actions are **not** captured — they bubble to the outer runtime as normal, so a story can freely mix state dispatches with other actions like `askRandomNumber` or `askNetworkRequest`.
+- `askReduceState` nests: an inner call owns its own state and reducer, and effects its reducer doesn't handle bubble up to the enclosing `askReduceState`. Reads always resolve against the nearest enclosing call's state.
+- Dispatch and read outcomes are correctly shaped for `askCatch` (they wrap exactly once), so wrapping `askStateDispatch`/`askStateRead` in `askCatch` behaves as expected.
+
+## Related
+
+- [askStateDispatch](./ask-state-dispatch.md) — dispatch the effects this story reduces.
+- [askStateRead](./ask-state-read.md) — read the accumulated state mid-story.
+- [defineStateDispatchOverWebsockets](../../../config/webserver/state-dispatch-over-websockets.md) — stream reduced dispatches to a WebSocket client.

package/template/docusaurus/docs/actions/core/state/ask-state-dispatch.md

@@ -0,0 +1,87 @@
+---
+title: askStateDispatch
+description: Dispatch an action (effect) into the surrounding reducer to update in-story state.
+---
+
+# askStateDispatch
+
+Dispatches an action — an **effect** — into the state reducer that surrounds the story, Redux-style. The dispatch itself carries no return value; it exists to update the accumulated state, which you later read back with [askStateRead](./ask-state-read.md). What actually consumes the dispatch depends on the runtime: [askReduceState](./ask-reduce-state.md) captures it and runs it through your reducer, while the React `useQPQ` hooks forward it to a `React.Dispatch`.
+
+- **Action type:** `StateActionType.Dispatch`
+
+```typescript
+import { askStateDispatch } from 'quidproquo-core';
+
+// CounterEffects is your effect union, e.g. Effect<'counter/Add', number>
+export function* askAddToCounter(amount: number) {
+  yield* askStateDispatch<CounterEffects>({ type: 'counter/Add', payload: amount });
+}
+```
+
+## Signature
+
+```typescript
+function* askStateDispatch<T>(action: T): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `action` | `T` | The action/effect to dispatch. In practice `T` is an [`Effect`](#effect-and-askstatedispatcheffect) — a `{ type, payload }` object — matching one of the cases your reducer handles. |
+
+## Returns
+
+`void` — a dispatch produces no value. It updates the surrounding state as a side effect; use [askStateRead](./ask-state-read.md) to observe the result.
+
+## `Effect` and `askStateDispatchEffect`
+
+An **effect** is the unit of state change dispatched here. It is just a typed, tagged payload:
+
+```typescript
+type Effect<TType extends string, TPayload = undefined> = {
+  type: TType;
+  payload: TPayload;
+};
+```
+
+You typically model your effects as a union of `Effect<...>` types and give each a reducer case:
+
+```typescript
+import { Effect } from 'quidproquo-core';
+
+type IncrementEffect = Effect<'counter/Increment'>;        // payload: undefined
+type AddEffect = Effect<'counter/Add', number>;            // payload: number
+type CounterEffects = IncrementEffect | AddEffect;
+```
+
+`askStateDispatchEffect` is a thin convenience wrapper over `askStateDispatch` that builds the `{ type, payload }` object for you from the type and payload arguments — handy for effects, especially payload-less ones:
+
+```typescript
+import { askStateDispatchEffect } from 'quidproquo-core';
+
+export function* askBumpCounter() {
+  yield* askStateDispatchEffect<IncrementEffect>('counter/Increment'); // payload defaults to undefined
+  yield* askStateDispatchEffect<AddEffect>('counter/Add', 5);
+}
+```
+
+Its signature is:
+
+```typescript
+function* askStateDispatchEffect<E extends Effect<any, any>>(
+  type: E['type'],
+  payload?: E['payload'],
+): AskResponse<void>;
+```
+
+## Notes
+
+- Dispatch is fire-and-forget from the story's point of view — there is no acknowledgement value, only the state mutation it triggers.
+- When [askReduceState](./ask-reduce-state.md) surrounds the story and its reducer does **not** handle a dispatched effect, the effect bubbles outward to a parent `askReduceState` (or the outer runtime) instead of being silently dropped.
+
+## Related
+
+- [askStateRead](./ask-state-read.md) — read the state that dispatches accumulate into.
+- [askReduceState](./ask-reduce-state.md) — run a story purely for its dispatched effects and return the reduced state.
+- [defineStateDispatchOverWebsockets](../../../config/webserver/state-dispatch-over-websockets.md) — redirect these dispatches to a connected WebSocket client.

package/template/docusaurus/docs/actions/core/state/ask-state-read.md

@@ -0,0 +1,45 @@
+---
+title: askStateRead
+description: Read the current in-story state accumulated from dispatched effects.
+---
+
+# askStateRead
+
+Reads the current state that surrounds the story — the value accumulated from every [askStateDispatch](./ask-state-dispatch.md) processed so far. It is the read side of quidproquo's Redux-style in-story state: dispatch mutates, `askStateRead` observes. Under [askReduceState](./ask-reduce-state.md) it returns the whole reduced state; under the React `useQPQ` runtime it returns the current store state.
+
+- **Action type:** `StateActionType.Read`
+
+```typescript
+import { askStateRead } from 'quidproquo-core';
+
+export function* askGetCount() {
+  const state = yield* askStateRead<CounterState>();
+  return state.count;
+}
+```
+
+## Signature
+
+```typescript
+function* askStateRead<R>(path?: string): AskResponse<R>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | Optional. Reserved for reading a sub-path of the state. **Path reads are not supported by any current runtime** — the whole state is always returned regardless of `path`. |
+
+## Returns
+
+`R` — the current accumulated state. The generic `R` is the shape you expect the state to have; it is returned as-is, so it is your responsibility to type it correctly.
+
+## Notes
+
+- The value reflects the state **at the point of the read** — reads issued between dispatches see the partially-accumulated state, not the final one.
+- Under [askReduceState](./ask-reduce-state.md), a read always returns that call's own accumulated state — a nested `askReduceState` reads its inner state, not the parent's.
+
+## Related
+
+- [askStateDispatch](./ask-state-dispatch.md) — dispatch effects that update the state this reads.
+- [askReduceState](./ask-reduce-state.md) — run a story purely for its dispatched effects and return the reduced state.

package/template/docusaurus/docs/actions/core/stream/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Stream",
+  "link": {
+    "type": "generated-index",
+    "description": "Streams read data incrementally in chunks — opened by actions like askFileStreamOpen and askAiPromptStream, consumed with askStreamRead / askStreamProcess / askStreamMap."
+  }
+}

package/template/docusaurus/docs/actions/core/stream/ask-stream-close.md

@@ -0,0 +1,56 @@
+---
+title: askStreamClose
+description: Release an open stream handle and free its underlying source.
+---
+
+# askStreamClose
+
+Releases an open stream, freeing the underlying source (a file body, a model response, etc.) held by the runtime's stream registry. Call it once you have finished reading — including on early exit, before the stream reports `done`.
+
+- **Action type:** `StreamActionType.Close`
+
+```typescript
+import { askFileStreamOpen, askStreamRead, askStreamClose } from 'quidproquo-core';
+
+export function* askReadFirstChunk(filepath: string) {
+  const handle = yield* askFileStreamOpen('logs', filepath, 'text');
+
+  const chunk = yield* askStreamRead(handle);
+
+  // We only wanted the first chunk — release the rest of the stream.
+  yield* askStreamClose(handle);
+
+  return chunk.data ?? '';
+}
+```
+
+## Signature
+
+```typescript
+function* askStreamClose(
+  handle: StreamHandle,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `handle` | `StreamHandle` | The handle returned by the action that opened the stream. Only its `id` is used to locate and release the stream. |
+
+## Returns
+
+`void` — the story resumes once the stream has been released.
+
+## Notes
+
+- Closing a stream that has already been closed (or that finished and was released automatically) is a no-op — it does not throw.
+- The stream stories [askStreamProcess](./ask-stream-process.md) and [askStreamMap](./ask-stream-map.md) close the handle for you after they finish reading, so you only call `askStreamClose` directly when you drive the read loop yourself or bail out early.
+
+## Related
+
+- [askStreamRead](./ask-stream-read.md) — pull chunks from the handle before closing it.
+- [askStreamProcess](./ask-stream-process.md) — reads to completion and closes for you.
+- [askStreamMap](./ask-stream-map.md) — collects into an array and closes for you.
+- [askFileStreamOpen](../file/ask-file-stream-open.md) — opens the stream this action releases.
+- [askAiPromptStream](../ai/ask-ai-prompt-stream.md) — opens a model-response stream.

package/template/docusaurus/docs/actions/core/stream/ask-stream-map.md

@@ -0,0 +1,73 @@
+---
+title: askStreamMap
+description: Read an open stream to completion, transform each chunk, collect the results into an array, then close it.
+---
+
+# askStreamMap
+
+Drives an open stream to completion and collects it into an array. It reads chunk after chunk, runs an optional transform callback on each one, pushes the result, and closes the stream when it reports `done`. Use it when you want the *whole* stream materialised as a list — e.g. gather every event of a model response, or turn a streamed file's chunks into an array of parsed records.
+
+`askStreamMap` is not a distinct action; it is a story composed of [askStreamRead](./ask-stream-read.md) and [askStreamClose](./ask-stream-close.md). It reads in the default blocking mode, skips any chunk whose `data` is `undefined` or that is marked `skipped`, stops on `done`, and always closes the handle before returning the collected array. When no callback is supplied, the chunks are collected as-is.
+
+```typescript
+import { askAiPromptStream, askStreamMap, AiModel } from 'quidproquo-core';
+
+export function* askCollectStreamedParts(prompt: string) {
+  const stream = yield* askAiPromptStream(AiModel.ClaudeSonnet46, prompt);
+
+  // No callback — collect every AiStreamPart into an array.
+  const parts = yield* askStreamMap(stream);
+
+  return parts;
+}
+```
+
+With a transform callback, map each chunk to a value of your choosing:
+
+```typescript
+import { askFileStreamOpen, askStreamMap } from 'quidproquo-core';
+
+export function* askChunkLengths(filepath: string) {
+  const handle = yield* askFileStreamOpen('logs', filepath, 'text');
+
+  const lengths = yield* askStreamMap(handle, function* (chunk, index) {
+    return chunk.length;
+  });
+
+  return lengths;
+}
+```
+
+## Signature
+
+```typescript
+function* askStreamMap<E extends StreamEncoding, T, R = StreamDataType<E, T>>(
+  handle: StreamHandle<E, T>,
+  askCallback?: (item: StreamDataType<E, T>, index: number) => AskResponse<R>,
+): AskResponse<R[]>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `handle` | `StreamHandle<E, T>` | The handle returned by the action that opened the stream, e.g. [askFileStreamOpen](../file/ask-file-stream-open.md) or [askAiPromptStream](../ai/ask-ai-prompt-stream.md). |
+| `askCallback` | `(item, index) => AskResponse<R>` | Optional story (generator) run once per delivered chunk to transform it. `item` is the decoded chunk; `index` is its 0-based position among delivered chunks. Defaults to a pass-through that collects the chunks unchanged. Skipped / empty chunks are not passed to it. |
+
+## Returns
+
+`R[]` — an array of the callback's results in stream order (or the raw chunks when no callback is given). Resolves once the stream is exhausted and closed.
+
+## Notes
+
+- The `index` counts only chunks handed to your callback — chunks that are `skipped` or carry no `data` are dropped and do not advance it.
+- The handle is closed for you when the loop ends.
+- Because it buffers the entire stream in memory, prefer [askStreamProcess](./ask-stream-process.md) when you only need to react to each chunk and don't need the full list.
+
+## Related
+
+- [askStreamProcess](./ask-stream-process.md) — the per-chunk counterpart; returns `void`.
+- [askStreamRead](./ask-stream-read.md) / [askStreamClose](./ask-stream-close.md) — the actions this story is built from.
+- [askAiPromptStream](../ai/ask-ai-prompt-stream.md) — collect a model response into an array of events.
+- [askFileStreamOpen](../file/ask-file-stream-open.md) — stream a large file chunk by chunk.
+- [askEventDocAiProcessSend](../../features/event-doc-ai/ask-event-doc-ai-process-send.md) — uses this to dispatch each AI stream part to the chat UI.

package/template/docusaurus/docs/actions/core/stream/ask-stream-process.md

@@ -0,0 +1,57 @@
+---
+title: askStreamProcess
+description: Read an open stream to completion, running a callback for each chunk, then close it.
+---
+
+# askStreamProcess
+
+Drives an open stream to completion: it reads chunk after chunk, invokes your callback for each one, and closes the stream when the stream reports `done`. Use it when you want to *react* to each chunk as it arrives — forwarding tokens to a client, tallying a running total — without accumulating a result.
+
+`askStreamProcess` is not a distinct action; it is a story composed of [askStreamRead](./ask-stream-read.md) and [askStreamClose](./ask-stream-close.md). It reads in the default blocking mode, skips any chunk whose `data` is `undefined` or that is marked `skipped`, stops on `done`, and always closes the handle before returning.
+
+```typescript
+import { askAiPromptStream, askStreamProcess, AiModel, AiStreamPartType } from 'quidproquo-core';
+
+export function* askAnswerStreamed(prompt: string) {
+  const stream = yield* askAiPromptStream(AiModel.ClaudeSonnet46, prompt);
+
+  yield* askStreamProcess(stream, function* (part, index) {
+    if (part.type === AiStreamPartType.TextDelta) {
+      // forward part.text to the client...
+    }
+  });
+}
+```
+
+## Signature
+
+```typescript
+function* askStreamProcess<E extends StreamEncoding, T>(
+  handle: StreamHandle<E, T>,
+  askCallback: (item: StreamDataType<E, T>, index: number) => AskResponse<void>,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `handle` | `StreamHandle<E, T>` | The handle returned by the action that opened the stream, e.g. [askFileStreamOpen](../file/ask-file-stream-open.md) or [askAiPromptStream](../ai/ask-ai-prompt-stream.md). |
+| `askCallback` | `(item, index) => AskResponse<void>` | A story (generator) run once per delivered chunk. `item` is the decoded chunk (`string`, `Uint8Array`, or the parsed object, per the handle's encoding); `index` is its 0-based position among delivered chunks. Skipped / empty chunks are not passed to it. |
+
+## Returns
+
+`void` — resolves once the stream is exhausted and closed.
+
+## Notes
+
+- The `index` counts only chunks handed to your callback — chunks that are `skipped` or carry no `data` are dropped and do not advance it.
+- The handle is closed for you when the loop ends. If you need finer control — reading only part of a stream, or polling with `noWait` — drive [askStreamRead](./ask-stream-read.md) / [askStreamClose](./ask-stream-close.md) directly instead.
+- To build up a result rather than react to each chunk, use [askStreamMap](./ask-stream-map.md).
+
+## Related
+
+- [askStreamMap](./ask-stream-map.md) — the collecting counterpart; returns an array.
+- [askStreamRead](./ask-stream-read.md) / [askStreamClose](./ask-stream-close.md) — the actions this story is built from.
+- [askAiPromptStream](../ai/ask-ai-prompt-stream.md) — a common source of streams to process.
+- [askFileStreamOpen](../file/ask-file-stream-open.md) — stream a large file chunk by chunk.