stitchkit 0.111.1 → 0.111.2

package/CHANGELOG.md

@@ -15,6 +15,12 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.111.2] - 2026-10-17
+
+### Added
+
+- `stitchkit/process`: `streamNativeCommand` starts a command like `runNativeCommand` and returns its stdout and stderr as `ReadableStream<Uint8Array>` while it runs, with `result` and `stop()`. It uses the same owner, so a stream keeps the group ownership, the `stop` policy, the bounds and every group-stop fix of `runNativeCommand`; a slow reader slows the child through pipe backpressure. The `stitchkit/process` surface ceiling rises from 12 to 15 for `streamNativeCommand` and its two types.
+
 ## [0.111.1] - 2026-10-17
 
 ### Fixed

package/dist/entrypoints/process.d.ts

@@ -2,4 +2,5 @@
 export { observeProcessInstance, type ProcessInstance, type ProcessInstanceObservation, ProcessInstanceSchema, type ProcessOwnerEvidence, probeProcessOwner, } from '../internal/process-instance.js';
 export { runNativeCommand } from '../process/command.js';
 export { NativeCommandError, type NativeCommandOptions, type NativeCommandResult, type NativeCommandSettlement, type NativeCommandStopPolicy, } from '../process/contract.js';
+export { type NativeCommandStream, type NativeCommandStreamOptions, streamNativeCommand, } from '../process/stream.js';
 //# sourceMappingURL=process.d.ts.map

package/dist/entrypoints/process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/entrypoints/process.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,OAAO,EACL,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,iBAAiB,GAClB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EACL,kBAAkB,EAClB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,GAC7B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/entrypoints/process.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,OAAO,EACL,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,iBAAiB,GAClB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EACL,kBAAkB,EAClB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,GAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,mBAAmB,GACpB,MAAM,mBAAmB,CAAC"}

package/dist/entrypoints/process.js

