@inferencesh/app 0.1.14 → 0.1.16

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, ERROR_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, ERROR_KEY, BINARY_SCHEMA_MARKER, } from "./stream.js";
 // Storage directories
 export { StorageDir, ensureDir } from "./storage.js";
 // Download utility

package/dist/schema.d.ts

@@ -28,6 +28,7 @@ export declare const FILE_SCHEMA_MARKER: unique symbol;
  */
 export declare function createFileSchema(z: any): any;
 /**
- * Check if a Zod schema is a file schema (created by createFileSchema).
+ * Check if a Zod schema is a file schema (created by createFileSchema),
+ * through any wrapper (optional, default, nullable, ...) in zod v3 or v4.
  */
 export declare function isFileSchema(schema: any): boolean;

package/dist/schema.js

@@ -7,6 +7,7 @@
  * - Generates JSON Schema with format: "file"
  */
 import { File } from "./file.js";
+import { findMarker } from "./zod-walk.js";
 // We don't import zod directly to avoid version conflicts.
 // Instead, apps provide their own zod and we work with the schema structure.
 /**
@@ -36,17 +37,9 @@ export function createFileSchema(z) {
     return schema;
 }
 /**
- * Check if a Zod schema is a file schema (created by createFileSchema).
+ * Check if a Zod schema is a file schema (created by createFileSchema),
+ * through any wrapper (optional, default, nullable, ...) in zod v3 or v4.
  */
 export function isFileSchema(schema) {
-    if (!schema || typeof schema !== "object")
-        return false;
-    // Check for our marker
-    if (schema._def && schema._def[FILE_SCHEMA_MARKER])
-        return true;
-    // Check inner type for transforms/effects
-    if (schema._def?.typeName === "ZodEffects" && schema._def.schema) {
-        return isFileSchema(schema._def.schema);
-    }
-    return false;
+    return findMarker(schema, FILE_SCHEMA_MARKER) === true;
 }

package/dist/stream.d.ts

@@ -51,6 +51,13 @@ import type { Socket } from "./socket.js";
  * The kernel's zodToJsonSchema reads this and emits `format: "stream"`.
  */
 export declare const STREAM_SCHEMA_MARKER: unique symbol;
+/** `{"$clear": "audio"}`: drop what has been buffered of a live output field. */
+export declare const CLEAR_KEY = "$clear";
+/**
+ * `{"$error": {"field": ..., "message": ...}}`: a refused frame, or anything
+ * else the caller should be told went wrong. The stream goes on.
+ */
+export declare const ERROR_KEY = "$error";
 /**
  * Marks a binary item schema. The value on `_def` is the content type.
  * The kernel's zodToJsonSchema reads this and emits
@@ -127,11 +134,18 @@ 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;
     private read;
     private refuse;
+    /**
+     * Tell the caller something went wrong without ending the stream: a
+     * provider error, or why the session is about to end.
+     */
+    error(message: string, field?: string | null): Promise<void>;
     /**
      * Send items of live output fields, or new values of ordinary ones.
      *
@@ -140,5 +154,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

@@ -45,11 +45,21 @@
  * Zod is never imported: the app's own zod (v3 or v4) is passed in, and the
  * schemas are read by duck-typing `_def`, the same way the kernel does.
  */
+import { findMarker } from "./zod-walk.js";
 /**
  * Marks a live field's schema. The value on `_def` is the item schema.
  * The kernel's zodToJsonSchema reads this and emits `format: "stream"`.
  */
 export const STREAM_SCHEMA_MARKER = Symbol.for("inferencesh.streamSchema");
