@inferencesh/app 0.1.13 → 0.1.15

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/index.d.ts

@@ -2,7 +2,7 @@ export { File } from "./file.js";
 export type { FileOptions, FileData } from "./file.js";
 export { createFileSchema, isFileSchema, FILE_SCHEMA_MARKER } from "./schema.js";
 export type { Socket, Frame } from "./socket.js";
-export { createStreamSchema, media, pcm16, Live, liveFields, binaryField, STREAM_SCHEMA_MARKER, BINARY_SCHEMA_MARKER, } from "./stream.js";
+export { createStreamSchema, media, pcm16, Live, liveFields, binaryField, STREAM_SCHEMA_MARKER, CLEAR_KEY, BINARY_SCHEMA_MARKER, } from "./stream.js";
 export type { Update } from "./stream.js";
 export { StorageDir, ensureDir } from "./storage.js";
 export type { StorageDirValue } from "./storage.js";

package/dist/index.js

@@ -2,7 +2,7 @@
 export { File } from "./file.js";
 // Zod schema utilities
 export { createFileSchema, isFileSchema, FILE_SCHEMA_MARKER } from "./schema.js";
-export { createStreamSchema, media, pcm16, Live, liveFields, binaryField, STREAM_SCHEMA_MARKER, BINARY_SCHEMA_MARKER, } from "./stream.js";
+export { createStreamSchema, media, pcm16, Live, liveFields, binaryField, STREAM_SCHEMA_MARKER, CLEAR_KEY, BINARY_SCHEMA_MARKER, } from "./stream.js";
 // Storage directories
 export { StorageDir, ensureDir } from "./storage.js";
 // Download utility

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

@@ -51,6 +51,11 @@ import type { Socket } from "./socket.js";
  * The kernel's zodToJsonSchema reads this and emits `format: "stream"`.
  */
 export declare const STREAM_SCHEMA_MARKER: unique symbol;
+/**
+ * A control frame, `{"$clear": "audio"}`: drop what has been buffered of a
+ * live output field. Reserved keys start with `$`, which no field name can.
+ */
+export declare const CLEAR_KEY = "$clear";
 /**
  * Marks a binary item schema. The value on `_def` is the content type.
  * The kernel's zodToJsonSchema reads this and emits
@@ -113,6 +118,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;
@@ -122,6 +132,8 @@ export declare class Live {
     private readonly inBinary;
     private readonly outShape;
     private readonly outBinary;
+    private readonly outLive;
+    private refusedBinary;
     constructor(socket: Socket, inputData: Record<string, unknown>, inputSchema: any, outputSchema: any);
     [Symbol.asyncIterator](): AsyncGenerator<Update, void, undefined>;
     private frames;
@@ -135,5 +147,10 @@ export declare class Live {
      * `await live.send({ effect: "echo" })` are JSON frames. Keys in one call
      * other than the binary field go out together as one JSON frame.
      */
+    /**
+     * Tell the caller to drop what it has buffered of a live output field:
+     * the queued audio of an answer the user just talked over.
+     */
+    clear(field: string): Promise<void>;
     send(fields: Record<string, unknown>): Promise<void>;
 }

package/dist/stream.js

@@ -50,6 +50,11 @@
  * The kernel's zodToJsonSchema reads this and emits `format: "stream"`.
  */
 export const STREAM_SCHEMA_MARKER = Symbol.for("inferencesh.streamSchema");
+/**
+ * A control frame, `{"$clear": "audio"}`: drop what has been buffered of a
+ * live output field. Reserved keys start with `$`, which no field name can.
+ */
+export const CLEAR_KEY = "$clear";
 /**
  * Marks a binary item schema. The value on `_def` is the content type.
  * The kernel's zodToJsonSchema reads this and emits
@@ -199,6 +204,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;
@@ -208,6 +218,8 @@ export class Live {
     inBinary;
     outShape;
     outBinary;
+    outLive;
+    refusedBinary = false;
     constructor(socket, inputData, inputSchema, outputSchema) {
         this.socket = socket;
         this.input = inputData;
@@ -216,6 +228,7 @@ export class Live {
         this.inBinary = binaryField(inputSchema);
         this.outShape = shapeOf(outputSchema);
         this.outBinary = binaryField(outputSchema);
+        this.outLive = liveFields(outputSchema);
     }
     async *[Symbol.asyncIterator]() {
         for await (const frame of this.frames()) {
@@ -240,7 +253,12 @@ export class Live {
     async read(frame) {
         if (isBinaryFrame(frame)) {
             if (this.inBinary === null) {
-                await this.refuse(null, "this function takes no binary frames");
+                // Once: a caller streaming audio to the wrong function would
+                // otherwise get an error frame for every frame it sends.
+                if (!this.refusedBinary) {
+                    this.refusedBinary = true;
+                    await this.refuse(null, "this function takes no binary frames");
+                }
                 return [];
             }
             return [{ field: this.inBinary, value: toBuffer(frame) }];
@@ -258,30 +276,25 @@ export class Live {
         }
         const updates = [];
         for (const [key, raw] of Object.entries(patch)) {
-            if (Object.prototype.hasOwnProperty.call(this.inLive, key)) {
-                if (key === this.inBinary) {
-                    await this.refuse(key, "send this field's items as binary frames");
-                    continue;
-                }
-                const result = this.inLive[key].safeParse(raw);
-                if (!result.success) {
-                    await this.refuse(key, firstIssue(result));
-                    continue;
-                }
-                updates.push({ field: key, value: result.data });
+            const live = Object.prototype.hasOwnProperty.call(this.inLive, key);
+            if (!live && !Object.prototype.hasOwnProperty.call(this.inShape, key)) {
+                await this.refuse(key, "no such field");
+                continue;
             }
-            else if (Object.prototype.hasOwnProperty.call(this.inShape, key)) {
-                const result = this.inShape[key].safeParse(raw);
-                if (!result.success) {
-                    await this.refuse(key, firstIssue(result));
-                    continue;
-                }
-                this.input[key] = result.data;
-                updates.push({ field: key, value: result.data });
+            if (key === this.inBinary) {
+                await this.refuse(key, "send this field's items as binary frames");
+                continue;
             }
-            else {
-                await this.refuse(key, "no such field");
+            // A live field's items are validated against the item schema, an
+            // ordinary field against its own and then applied to the input.
+            const result = (live ? this.inLive[key] : this.inShape[key]).safeParse(raw);
+            if (!result.success) {
+                await this.refuse(key, firstIssue(result));
+                continue;
             }
+            if (!live)
+                this.input[key] = result.data;
+            updates.push({ field: key, value: result.data });
         }
         return updates;
     }
@@ -296,6 +309,16 @@ export class Live {
      * `await live.send({ effect: "echo" })` are JSON frames. Keys in one call
      * other than the binary field go out together as one JSON frame.
      */
+    /**
+     * Tell the caller to drop what it has buffered of a live output field:
+     * the queued audio of an answer the user just talked over.
+     */
+    async clear(field) {
+        if (!Object.prototype.hasOwnProperty.call(this.outLive, field)) {
+            throw new Error(`the output schema has no live field "${field}"`);
+        }
+        await this.socket.send({ [CLEAR_KEY]: field });
+    }
     async send(fields) {
         const patch = {};
         for (const [key, value] of Object.entries(fields)) {

package/package.json

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