@@ -10,14 +10,89 @@ import {
 import {
   startNativeCommand
 } from "../index-7r4knwf8.js";
+import {
+  untilAborted
+} from "../index-a5qr2rj6.js";
 // src/process/command.ts
 function runNativeCommand(input) {
   return startNativeCommand(input).result;
 }
+// src/process/stream.ts
+function streamNativeCommand(input) {
+  for (const owned of ["capture", "onOutput", "stdio"])
+    if (owned in input)
+      throw new TypeError(`streamNativeCommand owns ${owned}`);
+  const channels = { stdout: channel(), stderr: channel() };
+  const owner = startNativeCommand({
+    ...input,
+    onOutput: async (bytes, name, signal) => {
+      await channels[name].push(Uint8Array.from(bytes), signal);
+    }
+  });
+  owner.result.then(() => {
+    channels.stdout.close();
+    channels.stderr.close();
+  }, (error) => {
+    channels.stdout.fail(error);
+    channels.stderr.fail(error);
+  });
+  return {
+    stdout: channels.stdout.stream,
+    stderr: channels.stderr.stream,
+    result: owner.result,
+    stop: () => owner.stop()
+  };
+}
+var QUEUED_BYTES = 1024 * 1024;
+function channel() {
+  let controller;
+  let cancelled = false;
+  let settled = false;
+  let resume = Promise.withResolvers();
+  const stream = new ReadableStream({
+    start(c) {
+      controller = c;
+    },
+    pull() {
+      resume.resolve();
+    },
+    cancel() {
+      cancelled = true;
+      resume.resolve();
+    }
+  }, new ByteLengthQueuingStrategy({ highWaterMark: QUEUED_BYTES }));
+  return {
+    stream,
+    async push(bytes, signal) {
+      if (cancelled || settled)
+        return;
+      controller.enqueue(bytes);
+      while (!cancelled && !signal.aborted && (controller.desiredSize ?? 0) <= 0) {
+        resume = Promise.withResolvers();
+        await untilAborted(resume.promise, signal).catch(() => {
+          return;
+        });
+      }
+    },
+    close() {
+      if (cancelled || settled)
+        return;
+      settled = true;
+      controller.close();
+    },
+    fail(error) {
+      if (cancelled || settled)
+        return;
+      settled = true;
+      controller.error(error);
+    }
+  };
+}
 export {
   NativeCommandError2 as NativeCommandError,
   ProcessInstanceSchema2 as ProcessInstanceSchema,
   observeProcessInstance2 as observeProcessInstance,
   probeProcessOwner2 as probeProcessOwner,
-  runNativeCommand
+  runNativeCommand,
+  streamNativeCommand
 };

package/dist/process/stream.d.ts

@@ -0,0 +1,27 @@
+import type { NativeCommandOptions, NativeCommandResult } from './contract.js';
+/** Options the stream owns: its readers are the capture, the sink and the pipes. */
+export type NativeCommandStreamOptions = Omit<NativeCommandOptions, 'capture' | 'onOutput' | 'stdio'>;
+/** A started command whose output is read as it appears. */
+export interface NativeCommandStream {
+    /** The leader's stdout; closes once the command finished and every byte was queued. */
+    readonly stdout: ReadableStream<Uint8Array>;
+    readonly stderr: ReadableStream<Uint8Array>;
+    /**
+     * Settles like `runNativeCommand` once the command ended and both streams were read to the end
+     * or cancelled: a stream nobody reads holds the child back, and with it this result. Its
+     * `stdout` and `stderr` are empty, the streams hold the bytes.
+     */
+    readonly result: Promise<NativeCommandResult>;
+    /** Stops the command with its stop policy and resolves once its resources are proven closed. */
+    stop(): Promise<void>;
+}
+/**
+ * Starts one command directly (no shell) like `runNativeCommand`, with the same group ownership,
+ * stop policy and bounds, and hands its output over as `ReadableStream`s instead of buffering it
+ * for the end. A slow reader slows the child (pipe backpressure); a cancelled stream drops what
+ * follows without stopping the command. When the command fails or is stopped, both streams error and
+ * the bytes still queued are dropped. A stream nobody reads holds the child back
+ * once it queued 1 MiB, so read large outputs concurrently or cancel the stream.
+ */
+export declare function streamNativeCommand(input: NativeCommandStreamOptions): NativeCommandStream;
+//# sourceMappingURL=stream.d.ts.map

package/dist/process/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/process/stream.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE5E,oFAAoF;AACpF,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAC3C,oBAAoB,EACpB,SAAS,GAAG,UAAU,GAAG,OAAO,CACjC,CAAC;AAEF,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC9C,gGAAgG;IAChG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,0BAA0B,GAAG,mBAAmB,CA0B1F"}

package/llms/process.2.txt

@@ -0,0 +1,32 @@
+# stitchkit/process — stitchkit docs slice, part 2 of 2
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Parts of this slice:
+- `llms/process.txt`: Guide: Native IO  (docs/guide/native-io.md)
+- `llms/process.2.txt`: API reference: `stitchkit/process`  (docs/api/reference.md)
+
+==============================================================================
+# API reference: `stitchkit/process`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/process`
+
+Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/native-io.md).
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `runNativeCommand` | function | caller-lifetime streaming or explicitly bounded binary capture |
+| `streamNativeCommand` | function | starts a command under the same group ownership, stop policy and bounds as `runNativeCommand` and returns `stdout` / `stderr` as `ReadableStream<Uint8Array>`, `result` and `stop()`; a slow reader slows the child, a cancelled stream drops its bytes, a failed command errors both streams |
+| `NativeCommandStream` | type | what `streamNativeCommand` returns: `stdout`, `stderr`, `result` (its buffers are empty) and `stop()` |
+| `NativeCommandStreamOptions` | type | `NativeCommandOptions` without `capture`, `onOutput` and `stdio`, which the streams own |
+| `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink, finite cleanup limits, the `stop` policy and `descendants` (`'terminate-after-leader'`, the default: stop the group after the leader exits, or `'leave'`); `stdio` (`'pipe'`, or `'inherit'` for the caller's descriptors, refusing the pipe-only options) and `group` (`'own'`, or `'caller'`: joins the caller's process group, stops only the leader, refuses `descendants`, `ownerLoss` and a group stop); `ownerLoss: 'terminate'` (optional Linux/Darwin Bun/Node guard: kernel channel EOF after abrupt caller death KILLs its owned group, unsupported platforms refuse); `onLeaderStarted({ pid })` (once after the group leader exists; the package guard's PID under `ownerLoss`), `drainTimeoutMs` (bound on the pipes staying open after the leader exited, `COMMAND_CLEANUP`); an unknown key is refused by name, a removed one (`killGraceMs`) with its replacement |
+| `NativeCommandStopPolicy` | type | how a cancelled command stops: `target` `'group'` (signal every member) or `'leader'` (signal only the leader; its exit ends the grace), `signal` (default `SIGTERM`), `graceMs` (at most one hour) before KILL to the group, and `killOn`, an `AbortSignal` that skips the grace; default `{ target: 'group', signal: 'SIGTERM', graceMs: 100 }` |
+| `NativeCommandResult` | type | observed nullable exit code/signal, `descendantsStopped` (members left in the group after the leader exited were stopped) and captured stdout/stderr bytes |
+| `NativeCommandError` | class | COMMAND_LIMIT with machine reason `deadline` or `output-budget`; COMMAND_UNAVAILABLE / COMMAND_CLEANUP have no limit reason; COMMAND_CLEANUP means the command's resources were not proven closed, either past `cleanupTimeoutMs` after a stop or past `drainTimeoutMs` after the leader exited, and `cause` holds that bound's failure. Preserves internal cause and existing constructor; caller-created limits without supplied reason remain unclassified |
+
+| `NativeCommandSettlement` | type | `exit` (the leader ended on its own), `stopped` (the command was stopped and the leader's exit after the stop observed: the stop's `cause` with `exitCode`/`signal`) or `error` (no exit observed), including synchronous native launch failure; `onLeaderSettled` runs once before drain, bounded by cleanupTimeoutMs, with a cancellable settlement signal; schema/pre-abort refusal creates no settlement obligation |
+| `observeProcessInstance` / `ProcessInstanceObservation` | function / type | Linux/Darwin lifetime observation; observed identity or unavailable with its original cause, never guessed absence |
+| `ProcessInstanceSchema` / `ProcessInstance` | schema / type | platform, boot ID, namespace and process start identity from the shared native reader |
+| `probeProcessOwner` / `ProcessOwnerEvidence` | function / type | compare lifetimes on one caller-established machine; matched, boot change, reused PID, gone, legacy or unavailable with cause |

package/llms/process.txt

@@ -1,9 +1,12 @@
-# stitchkit/process — stitchkit docs slice
+# stitchkit/process — stitchkit docs slice, part 1 of 2
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
+> Continues in `llms/process.2.txt`.
 
-Contains: Guide: Native IO  (docs/guide/native-io.md) · API reference: `stitchkit/process`  (docs/api/reference.md)
+Parts of this slice:
+- `llms/process.txt`: Guide: Native IO  (docs/guide/native-io.md)
+- `llms/process.2.txt`: API reference: `stitchkit/process`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: Native IO  (docs/guide/native-io.md)
@@ -147,6 +150,27 @@ await runNativeCommand({
 })
 ```
 
