@llblab/pi-kit 0.7.1 → 0.8.1

package/node_modules/@llblab/pi-state-flow/lib/transition.ts

@@ -1,8 +1,10 @@
 import {
+	compileArtifact,
 	ORDINARY_ARTIFACT_COMPILER,
 	validateArtifactMetadata,
 	validateArtifactRegistry,
-	type ArtifactMetadata,
+	type ArtifactCompilerOutput,
+	type ArtifactProvenance,
 } from "./artifact.ts";
 import type { SuccessfulArtifactRead } from "./acquisition.ts";
 import { createAcceptedTransition, type AcceptedTransition } from "./history.ts";
@@ -24,6 +26,8 @@ import type {
 export interface StagedScopedTransition {
 	nextStates: ScopedStates;
 	stateHashes: Record<StateScope, string>;
+	/** Fresh runtime-owned provenance for artifacts compiled in this transition. */
+	provenanceUpdates: Record<StateScope, Record<string, ArtifactProvenance>>;
 	causalBasis: string;
 	committed: boolean;
 }
@@ -35,27 +39,26 @@ function compileReadArtifacts(
 	nextState: StateDocument,
 	patch: Pick<StatePatch, "artifacts">,
 	successfulArtifactReads: Iterable<SuccessfulArtifactRead>,
+	provenance: Record<string, ArtifactProvenance>,
 ): void {
 	for (const read of successfulArtifactReads) {
 		const output = patch.artifacts[read.path];
 		if (!isObject(output)) {
 			throw new Error(`Every successfully read invalidated artifact must have a global compiler output at artifacts[exact candidate path]; missing: ${read.path}`);
 		}
-		if (Object.hasOwn(output, "hash") || Object.hasOwn(output, "compiler")) {
-			throw new Error(`Artifact compiler output at ${read.path} cannot set runtime-owned hash or compiler fields`);
-		}
-		const metadata = {
-			...structuredClone(output),
-			hash: read.hash,
+		const compiled = compileArtifact({
+			source: { path: read.path, hash: read.hash },
 			compiler: ORDINARY_ARTIFACT_COMPILER,
-		} as ArtifactMetadata;
-		validateArtifactMetadata(metadata, read.path);
+			output: output as ArtifactCompilerOutput,
+		});
+		validateArtifactMetadata(compiled.semantic, read.path);
 		Object.defineProperty(nextState.artifacts, read.path, {
-			value: metadata,
+			value: compiled.semantic,
 			enumerable: true,
 			configurable: true,
 			writable: true,
 		});
+		provenance[read.path] = compiled.provenance;
 	}
 }
 
@@ -63,6 +66,7 @@ function compileReadSkills(
 	nextState: StateDocument,
 	patch: Pick<StatePatch, "artifacts">,
 	successfulSkillReads: Iterable<SuccessfulSkillRead>,
+	provenance: Record<string, ArtifactProvenance>,
 ): void {
 	for (const read of successfulSkillReads) {
 		if (read.hash === undefined) {
@@ -84,20 +88,20 @@ function compileReadSkills(
 		if (!isObject(output.compilation) || Object.keys(output.compilation).length === 0) {
 			throw new Error(`Skill artifact compiler output at ${read.path} must have a non-empty compilation object`);
 		}
-		const metadata = {
-			...structuredClone(output),
-			hash: read.hash,
+		const compiled = compileArtifact({
+			source: { path: read.path, hash: read.hash },
 			compiler: SKILL_ARTIFACT_COMPILER,
-			kind: "skill",
-		} as ArtifactMetadata;
-		validateArtifactMetadata(metadata, read.path);
+			output: { ...structuredClone(output), kind: "skill" } as ArtifactCompilerOutput,
+		});
+		validateArtifactMetadata(compiled.semantic, read.path);
 		Object.defineProperty(nextState.artifacts, read.path, {
-			value: metadata,
+			value: compiled.semantic,
 			enumerable: true,
 			configurable: true,
 			writable: true,
 		});
-		if (!hasCompiledSkillArtifact(nextState.artifacts, read.path, read.hash)) {
+		provenance[read.path] = compiled.provenance;
+		if (!hasCompiledSkillArtifact(nextState.artifacts, provenance[read.path], read.path, read.hash)) {
 			throw new Error(`Skill artifact compilation at ${read.path} is not locally materialized for its executed source identity`);
 		}
 	}
@@ -146,7 +150,7 @@ function stageScopedSemanticTransition(
 	successfulSkillReads: Iterable<SuccessfulSkillRead>,
 	causalBasis: string,
 	successfulArtifactReads: Iterable<SuccessfulArtifactRead>,
-	terminalResponse?: string,
+	acceptedResponse?: string,
 ): StagedScopedTransition {
 	if (!Array.isArray(transition.transitions)) throw new Error("State Flow transitions must be an array");
 	const patches = new Map<StateScope, ScopePatch>();
@@ -164,20 +168,22 @@ function stageScopedSemanticTransition(
 
 	const cwdPatch = patches.get("cwd") ?? {};
 	const nextStates = structuredClone(currentStates);
+	const provenanceUpdates: Record<StateScope, Record<string, ArtifactProvenance>> = { global: {}, cwd: {}, session: {} };
 	for (const scope of SCOPES) {
 		const authored = patches.get(scope) ?? {};
-		const response = scope === "session" && terminalResponse !== undefined
-			? terminalResponse
+		const response = scope === "session" && acceptedResponse !== undefined
+			? acceptedResponse
 			: currentStates[scope].response;
 		const patch = completePatch(authored, response);
 		const nextState = applyPatch(structuredClone(currentStates[scope]), patch) as MaterializedState;
-		compileReadArtifacts(nextState, { artifacts: scope === "global" ? authored.artifacts ?? {} : {} }, scope === "global" ? successfulArtifactReads : []);
-		compileReadSkills(nextState, { artifacts: scope === "cwd" ? cwdPatch.artifacts ?? {} : {} }, scope === "cwd" ? successfulSkillReads : []);
+		compileReadArtifacts(nextState, { artifacts: scope === "global" ? authored.artifacts ?? {} : {} }, scope === "global" ? successfulArtifactReads : [], provenanceUpdates.global);
+		compileReadSkills(nextState, { artifacts: scope === "cwd" ? cwdPatch.artifacts ?? {} : {} }, scope === "cwd" ? successfulSkillReads : [], provenanceUpdates.cwd);
 		validateMaterializedTransition(nextState);
 		nextStates[scope] = nextState;
 	}
 	return {
 		nextStates,
+		provenanceUpdates,
 		stateHashes: {
 			global: hashJson(currentStates.global),
 			cwd: hashJson(currentStates.cwd),
@@ -188,6 +194,22 @@ function stageScopedSemanticTransition(
 	};
 }
 
+/** Validate that explicit unchanged resolution has no pending acquisition/compilation obligation. */
+export function validateUnchangedResolution(
+	currentStates: ScopedStates,
+	successfulSkillReads: Iterable<SuccessfulSkillRead>,
+	causalBasis: string,
+	successfulArtifactReads: Iterable<SuccessfulArtifactRead> = [],
+): void {
+	stageScopedSemanticTransition(
+		currentStates,
+		{ transitions: [] },
+		successfulSkillReads,
+		causalBasis,
+		successfulArtifactReads,
+	);
+}
+
 /** Stage one intermediate state barrier without changing the finalized response. */
 export function stageScopedPatch(
 	currentStates: ScopedStates,
@@ -213,7 +235,7 @@ export function stageScopedTransition(
 	successfulArtifactReads: Iterable<SuccessfulArtifactRead> = [],
 ): StagedScopedTransition {
 	if (typeof transition.response !== "string" || transition.response.trim().length === 0) {
-		throw new Error("Terminal State Flow response body must be non-empty");
+		throw new Error("Accepted State Flow response body must be non-empty");
 	}
 	return stageScopedSemanticTransition(
 		currentStates,
@@ -227,7 +249,7 @@ export function stageScopedTransition(
 
 /** Commit one accepted transition; durable publication receives all changed scopes as one cohort. */
 export interface CommitScopedTransitionOptions {
-	/** Terminal reconciliation finalizes bootstrap and validation lifecycle state. */
+	/** Runtime response reconciliation finalizes bootstrap lifecycle state. */
 	finalizeRun?: boolean;
 }
 
@@ -240,10 +262,10 @@ export function commitScopedTransition(
 	options: CommitScopedTransitionOptions = {},
 ): boolean {
 	if (stage.committed) return false;
-	if (causalBasis !== stage.causalBasis) throw new Error("State Flow causal basis changed after response validation; regenerate the terminal response");
+	if (causalBasis !== stage.causalBasis) throw new Error("State Flow causal basis changed before response reconciliation; rematerialize state before retrying");
 	for (const scope of SCOPES) {
 		if (hashJson(states[scope]) !== stage.stateHashes[scope]) {
-			throw new Error(`State Flow ${scope} scope changed after response validation; regenerate the terminal response`);
+			throw new Error(`State Flow ${scope} scope changed before response reconciliation; rematerialize state before retrying`);
 		}
 	}
 	// The finalized response may differ from message_end after chained handlers.

package/node_modules/@llblab/pi-state-flow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": false,
   "description": "Incremental scoped state/context compiler for Pi, inspired by SKILL.state",
   "keywords": [

package/node_modules/@llblab/pi-telegram/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ## Unreleased
 
+## 0.45.2: Provider-Compatible Bind Schema Hotfix
+
+- `Provider-Compatible Bind Argument`: Serializes the `telegram_bind` `argument` schema as an inline builder-made JSON-value union bounded to four container levels, with no `$ref`/`$defs` recursion or raw TypeBox marker leakage; OpenAI no longer rejects every request with "Recursive JSON schemas are not currently supported" (#273) and Gemini no longer rejects the unknown `~optional` field (#269) while the tool is registered.
+
 ## 0.45.1: Guest Mode And Channel Media Hotfixes
 
 - `Environment-backed bot tokens`: `telegram.json` profiles may store an exact `$NAME`/`${NAME}` reference instead of a copied token. Resolution happens only at validation/activation boundaries, including pairing identity hashing; setup prefills the first supported alias, validates the resolved value, and persists the alias; literals stay compatible; unresolved references fail closed with a redacted named-variable diagnostic in setup, connect, and status.

package/node_modules/@llblab/pi-telegram/docs/generative-apps.md

@@ -98,7 +98,7 @@ An absent, stale, or invalid bound app fails closed and never degrades into an a
 
 ## `telegram_bind` Tool
 
-One agent Tool owns installation and deliberate invocation through two mutually exclusive shapes. Its optional `argument` schema explicitly describes recursive JSON values (`null`, boolean, number, string, array, or object) rather than using an unconstrained subschema. Pi keeps the same JSON semantics, while schema aggregators cannot lower this field to a bare `true` schema that some llama-server grammars reject. The recursive definition lives in the tool root `$defs` and uses only local `#/$defs/TelegramBindJsonValue` references; it does not rely on named/remote reference resolution or newer TypeBox runtime helpers.
+One agent Tool owns installation and deliberate invocation through two mutually exclusive shapes. Its optional `argument` schema explicitly describes JSON values (`null`, boolean, number, string, array, or object) as a bounded union nested four container levels deep rather than using an unconstrained subschema. Pi keeps the same JSON semantics, while schema aggregators cannot lower this field to a bare `true` schema that some llama-server grammars reject. The union is built through standard schema builders and serialized inline with no `$ref`/`$defs` recursion, so provider tool APIs that reject recursive or reference-resolved schemas (OpenAI) accept it alongside providers strict about unknown schema fields (Gemini).
 
 Install an external self-contained module and initialize it:
 

package/node_modules/@llblab/pi-telegram/lib/generative-apps.ts

@@ -862,21 +862,23 @@ export function formatGenerativeAppToolError(error: unknown): Error {
   return new Error(`\n${message.replace(/^\n+/u, "") || "Generative App operation failed."}`);
 }
 
-const TELEGRAM_BIND_JSON_ARGUMENT_REFERENCE = "#/$defs/TelegramBindJsonValue";
-const TELEGRAM_BIND_JSON_ARGUMENT_SCHEMA = {
-  $ref: TELEGRAM_BIND_JSON_ARGUMENT_REFERENCE,
-} as unknown as ReturnType<typeof Type.Unknown>;
-const TELEGRAM_BIND_JSON_ARGUMENT_DEFINITION = {
-  anyOf: [
-    { type: "null" },
-    { type: "boolean" },
-    { type: "number" },
-    { type: "string" },
-    { type: "array", items: { $ref: TELEGRAM_BIND_JSON_ARGUMENT_REFERENCE } },
-    { type: "object", properties: {},
-      additionalProperties: { $ref: TELEGRAM_BIND_JSON_ARGUMENT_REFERENCE } },
-  ],
-};
+// Provider tool APIs reject recursive $ref schemas (OpenAI) and raw TypeBox
+// optional markers on non-builder objects (Gemini), while llama-server rejects
+// unconstrained subschemas; one bounded builder-made JSON-value union satisfies all.
+const TELEGRAM_BIND_JSON_ARGUMENT_MAX_DEPTH = 4;
+
+function createTelegramBindJsonArgumentSchema(
+  depth: number,
+): ReturnType<typeof Type.Union> {
+  const scalars = [Type.Null(), Type.Boolean(), Type.Number(), Type.String()];
+  if (depth <= 0) return Type.Union(scalars);
+  const nested = createTelegramBindJsonArgumentSchema(depth - 1);
+  return Type.Union([
+    ...scalars,
+    Type.Array(nested),
+    Type.Object({}, { additionalProperties: nested }),
+  ]);
+}
 
 export function registerTelegramBindTool(
   pi: ExtensionAPI,
@@ -893,10 +895,10 @@ export function registerTelegramBindTool(
       method: Type.Optional(Type.String()),
       replace: Type.Optional(Type.Boolean()),
       display: Type.Optional(Type.Boolean()),
-      argument: Type.Optional(TELEGRAM_BIND_JSON_ARGUMENT_SCHEMA),
-    }, { additionalProperties: false,
-      $defs: { TelegramBindJsonValue: TELEGRAM_BIND_JSON_ARGUMENT_DEFINITION },
-    }),
+      argument: Type.Optional(
+        createTelegramBindJsonArgumentSchema(TELEGRAM_BIND_JSON_ARGUMENT_MAX_DEPTH),
+      ),
+    }, { additionalProperties: false }),
     async execute(_toolCallId, params) {
       try {
         const result = await bindGenerativeApp({

package/node_modules/@llblab/pi-telegram/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.45.1",
+  "version": "0.45.2",
   "private": false,
   "publishConfig": {
     "access": "public"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -44,8 +44,8 @@
     "@llblab/pi-clean-room": "0.1.1",
     "@llblab/pi-codex-usage": "0.9.4",
     "@llblab/pi-grow-loop": "0.7.5",
-    "@llblab/pi-state-flow": "0.6.0",
-    "@llblab/pi-telegram": "0.45.1",
+    "@llblab/pi-state-flow": "0.7.0",
+    "@llblab/pi-telegram": "0.45.2",
     "@llblab/skills": "1.15.0"
   },
   "bundledDependencies": [

package/node_modules/@llblab/pi-state-flow/lib/validation.ts

@@ -1,27 +0,0 @@
-import { terminalRegenerationInstruction } from "./terminal.ts";
-
-export const MAX_VALIDATION_RETRIES = 3;
-
-export interface ValidationFeedback {
-	attempt: number;
-	error: string;
-	instruction: string;
-}
-
-export type ValidationDecision =
-	| { kind: "retry"; feedback: ValidationFeedback }
-	| { kind: "exhausted"; error: string };
-
-/** Decide retry progression without mutating persistent runtime state. */
-export function nextValidation(previous: ValidationFeedback | undefined, error: string): ValidationDecision {
-	const attempt = (previous?.attempt ?? 0) + 1;
-	if (attempt > MAX_VALIDATION_RETRIES) return { kind: "exhausted", error };
-	return {
-		kind: "retry",
-		feedback: {
-			attempt,
-			error,
-			instruction: terminalRegenerationInstruction(error),
-		},
-	};
-}