+// Control frames. Reserved keys start with `$`, which no field name can, so a
+// control frame is never mistaken for an output field.
+/** `{"$clear": "audio"}`: drop what has been buffered of a live output field. */
+export const CLEAR_KEY = "$clear";
+/**
+ * `{"$error": {"field": ..., "message": ...}}`: a refused frame, or anything
+ * else the caller should be told went wrong. The stream goes on.
+ */
+export const ERROR_KEY = "$error";
 /**
  * Marks a binary item schema. The value on `_def` is the content type.
  * The kernel's zodToJsonSchema reads this and emits
@@ -90,41 +100,6 @@ export function pcm16(z, rate = 16000, channels = 1) {
     return media(z, `audio/pcm;format=s16le;rate=${rate};channels=${channels}`);
 }
 // --- schema walking (zod v3 and v4 `_def` shapes) ---------------------------
-/** Inner schemas of a wrapper def, in the order worth checking. */
-function innerSchemas(def) {
-    const out = [];
-    // v3 + v4: optional / default / nullable / catch / readonly
-    if (def.innerType)
-        out.push(def.innerType);
-    // v3: effects (preprocess / transform / refine), v4: some wrappers
-    if (def.schema)
-        out.push(def.schema);
-    if (def.inner)
-        out.push(def.inner);
-    // v4: pipe (preprocess, transform) — in, then out
-    if (def.in)
-        out.push(def.in);
-    if (def.out)
-        out.push(def.out);
-    return out;
-}
-/** The marker's value on the schema or any schema it wraps, or undefined. */
-function findMarker(schema, marker, seen = new Set()) {
-    if (!schema || typeof schema !== "object" || seen.has(schema))
-        return undefined;
-    seen.add(schema);
-    const def = schema._def;
-    if (!def || typeof def !== "object")
-        return undefined;
-    if (Object.prototype.hasOwnProperty.call(def, marker))
-        return def[marker];
-    for (const inner of innerSchemas(def)) {
-        const found = findMarker(inner, marker, seen);
-        if (found !== undefined)
-            return found;
-    }
-    return undefined;
-}
 /** The fields of a zod object schema. v3: `_def.shape()`, v4: `_def.shape`. */
 function shapeOf(objectSchema) {
     const def = objectSchema?._def;
@@ -213,6 +188,8 @@ export class Live {
     inBinary;
     outShape;
     outBinary;
+    outLive;
+    refusedBinary = false;
     constructor(socket, inputData, inputSchema, outputSchema) {
         this.socket = socket;
         this.input = inputData;
@@ -221,6 +198,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()) {
@@ -245,7 +223,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) }];
@@ -263,35 +246,37 @@ 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;
     }
     async refuse(field, message) {
-        await this.socket.send({ error: { field, message } });
+        await this.error(message, field);
+    }
+    /**
+     * Tell the caller something went wrong without ending the stream: a
+     * provider error, or why the session is about to end.
+     */
+    async error(message, field = null) {
+        await this.socket.send({ [ERROR_KEY]: { field, message } });
     }
     /**
      * Send items of live output fields, or new values of ordinary ones.
@@ -301,6 +286,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/dist/zod-walk.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Walking a zod schema through its wrappers, the same way for zod v3 and v4:
+ * the app's own zod is passed in and never imported here, so schemas are read
+ * by duck-typing `_def`, as the kernel does.
+ */
+/** The schemas a wrapper (optional, default, nullable, effects, pipe, ...) wraps. */
+export declare function innerSchemas(def: any): any[];
+/** The value of a marker on a schema's `_def`, looking through its wrappers. */
+export declare function findMarker(schema: any, marker: symbol, seen?: Set<any>): unknown;

package/dist/zod-walk.js

@@ -0,0 +1,40 @@
+/**
+ * Walking a zod schema through its wrappers, the same way for zod v3 and v4:
+ * the app's own zod is passed in and never imported here, so schemas are read
+ * by duck-typing `_def`, as the kernel does.
+ */
+/** The schemas a wrapper (optional, default, nullable, effects, pipe, ...) wraps. */
+export function innerSchemas(def) {
+    const out = [];
+    // v3 + v4: optional / default / nullable / catch / readonly
+    if (def.innerType)
+        out.push(def.innerType);
+    // v3: effects (preprocess / transform / refine), v4: some wrappers
+    if (def.schema)
+        out.push(def.schema);
+    if (def.inner)
+        out.push(def.inner);
+    // v4: pipe (preprocess, transform) — in, then out
+    if (def.in)
+        out.push(def.in);
+    if (def.out)
+        out.push(def.out);
+    return out;
+}
+/** The value of a marker on a schema's `_def`, looking through its wrappers. */
+export function findMarker(schema, marker, seen = new Set()) {
+    if (!schema || typeof schema !== "object" || seen.has(schema))
+        return undefined;
+    seen.add(schema);
+    const def = schema._def;
+    if (!def || typeof def !== "object")
+        return undefined;
+    if (Object.prototype.hasOwnProperty.call(def, marker))
+        return def[marker];
+    for (const inner of innerSchemas(def)) {
+        const found = findMarker(inner, marker, seen);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}

package/package.json

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