+To read output as it appears, use `streamNativeCommand`: the same owner, group ownership, `stop`
+policy and bounds, with the output as `ReadableStream<Uint8Array>`.
+
+```ts
+import { streamNativeCommand } from 'stitchkit/process'
+
+const lifetime = new AbortController()
+const command = streamNativeCommand({
+  executable: '/usr/bin/tail', args: ['-f', '/var/log/app.log'], signal: lifetime.signal,
+})
+void command.stderr.cancel() // not interested: dropped, the command keeps running
+for await (const bytes of command.stdout) handle(bytes) // a slow reader slows the child
+await command.result // settles like `runNativeCommand`; `stop()` ends the group and waits for it
+```
+
+The streams own `capture`, `onOutput` and `stdio`; passing one is refused. Each stream queues up to 1 MiB, so
+a small output can be read in any order, even after `result`; past that an unread stream fills its pipe
+and holds the command, and its `result`, until the signal or `timeoutMs`, so read large outputs
+concurrently or cancel the stream you ignore. Cancelling a stream drops its later bytes and leaves the command running. When the
+command fails or is stopped, both streams error and the bytes still queued are dropped.
+
 A command needs a caller `signal` or a finite `timeoutMs` (1 to 2147483647 ms, the native timer
 range; a larger value is refused, never turned into 1 ms). Streaming runs for the caller's lifetime,
 with no hidden 60-second timeout or 1 MiB output limit. `capture` defaults to false; `true` requires
