@oh-my-pi/pi-ai 18.4.2 → 18.4.4

package/src/utils/http-inspector.ts

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import { getLogsDir, isBunTestRuntime } from "@oh-my-pi/pi-utils";
+import { getLogsDir, isBunTestRuntime, isRecord } from "@oh-my-pi/pi-utils";
 import * as AIError from "../error/flags";
 import { formatErrorMessageWithRetryAfter } from "./retry-after.js";
 
@@ -252,13 +252,13 @@ function formatCapturedHttpError(captured: CapturedHttpErrorResponse | undefined
 }
 
 function parseCapturedErrorPayload(captured: CapturedHttpErrorResponse): Record<string, unknown> | undefined {
-	if (isObject(captured.bodyJson)) {
+	if (isRecord(captured.bodyJson)) {
 		return captured.bodyJson;
 	}
 	if (!captured.bodyText) return undefined;
 	try {
 		const parsed = JSON.parse(captured.bodyText);
-		return isObject(parsed) ? parsed : undefined;
+		return isRecord(parsed) ? parsed : undefined;
 	} catch {
 		return undefined;
 	}
@@ -266,14 +266,10 @@ function parseCapturedErrorPayload(captured: CapturedHttpErrorResponse): Record<
 
 function getObjectProperty(value: Record<string, unknown>, key: string): Record<string, unknown> | undefined {
 	const property = value[key];
-	return isObject(property) ? property : undefined;
+	return isRecord(property) ? property : undefined;
 }
 
 function getStringProperty(value: Record<string, unknown>, key: string): string | undefined {
 	const property = value[key];
 	return typeof property === "string" && property.trim().length > 0 ? property : undefined;
 }
-
-function isObject(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/utils/openai-http.ts

@@ -70,8 +70,14 @@ export interface OpenAIStreamRequestInit {
 	fetch?: FetchImpl;
 	/** Optional caller-specific gate composed with shared transport retry exclusions. */
 	shouldRetryResponse?: (response: Response, bodyText: string) => boolean | Promise<boolean>;
-	/** Raw wire-frame observer (`onSseEvent` debug pipeline). */
+	/**
+	 * Raw wire-frame observer (`onSseEvent` debug pipeline). Leave it unset
+	 * when no diagnostic listener exists: any observer turns on per-line raw
+	 * capture for every frame.
+	 */
 	onSseEvent?: SseEventObserver;
+	/** Called when the stream ends on the OpenAI `[DONE]` sentinel; independent of {@link onSseEvent}. */
+	onDoneSentinel?: () => void;
 }
 
 export interface OpenAIStreamHandle<TEvent> {
@@ -117,7 +123,7 @@ export async function postOpenAIStream<TEvent>(init: OpenAIStreamRequestInit): P
 		});
 	}
 	return {
-		events: decodeStream<TEvent>(response.body, init.signal, init.onSseEvent),
+		events: decodeStream<TEvent>(response.body, init.signal, init.onSseEvent, init.onDoneSentinel),
 		response,
 		requestId: response.headers.get("x-request-id"),
 	};
@@ -140,8 +146,9 @@ async function* decodeStream<TEvent>(
 	body: ReadableStream<Uint8Array>,
 	signal: AbortSignal | undefined,
 	onSseEvent: SseEventObserver | undefined,
+	onDoneSentinel: (() => void) | undefined,
 ): AsyncGenerator<TEvent> {
-	for await (const frame of readSseJsonOrText<TEvent>(body, signal, onSseEvent)) {
+	for await (const frame of readSseJsonOrText<TEvent>(body, signal, onSseEvent, onDoneSentinel)) {
 		if (typeof frame === "string") {
 			const inBand = AIError.createInBandProviderErrorFromText(frame);
 			if (inBand) throw inBand;

package/src/utils/schema/json-schema-validator.ts

@@ -12,7 +12,7 @@
  * Compared to AJV this is single-pass, synchronous, dependency-free, and
  * tolerates non-standard shapes (`nullable`) that LLM-emitted schemas carry.
  */
-import { logger } from "@oh-my-pi/pi-utils";
+import { isRecord, logger } from "@oh-my-pi/pi-utils";
 import { areJsonValuesEqual } from "./equality";
 
 export interface JsonSchemaValidationIssue {
@@ -65,9 +65,6 @@ function getValueIdentity(ctx: ValidationContext, value: object): number {
 	return id;
 }
 
-function isJsonObject(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 /**
  * Whether `value` matches every `const`/`enum` discriminator property the
  * branch declares (with at least one such property present and matching).
@@ -76,13 +73,13 @@ function isJsonObject(value: unknown): value is Record<string, unknown> {
  * repairs to them; without a unique tag, branch issues are guesses.
  */
 function isTagSelectedBranch(branch: unknown, value: unknown): boolean {
-	if (!isJsonObject(branch) || !isJsonObject(value)) return false;
+	if (!isRecord(branch) || !isRecord(value)) return false;
 	const props = branch.properties;
-	if (!isJsonObject(props)) return false;
+	if (!isRecord(props)) return false;
 	let matched = false;
 	for (const key in props) {
 		const propSchema = props[key];
-		if (!isJsonObject(propSchema)) continue;
+		if (!isRecord(propSchema)) continue;
 		const hasConst = Object.hasOwn(propSchema, "const");
 		const enumValues = Array.isArray(propSchema.enum) ? propSchema.enum : undefined;
 		if (!hasConst && !enumValues) continue;
@@ -138,7 +135,7 @@ function matchesJsonSchemaType(value: unknown, type: string): boolean {
 		case "boolean":
 			return typeof value === "boolean";
 		case "object":
-			return isJsonObject(value);
+			return isRecord(value);
 		case "array":
 			return Array.isArray(value);
 		case "null":
@@ -178,7 +175,7 @@ function resolveLocalRef(root: unknown, ref: string): unknown | undefined {
 	let current: unknown = root;
 	for (const rawToken of ref.slice(2).split("/")) {
 		const token = decodePointerToken(rawToken);
-		if (!isJsonObject(current) && !Array.isArray(current)) return undefined;
+		if (!isRecord(current) && !Array.isArray(current)) return undefined;
 		current = (current as Record<string, unknown>)[token];
 	}
 	return current;
@@ -186,7 +183,7 @@ function resolveLocalRef(root: unknown, ref: string): unknown | undefined {
 
 /** A presence-only constraint, as distinct from restrictions on a property's value. */
 function requiresOnlyPropertyPresence(schema: unknown, key: string, root: unknown, depth = 0): boolean {
-	if (!isJsonObject(schema) || depth >= MAX_REF_DEPTH) return false;
+	if (!isRecord(schema) || depth >= MAX_REF_DEPTH) return false;
 	for (const keyword of Object.keys(schema)) {
 		switch (keyword) {
 			case "required":
@@ -217,17 +214,17 @@ export function schemaDefinesProperty(schema: unknown, key: string): boolean {
 	const root = schema;
 	const visited = new WeakMap<object, number>();
 	const visit = (node: unknown, context: "positive" | "negative" | "predicate" = "positive"): boolean => {
-		if (!isJsonObject(node)) return false;
+		if (!isRecord(node)) return false;
 		const contextBit = context === "positive" ? 1 : context === "negative" ? 2 : 4;
 		const previousContexts = visited.get(node) ?? 0;
 		if (previousContexts & contextBit) return false;
 		visited.set(node, previousContexts | contextBit);
-		if (isJsonObject(node.const) && Object.hasOwn(node.const, key)) return true;
-		if (Array.isArray(node.enum) && node.enum.some(value => isJsonObject(value) && Object.hasOwn(value, key))) {
+		if (isRecord(node.const) && Object.hasOwn(node.const, key)) return true;
+		if (Array.isArray(node.enum) && node.enum.some(value => isRecord(value) && Object.hasOwn(value, key))) {
 			return true;
 		}
 		const properties = node.properties;
-		if (isJsonObject(properties) && Object.hasOwn(properties, key)) {
+		if (isRecord(properties) && Object.hasOwn(properties, key)) {
 			return properties[key] !== false || context !== "positive";
 		}
 		const required = node.required;
@@ -240,7 +237,7 @@ export function schemaDefinesProperty(schema: unknown, key: string): boolean {
 			return true;
 		}
 		const patternProperties = node.patternProperties;
-		if (isJsonObject(patternProperties)) {
+		if (isRecord(patternProperties)) {
 			for (const [pattern, patternSchema] of Object.entries(patternProperties)) {
 				try {
 					if (new RegExp(pattern).test(key)) {
@@ -251,8 +248,8 @@ export function schemaDefinesProperty(schema: unknown, key: string): boolean {
 				}
 			}
 		}
-		if (isJsonObject(node.unevaluatedProperties)) return true;
-		if (isJsonObject(node.additionalProperties)) return true;
+		if (isRecord(node.unevaluatedProperties)) return true;
+		if (isRecord(node.additionalProperties)) return true;
 		for (const keyword of ["anyOf", "oneOf", "allOf"] as const) {
 			const branches = node[keyword];
 			if (Array.isArray(branches) && branches.some(branch => visit(branch, context))) return true;
@@ -270,19 +267,19 @@ export function schemaDefinesProperty(schema: unknown, key: string): boolean {
 			return true;
 		}
 		const dependentSchemas = node.dependentSchemas;
-		if (isJsonObject(dependentSchemas)) {
+		if (isRecord(dependentSchemas)) {
 			if (Object.hasOwn(dependentSchemas, key)) return true;
 			if (Object.values(dependentSchemas).some(dependency => visit(dependency, context))) return true;
 		}
 		const dependentRequired = node.dependentRequired;
-		if (isJsonObject(dependentRequired)) {
+		if (isRecord(dependentRequired)) {
 			if (Object.hasOwn(dependentRequired, key)) return true;
 			for (const dependencies of Object.values(dependentRequired)) {
 				if (Array.isArray(dependencies) && dependencies.includes(key)) return true;
 			}
 		}
 		const dependencies = node.dependencies;
-		if (isJsonObject(dependencies)) {
+		if (isRecord(dependencies)) {
 			if (Object.hasOwn(dependencies, key)) return true;
 			for (const dependency of Object.values(dependencies)) {
 				if (Array.isArray(dependency) && dependency.includes(key)) return true;
@@ -324,7 +321,7 @@ function validateSchemaNode(
 		pushIssue(issues, path, "must not match false schema", { keyword: "false" });
 		return false;
 	}
-	if (!isJsonObject(schema)) {
+	if (!isRecord(schema)) {
 		pushIssue(issues, path, "schema must be an object or boolean", { keyword: "schema" });
 		return false;
 	}
@@ -469,7 +466,7 @@ function validateSchemaNode(
 		);
 	}
 
-	if (isJsonObject(value)) {
+	if (isRecord(value)) {
 		valid = validateObjectKeywords(schema, value, path, ctx, issues) && valid;
 	}
 	if (Array.isArray(value)) {
@@ -494,7 +491,7 @@ function validateObjectKeywords(
 	issues: JsonSchemaValidationIssue[],
 ): boolean {
 	let valid = true;
-	const properties = isJsonObject(schema.properties) ? schema.properties : {};
+	const properties = isRecord(schema.properties) ? schema.properties : {};
 	if (isRequiredSet(schema.required)) {
 		for (const key of schema.required) {
 			if (!(key in value)) {
@@ -516,7 +513,7 @@ function validateObjectKeywords(
 	}
 
 	const known = new Set(Object.keys(properties));
-	if (isJsonObject(schema.patternProperties)) {
+	if (isRecord(schema.patternProperties)) {
 		const patternProperties = schema.patternProperties;
 		for (const pattern in patternProperties) {
 			const patternSchema = patternProperties[pattern];
@@ -536,7 +533,7 @@ function validateObjectKeywords(
 		}
 	}
 
-	if (isJsonObject(schema.dependentRequired)) {
+	if (isRecord(schema.dependentRequired)) {
 		const dependentRequired = schema.dependentRequired;
 		for (const key in dependentRequired) {
 			const deps = dependentRequired[key];
@@ -554,7 +551,7 @@ function validateObjectKeywords(
 		}
 	}
 
-	if (isJsonObject(schema.dependentSchemas)) {
+	if (isRecord(schema.dependentSchemas)) {
 		const dependentSchemas = schema.dependentSchemas;
 		for (const key in dependentSchemas) {
 			if (!(key in value)) continue;

package/src/utils/schema/meta-validator.ts

@@ -1,3 +1,4 @@
+import { isRecord } from "@oh-my-pi/pi-utils";
 import { areJsonValuesEqual } from "./equality";
 import { epochNext, once } from "./stamps";
 
@@ -12,10 +13,6 @@ import { epochNext, once } from "./stamps";
 
 type Json = unknown;
 
-function isPlainObject(value: Json): value is Record<string, Json> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 const TYPE_NAMES: Record<string, true> = {
 	string: true,
 	number: true,
@@ -55,7 +52,7 @@ function checkSchemaArray(value: Json, epoch: number): boolean {
 }
 
 function checkSchemaMap(value: Json, epoch: number): boolean {
-	if (!isPlainObject(value)) return false;
+	if (!isRecord(value)) return false;
 	for (const k in value) {
 		if (!checkNode(value[k], epoch)) return false;
 	}
@@ -66,7 +63,7 @@ function checkSchemaMap(value: Json, epoch: number): boolean {
 function checkNode(node: Json, epoch: number): boolean {
 	// Boolean schemas (`true` / `false`) are valid JSON Schema.
 	if (node === true || node === false) return true;
-	if (!isPlainObject(node)) return false;
+	if (!isRecord(node)) return false;
 	if (!once(node, epoch)) return true;
 
 	if ("type" in node && !checkTypeKeyword(node.type)) return false;
@@ -115,7 +112,7 @@ function checkNode(node: Json, epoch: number): boolean {
 	if ("dependentSchemas" in node && !checkSchemaMap(node.dependentSchemas, epoch)) return false;
 	if ("dependentRequired" in node) {
 		const value = node.dependentRequired;
-		if (!isPlainObject(value)) return false;
+		if (!isRecord(value)) return false;
 		for (const k in value) {
 			const entry = value[k];
 			if (!Array.isArray(entry) || !entry.every(item => typeof item === "string")) return false;

package/src/utils/schema/wire.ts

@@ -7,7 +7,7 @@
  */
 
 import type { Type } from "@oh-my-pi/omptype";
-import { structuredCloneJSON } from "@oh-my-pi/pi-utils";
+import { isRecord, structuredCloneJSON } from "@oh-my-pi/pi-utils";
 import type { Tool, TSchema } from "../../types";
 import { upgradeJsonSchemaTo202012 } from "./draft";
 import { stamp } from "./stamps";
@@ -28,13 +28,13 @@ export function isArkSchema(value: unknown): value is Type {
 
 function isArkJsonAst(value: unknown): boolean {
 	if (Array.isArray(value)) return value.some(isArkJsonAst);
-	if (!isSchemaRecord(value)) return false;
+	if (!isRecord(value)) return false;
 	if (typeof value.domain === "string" || Object.hasOwn(value, "unit")) return true;
 	if (value.proto === "Array" && Object.hasOwn(value, "sequence")) return true;
 	const required = value.required;
 	return (
 		Array.isArray(required) &&
-		required.some(entry => isSchemaRecord(entry) && typeof entry.key === "string" && "value" in entry)
+		required.some(entry => isRecord(entry) && typeof entry.key === "string" && "value" in entry)
 	);
 }
 
@@ -46,7 +46,7 @@ function parseArkObjectKey(key: string): { name: string; description?: string }
 
 function withArkKeyDescription(schema: unknown, description: string | undefined): unknown {
 	if (!description) return schema;
-	if (isSchemaRecord(schema)) {
+	if (isRecord(schema)) {
 		if (typeof schema.description !== "string") schema.description = description;
 		return schema;
 	}
@@ -70,13 +70,13 @@ function arkJsonAstToWire(value: unknown): unknown {
 	}
 
 	if (Array.isArray(value)) {
-		if (value.every(item => isSchemaRecord(item) && Object.hasOwn(item, "unit"))) {
+		if (value.every(item => isRecord(item) && Object.hasOwn(item, "unit"))) {
 			return { enum: value.map(item => (item as { unit: unknown }).unit) };
 		}
 		return { anyOf: value.map(arkJsonAstToWire) };
 	}
 
-	if (!isSchemaRecord(value)) return {};
+	if (!isRecord(value)) return {};
 
 	if (Object.hasOwn(value, "unit")) return { const: value.unit };
 
@@ -88,7 +88,7 @@ function arkJsonAstToWire(value: unknown): unknown {
 		const properties: Record<string, unknown> = {};
 		const required: string[] = [];
 		const addEntry = (entry: unknown, isRequired: boolean): void => {
-			if (!isSchemaRecord(entry) || typeof entry.key !== "string" || !("value" in entry)) return;
+			if (!isRecord(entry) || typeof entry.key !== "string" || !("value" in entry)) return;
 			const key = parseArkObjectKey(entry.key);
 			properties[key.name] = withArkKeyDescription(arkJsonAstToWire(entry.value), key.description);
 			if (isRequired) required.push(key.name);
@@ -144,10 +144,6 @@ const SCHEMA_DEFINING_SIBLING_KEYS = new Set([
 	"unevaluatedProperties",
 ]);
 
-function isSchemaRecord(value: unknown): value is Record<string, unknown> {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 function hasSchemaDefiningSibling(schema: Record<string, unknown>): boolean {
 	for (const key in schema) {
 		if (key !== "anyOf" && SCHEMA_DEFINING_SIBLING_KEYS.has(key)) return true;
@@ -188,7 +184,7 @@ function rewriteNullableScalarAnyOf(schema: Record<string, unknown>): void {
 	let scalarType: string | undefined;
 	let sawNull = false;
 	for (const variant of variants) {
-		if (!isSchemaRecord(variant)) return;
+		if (!isRecord(variant)) return;
 		if (isNullVariant(variant)) {
 			if (sawNull) return;
 			sawNull = true;
@@ -206,7 +202,7 @@ function rewriteNullableScalarAnyOf(schema: Record<string, unknown>): void {
 }
 
 function isExclusiveRequiredBranch(branch: unknown): boolean {
-	if (!isSchemaRecord(branch)) return false;
+	if (!isRecord(branch)) return false;
 	if (Object.hasOwn(branch, "type")) return false;
 	if (!Array.isArray(branch.required) || branch.required.length === 0) return false;
 	if (!branch.required.every(name => typeof name === "string" && name.length > 0)) return false;
@@ -229,7 +225,7 @@ export function flattenExclusiveRequiredRootUnion(schema: Record<string, unknown
 	const union = schema[unionKey];
 	if (!Array.isArray(union) || union.length === 0) return schema;
 	const typedObject = schema.type === "object" || (Array.isArray(schema.type) && schema.type.includes("object"));
-	if (!typedObject && !isSchemaRecord(schema.properties)) return schema;
+	if (!typedObject && !isRecord(schema.properties)) return schema;
 	if (!union.every(isExclusiveRequiredBranch)) return schema;
 	const flattened = { ...schema };
 	delete flattened[unionKey];
@@ -261,11 +257,11 @@ function normalizeArkPropertyComments(node: unknown): void {
 		for (const child of node) normalizeArkPropertyComments(child);
 		return;
 	}
-	if (!isSchemaRecord(node)) return;
+	if (!isRecord(node)) return;
 	const obj = node as Record<string, unknown>;
 
 	const properties = obj.properties;
-	if (isSchemaRecord(properties)) {
+	if (isRecord(properties)) {
 		const required = Array.isArray(obj.required) ? obj.required : undefined;
 		if (required) {
 			obj.required = required.map(key => (typeof key === "string" ? parseArkObjectKey(key).name : key));
@@ -289,7 +285,7 @@ function normalizeArkPropertyComments(node: unknown): void {
 	for (const mapKey of SCHEMA_MAP_KEYS) {
 		if (mapKey === "properties") continue;
 		const map = obj[mapKey];
-		if (isSchemaRecord(map)) {
+		if (isRecord(map)) {
 			for (const key in map) normalizeArkPropertyComments(map[key]);
 		}
 	}
@@ -382,7 +378,7 @@ function collapseConstUnionAnyOf(obj: Record<string, unknown>): void {
 	let branchDescription: string | undefined;
 	let describedCount = 0;
 	for (const variant of variants) {
-		if (!isSchemaRecord(variant) || !Object.hasOwn(variant, "const")) return;
+		if (!isRecord(variant) || !Object.hasOwn(variant, "const")) return;
 		for (const key in variant) {
 			if (key !== "const" && key !== "description") return; // extra constraints — not a bare const
 		}
@@ -553,7 +549,7 @@ function pruneArkUndefinedUnionBranches(node: unknown): void {
 		const concrete = branches.filter(branch => !isUnconstrainedSchema(branch));
 		if (concrete.length === branches.length || concrete.length === 0) continue;
 		const only = concrete.length === 1 ? concrete[0] : undefined;
-		if (only !== undefined && isSchemaRecord(only)) {
+		if (only !== undefined && isRecord(only)) {
 			delete obj[unionKey];
 			for (const key in only) {
 				if (!(key in obj)) obj[key] = only[key];
@@ -651,14 +647,14 @@ function stripSchemaDescriptionsInPlace(node: unknown): void {
 		for (const child of node) stripSchemaDescriptionsInPlace(child);
 		return;
 	}
-	if (!isSchemaRecord(node)) return;
+	if (!isRecord(node)) return;
 	delete node.description;
 	for (const key of STRIP_SCHEMA_VALUE_KEYS) {
 		if (Object.hasOwn(node, key)) stripSchemaDescriptionsInPlace(node[key]);
 	}
 	for (const mapKey of STRIP_SCHEMA_MAP_KEYS) {
 		const map = node[mapKey];
-		if (isSchemaRecord(map)) {
+		if (isRecord(map)) {
 			for (const key in map) stripSchemaDescriptionsInPlace(map[key]);
 		}
 	}