@inferencesh/app 0.1.13 → 0.1.14

package/README.md

@@ -256,6 +256,47 @@ export class App {
 
 on the wire, a binary frame is one item of the schema's single binary live field (`pcm16(z, rate, channels)` or `media(z, contentType)`); a json text frame is a partial object keyed by field name: an item of a live field (`{"events": {"type": "interrupt"}}`) or a new value for an ordinary field (`{"effect": "robot"}`). frames that do not fit the input schema are answered with `{"error": {"field", "message"}}` and skipped. `live.send({...})` sends the output binary field as a binary frame and everything else as one json frame; unknown output fields throw.
 
+### progress from a stream function
+
+a stream function may also be an async generator (`async *dictate(input, socket)`). each yield is a progress snapshot of the task's output: it replaces the task's `output` and reaches clients as a task update (sse `/tasks/{id}/stream`), not over the socket — the socket carries the live fields. yield cumulative snapshots; the last yield is the result, so `output_meta` goes there, and a generator that ends without yielding fails the task (`NoOutput`).
+
+```javascript
+export const DictateInput = z.object({
+  audio: createStreamSchema(z, pcm16(z, 16000)),   // mic frames arrive over the socket
+});
+
+export const DictateOutput = z.object({
+  text: z.string().default(""),
+  partial: z.boolean().default(true),
+});
+
+export class App {
+  async *dictate(input, socket) {
+    const live = new Live(socket, input, DictateInput, DictateOutput);
+    let window = Buffer.alloc(0);
+    for await (const { field, value } of live) {
+      if (field === "audio") {
+        window = Buffer.concat([window, value]);
+        if (window.length >= 32000) {                       // one second of 16 khz s16le
+          yield { text: await this.transcribe(window) };    // the transcript so far
+        }
+      }
+    }
+    yield {
+      text: await this.transcribe(window),
+      partial: false,
+      output_meta: { inputs: [], outputs: [] },
+    };
+  }
+}
+```
+
+the client closing the socket ends the `for await`, so the final yield goes after the loop. both channels can be used at once: `live.send({ text })` pushes a partial over the socket for the lowest latency, while the yields build the transcript the task stores.
+
+### frames dropped when the app falls behind
+
+binary frames are perishable media, so the kernel keeps at most 256 of them queued for the app (about five seconds of 20 ms audio) and drops the oldest when the app reads slower than the client sends — latency stays bounded instead of growing for ever. text frames (commands and patches) are never dropped. `socket.dropped` counts the binary frames lost so far, and `socket.binaryBacklog = null` turns dropping off when every frame matters (a file sent in chunks).
+
 ## requirements
 
 - node.js 18.0.0 or higher

package/dist/socket.d.ts

@@ -31,6 +31,10 @@ export type Frame = Buffer | string;
 export interface Socket {
     readonly id: string;
     metadata: Record<string, unknown>;
+    /** How many binary frames the kernel has dropped because the app read too slowly. */
+    readonly dropped: number;
+    /** The most binary frames kept queued (256); null keeps every one of them. */
+    binaryBacklog: number | null;
     /** True once the client is gone or the app closed the socket. */
     readonly closed: boolean;
     /** The next frame from the client, or null once it is gone. */

package/dist/stream.d.ts

@@ -113,6 +113,11 @@ export declare function binaryField(objectSchema: any): string | null;
  *
  * A frame that does not fit the input schema is answered with
  * `{"error": {"field": ..., "message": ...}}` and skipped; the stream goes on.
+ *
+ * The function may instead be an async generator (`async *talk(inputData, socket)`):
+ * each yield is a cumulative snapshot of the task's output, sent as a task update
+ * rather than over the socket, and the last yield (after the loop, once the client
+ * closes) is the result.
  */
 export declare class Live {
     readonly socket: Socket;

package/dist/stream.js

@@ -199,6 +199,11 @@ function firstIssue(result) {
  *
  * A frame that does not fit the input schema is answered with
  * `{"error": {"field": ..., "message": ...}}` and skipped; the stream goes on.
+ *
+ * The function may instead be an async generator (`async *talk(inputData, socket)`):
+ * each yield is a cumulative snapshot of the task's output, sent as a task update
+ * rather than over the socket, and the last yield (after the loop, once the client
+ * closes) is the result.
  */
 export class Live {
     socket;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inferencesh/app",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "App framework for building inference.sh apps — File handling, output metadata, storage utilities",
   "type": "module",
   "main": "dist/index.js",