@@ -698,24 +722,3 @@ A sandbox admission slot is released once a direct command's pipes have closed a
 A `COMMAND_CLEANUP` outcome means the death of its group was not proven, so the slot stays
 occupied, `stop` keeps rejecting with the cleanup error, and the sandbox session is recreated to
 recover.
-
-==============================================================================
-# API reference: `stitchkit/process`  (docs/api/reference.md)
-==============================================================================
-
-## `stitchkit/process`
-
-Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/native-io.md).
-
-| Export | Kind | Purpose |
-|---|---|---|
-| `runNativeCommand` | function | caller-lifetime streaming or explicitly bounded binary capture |
-| `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink, finite cleanup limits, the `stop` policy and `descendants` (`'terminate-after-leader'`, the default: stop the group after the leader exits, or `'leave'`); `stdio` (`'pipe'`, or `'inherit'` for the caller's descriptors, refusing the pipe-only options) and `group` (`'own'`, or `'caller'`: joins the caller's process group, stops only the leader, refuses `descendants`, `ownerLoss` and a group stop); `ownerLoss: 'terminate'` (optional Linux/Darwin Bun/Node guard: kernel channel EOF after abrupt caller death KILLs its owned group, unsupported platforms refuse); `onLeaderStarted({ pid })` (once after the group leader exists; the package guard's PID under `ownerLoss`), `drainTimeoutMs` (bound on the pipes staying open after the leader exited, `COMMAND_CLEANUP`); an unknown key is refused by name, a removed one (`killGraceMs`) with its replacement |
-| `NativeCommandStopPolicy` | type | how a cancelled command stops: `target` `'group'` (signal every member) or `'leader'` (signal only the leader; its exit ends the grace), `signal` (default `SIGTERM`), `graceMs` (at most one hour) before KILL to the group, and `killOn`, an `AbortSignal` that skips the grace; default `{ target: 'group', signal: 'SIGTERM', graceMs: 100 }` |
-| `NativeCommandResult` | type | observed nullable exit code/signal, `descendantsStopped` (members left in the group after the leader exited were stopped) and captured stdout/stderr bytes |
-| `NativeCommandError` | class | COMMAND_LIMIT with machine reason `deadline` or `output-budget`; COMMAND_UNAVAILABLE / COMMAND_CLEANUP have no limit reason; COMMAND_CLEANUP means the command's resources were not proven closed, either past `cleanupTimeoutMs` after a stop or past `drainTimeoutMs` after the leader exited, and `cause` holds that bound's failure. Preserves internal cause and existing constructor; caller-created limits without supplied reason remain unclassified |
-
-| `NativeCommandSettlement` | type | `exit` (the leader ended on its own), `stopped` (the command was stopped and the leader's exit after the stop observed: the stop's `cause` with `exitCode`/`signal`) or `error` (no exit observed), including synchronous native launch failure; `onLeaderSettled` runs once before drain, bounded by cleanupTimeoutMs, with a cancellable settlement signal; schema/pre-abort refusal creates no settlement obligation |
-| `observeProcessInstance` / `ProcessInstanceObservation` | function / type | Linux/Darwin lifetime observation; observed identity or unavailable with its original cause, never guessed absence |
-| `ProcessInstanceSchema` / `ProcessInstance` | schema / type | platform, boot ID, namespace and process start identity from the shared native reader |
-| `probeProcessOwner` / `ProcessOwnerEvidence` | function / type | compare lifetimes on one caller-established machine; matched, boot change, reused PID, gone, legacy or unavailable with cause |

package/llms-full.txt

@@ -8586,6 +8586,27 @@ await runNativeCommand({
 })
 ```
 
+To read output as it appears, use `streamNativeCommand`: the same owner, group ownership, `stop`
+policy and bounds, with the output as `ReadableStream<Uint8Array>`.
+
+```ts
+import { streamNativeCommand } from 'stitchkit/process'
+
+const lifetime = new AbortController()
+const command = streamNativeCommand({
+  executable: '/usr/bin/tail', args: ['-f', '/var/log/app.log'], signal: lifetime.signal,
+})
+void command.stderr.cancel() // not interested: dropped, the command keeps running
+for await (const bytes of command.stdout) handle(bytes) // a slow reader slows the child
+await command.result // settles like `runNativeCommand`; `stop()` ends the group and waits for it
+```
+
+The streams own `capture`, `onOutput` and `stdio`; passing one is refused. Each stream queues up to 1 MiB, so
+a small output can be read in any order, even after `result`; past that an unread stream fills its pipe
+and holds the command, and its `result`, until the signal or `timeoutMs`, so read large outputs
+concurrently or cancel the stream you ignore. Cancelling a stream drops its later bytes and leaves the command running. When the
+command fails or is stopped, both streams error and the bytes still queued are dropped.
+
 A command needs a caller `signal` or a finite `timeoutMs` (1 to 2147483647 ms, the native timer
 range; a larger value is refused, never turned into 1 ms). Streaming runs for the caller's lifetime,
 with no hidden 60-second timeout or 1 MiB output limit. `capture` defaults to false; `true` requires
@@ -23566,6 +23587,9 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 | Export | Kind | Purpose |
 |---|---|---|
 | `runNativeCommand` | function | caller-lifetime streaming or explicitly bounded binary capture |
+| `streamNativeCommand` | function | starts a command under the same group ownership, stop policy and bounds as `runNativeCommand` and returns `stdout` / `stderr` as `ReadableStream<Uint8Array>`, `result` and `stop()`; a slow reader slows the child, a cancelled stream drops its bytes, a failed command errors both streams |
+| `NativeCommandStream` | type | what `streamNativeCommand` returns: `stdout`, `stderr`, `result` (its buffers are empty) and `stop()` |
+| `NativeCommandStreamOptions` | type | `NativeCommandOptions` without `capture`, `onOutput` and `stdio`, which the streams own |
 | `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink, finite cleanup limits, the `stop` policy and `descendants` (`'terminate-after-leader'`, the default: stop the group after the leader exits, or `'leave'`); `stdio` (`'pipe'`, or `'inherit'` for the caller's descriptors, refusing the pipe-only options) and `group` (`'own'`, or `'caller'`: joins the caller's process group, stops only the leader, refuses `descendants`, `ownerLoss` and a group stop); `ownerLoss: 'terminate'` (optional Linux/Darwin Bun/Node guard: kernel channel EOF after abrupt caller death KILLs its owned group, unsupported platforms refuse); `onLeaderStarted({ pid })` (once after the group leader exists; the package guard's PID under `ownerLoss`), `drainTimeoutMs` (bound on the pipes staying open after the leader exited, `COMMAND_CLEANUP`); an unknown key is refused by name, a removed one (`killGraceMs`) with its replacement |
 | `NativeCommandStopPolicy` | type | how a cancelled command stops: `target` `'group'` (signal every member) or `'leader'` (signal only the leader; its exit ends the grace), `signal` (default `SIGTERM`), `graceMs` (at most one hour) before KILL to the group, and `killOn`, an `AbortSignal` that skips the grace; default `{ target: 'group', signal: 'SIGTERM', graceMs: 100 }` |
 | `NativeCommandResult` | type | observed nullable exit code/signal, `descendantsStopped` (members left in the group after the leader exited were stopped) and captured stdout/stderr bytes |

package/llms.txt

@@ -56,7 +56,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/node**: [llms/node.txt](llms/node.txt) 3.1 KB
 - **stitchkit/agent-runtime/react**: [llms/agent-runtime-react.txt](llms/agent-runtime-react.txt) 1.0 KB
 - **stitchkit/agent-runtime/realtime**: [llms/agent-runtime-realtime.txt](llms/agent-runtime-realtime.txt) 2.6 KB
-- **stitchkit/process**: [llms/process.txt](llms/process.txt) 45.8 KB
+- **stitchkit/process**: [llms/process.txt](llms/process.txt) 43.7 KB → [llms/process.2.txt](llms/process.2.txt) 4.3 KB
 - **stitchkit/process/owner-loss**: [llms/process-owner-loss.txt](llms/process-owner-loss.txt) 0.9 KB
 - **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 3.5 KB
 - **stitchkit/http**: [llms/http.txt](llms/http.txt) 0.9 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.111.1",
+  "version": "0.111.2",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",