@danypops/papyrus 0.46.0 → 0.46.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.46.0",
+  "version": "0.46.2",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/handlers/playbooks.ts

@@ -44,6 +44,10 @@ import {
 } from "./shared.ts";
 
 const OWNER = "playbooks";
+const jsonObjectProp = {
+	type: ["object", "string"],
+	description: "A JSON object; a JSON-encoded object string is also accepted for tool-calling compatibility.",
+} as const;
 
 export interface PlaybooksVehicleDeps {
 	artifacts: ArtifactStore;
@@ -126,7 +130,7 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 		"preview",
 		"Renders a Playbook's whole composition tree as text, with no side effects.",
 		"read",
-		{ id: stringProp, name: stringProp, arguments: { type: "object" } },
+		{ id: stringProp, name: stringProp, arguments: jsonObjectProp },
 		[],
 		(input) => {
 			normalizeJsonEncodedField(input, "arguments");
@@ -138,7 +142,7 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 		"invoke",
 		"Compiles the Playbook's steps and composition tree into real Tasks wired with dependsOn, and focuses the first one -- one step surfaces at a time as it becomes focused, exactly like any other Task. `arguments` supplies known values as {name: value}; if a declared REQUIRED argument is still missing, nothing is created and missingArguments is returned instead -- ask the human for these (discuss tool, live:true) and invoke again, never guess. Drive the returned entryTaskId forward with the tasks tool (start/submit/complete).",
 		"local-write",
-		{ id: stringProp, name: stringProp, run_id: stringProp, arguments: { type: "object" }, project_root: stringProp },
+		{ id: stringProp, name: stringProp, run_id: stringProp, arguments: jsonObjectProp, project_root: stringProp },
 		[],
 		(input) => {
 			normalizeJsonEncodedField(input, "arguments");

package/src/handlers/shared.ts

@@ -7,11 +7,13 @@ import {
 	bindVehicleOperation,
 	defineVehicleOperation,
 	defineVehicleSchema,
+	type JsonSchema,
 	type VehicleContentBlock,
 	VehicleError,
 	type VehicleLimits,
 	type VehicleOperationContext,
 	type VehicleSchemaCodec,
+	type VehicleSchemaIssue,
 } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { Artifact } from "../artifact/artifact.ts";
@@ -21,33 +23,118 @@ import { InvalidSessionSecretError } from "../session-identity/session-identity-
 import { TaskCreateIdempotencyConflictError } from "../stores/task-create-request-store.ts";
 import { TaskDependencyCycleError, TaskExecutionBoundExceededError, type TaskExecutionPlan } from "../task/task-execution.ts";
 
-/**
- * VehicleRegistry only ever calls a schema's own safeParse -- jsonSchema is
- * descriptive metadata surfaced to a client/Pi projection, never itself
- * enforced at runtime -- so a declared `enum` has to be checked here for
- * real, or it's a documentation gesture, not an honest contract.
- */
+interface OperationSchemaNode {
+	readonly type?: string | readonly string[];
+	readonly enum?: readonly unknown[];
+	readonly properties?: Readonly<Record<string, OperationSchemaNode>>;
+	readonly required?: readonly string[];
+	readonly additionalProperties?: boolean | OperationSchemaNode;
+	readonly items?: OperationSchemaNode;
+	readonly minLength?: number;
+	readonly maxLength?: number;
+	readonly minimum?: number;
+	readonly maximum?: number;
+	readonly minItems?: number;
+	readonly maxItems?: number;
+	readonly description?: string;
+	readonly [key: string]: unknown;
+}
+
+function schemaIssue(path: readonly (string | number)[], message: string): VehicleSchemaIssue[] {
+	return [{ path, message }];
+}
+
+function matchesSchemaType(value: unknown, type: string): boolean {
+	if (type === "object") return typeof value === "object" && value !== null && !Array.isArray(value);
+	if (type === "array") return Array.isArray(value);
+	if (type === "string") return typeof value === "string";
+	if (type === "number") return typeof value === "number" && Number.isFinite(value);
+	if (type === "integer") return typeof value === "number" && Number.isInteger(value);
+	if (type === "boolean") return typeof value === "boolean";
+	return true;
+}
+
+function validateSchemaValue(value: unknown, schema: OperationSchemaNode, path: readonly (string | number)[]): VehicleSchemaIssue[] {
+	const label = path.length === 0 ? "input" : String(path.at(-1));
+	const declaredTypes = typeof schema.type === "string" ? [schema.type] : (schema.type ?? []);
+	const type = declaredTypes.find((candidate) => matchesSchemaType(value, candidate));
+	if (declaredTypes.length > 0 && type === undefined) {
+		const accepted = declaredTypes.map((candidate) =>
+			candidate === "integer" ? "an integer" : `${candidate === "object" ? "an" : "a"} ${candidate}`,
+		);
+		return schemaIssue(path, `${label} must be ${accepted.join(" or ")}`);
+	}
+	if (type === "object") {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return schemaIssue(path, `${label} must be an object`);
+		const record = value as Record<string, unknown>;
+		for (const key of schema.required ?? []) {
+			if (!(key in record)) {
+				const acceptedShape = schema.description ? `; ${schema.description}` : "";
+				return schemaIssue([...path, key], `${key} is required${acceptedShape}`);
+			}
+		}
+		for (const [key, child] of Object.entries(schema.properties ?? {})) {
+			if (!(key in record)) continue;
+			const issues = validateSchemaValue(record[key], child, [...path, key]);
+			if (issues.length > 0) return issues;
+		}
+		for (const key of Object.keys(record)) {
+			if (key in (schema.properties ?? {})) continue;
+			if (schema.additionalProperties === false) return schemaIssue([...path, key], `${key} is not allowed`);
+			if (typeof schema.additionalProperties === "object") {
+				const issues = validateSchemaValue(record[key], schema.additionalProperties, [...path, key]);
+				if (issues.length > 0) return issues;
+			}
+		}
+	} else if (type === "array") {
+		const entries = value as unknown[];
+		if (schema.minItems !== undefined && entries.length < schema.minItems) {
+			return schemaIssue(path, `${label} must contain at least ${schema.minItems} item(s)`);
+		}
+		if (schema.maxItems !== undefined && entries.length > schema.maxItems) {
+			return schemaIssue(path, `${label} cannot contain more than ${schema.maxItems} item(s)`);
+		}
+		if (schema.items) {
+			for (const [index, entry] of entries.entries()) {
+				const issues = validateSchemaValue(entry, schema.items, [...path, index]);
+				if (issues.length > 0) return issues;
+			}
+		}
+	} else if (type === "string") {
+		const text = value as string;
+		if (schema.minLength !== undefined && text.length < schema.minLength) {
+			return schemaIssue(path, `${label} must contain at least ${schema.minLength} character(s)`);
+		}
+		if (schema.maxLength !== undefined && text.length > schema.maxLength) {
+			return schemaIssue(path, `${label} cannot exceed ${schema.maxLength} character(s)`);
+		}
+	} else if (type === "number" || type === "integer") {
+		const number = value as number;
+		if (schema.minimum !== undefined && number < schema.minimum) {
+			return schemaIssue(path, `${label} must be at least ${schema.minimum}`);
+		}
+		if (schema.maximum !== undefined && number > schema.maximum) {
+			return schemaIssue(path, `${label} cannot exceed ${schema.maximum}`);
+		}
+	}
+	if (schema.enum && !schema.enum.includes(value)) {
+		return schemaIssue(path, `${label} must be one of ${schema.enum.join(", ")}`);
+	}
+	return [];
+}
+
+/** VehicleRegistry executes this codec before resolving or dispatching an operation. Keep the
+ * recursive runtime checks aligned with the same JSON Schema clients and tools_man receive. */
 export function looseObjectSchema(
-	properties: Record<string, { type: string; enum?: readonly string[] }>,
+	properties: Readonly<Record<string, OperationSchemaNode>>,
 	required: readonly string[] = [],
 ): VehicleSchemaCodec<Record<string, unknown>> {
+	const schema = { type: "object", properties, required: [...required], additionalProperties: false } as const;
 	return defineVehicleSchema<Record<string, unknown>>({
-		jsonSchema: { type: "object", properties, required: [...required], additionalProperties: false },
+		jsonSchema: schema as unknown as JsonSchema,
 		safeParse(value) {
-			if (typeof value !== "object" || value === null || Array.isArray(value)) {
-				return { success: false, issues: [{ path: [], message: "input must be an object" }] };
-			}
-			const input = value as Record<string, unknown>;
-			for (const key of required) {
-				if (!(key in input)) return { success: false, issues: [{ path: [key], message: `${key} is required` }] };
-			}
-			for (const [key, schema] of Object.entries(properties)) {
-				if (!schema.enum || !(key in input)) continue;
-				if (!schema.enum.includes(input[key] as string)) {
-					return { success: false, issues: [{ path: [key], message: `${key} must be one of ${schema.enum.join(", ")}` }] };
-				}
-			}
-			return { success: true, value: input };
+			const issues = validateSchemaValue(value, schema, []);
+			return issues.length > 0 ? { success: false, issues } : { success: true, value: value as Record<string, unknown> };
 		},
 	});
 }
@@ -249,7 +336,7 @@ export function buildWorkflowRunContent(
 
 export type OperationSchemaProperties = Record<
 	string,
-	{ type: string; enum?: readonly string[]; description?: string; [key: string]: unknown }
+	{ type: string | readonly string[]; enum?: readonly string[]; description?: string; [key: string]: unknown }
 >;
 
 export type DefineOperation = (

package/src/handlers/tasks.ts

@@ -81,6 +81,7 @@ const gateProp = {
 	description: "Validation gates run by tasks.run_gates and tasks.complete.",
 	items: {
 		type: "object",
+		description: "Accepted gate shape: {type, target, expect?, timeoutMs?}.",
 		properties: {
 			type: { type: "string", enum: GATE_TYPES, description: "Gate evaluator." },
 			target: { type: "string", minLength: 1, description: "Path, command, text target, or test command." },
@@ -109,6 +110,7 @@ const checklistProp = {
 				minItems: 1,
 				items: {
 					type: "object",
+					description: "Accepted proof shape: {type, target, expect?}.",
 					properties: {
 						type: { type: "string", enum: PROOF_TYPES },
 						target: { type: "string", minLength: 1 },
@@ -286,7 +288,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 
 	define(
 		"create",
-		"Creates a Task -- work: desired outcomes, gates, checklists, and dependencies. project_root is required (no ambient cwd server-side). Prefer parent_name/depends_on_names over parent_id/depends_on -- resolved server-side.",
+		'Creates a Task -- work: desired outcomes, gates, checklists, and dependencies. Gates are {type, target, expect?, timeoutMs?}; for example [{type: "command", target: "bun run typecheck", timeoutMs: 60000}]. Checklist criteria are {proof: [{type, target, expect?}]}. project_root is required (no ambient cwd server-side). Prefer parent_name/depends_on_names over parent_id/depends_on -- resolved server-side.',
 		"local-write",
 		{
 			title: stringProp,
@@ -752,11 +754,11 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 
 	define(
 		"claim",
-		"Claims this Task's lease under owner (defaults to session_id). Returns taskName (the reusable artifact alias) and taskTitle instead of exposing its backend UUID. Throws if a different owner already holds one.",
+		"Claims this Task's lease under owner (defaults to session_id). Prefer name over id. Returns taskName (the reusable artifact alias) and taskTitle instead of exposing its backend UUID. Throws if a different owner already holds one.",
 		"local-write",
 		{
-			id: stringProp,
 			name: stringProp,
+			id: stringProp,
 			owner: stringProp,
 			ttl_ms: numberProp,
 			note: stringProp,
@@ -772,11 +774,11 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 	);
 	define(
 		"heartbeat_lease",
-		"Extends this Task's lease -- needs the exact owner/token claim() returned and returns the reusable taskName plus taskTitle.",
+		"Extends this Task's lease -- needs the exact owner/token claim() returned. Prefer name over id. Returns the reusable taskName plus taskTitle.",
 		"local-write",
 		{
-			id: stringProp,
 			name: stringProp,
+			id: stringProp,
 			owner: stringProp,
 			token: stringProp,
 			ttl_ms: numberProp,
@@ -791,9 +793,9 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 	);
 	define(
 		"release_lease",
-		"Releases this Task's lease -- needs the exact owner/token claim() returned.",
+		"Releases this Task's lease -- needs the exact owner/token claim() returned. Prefer name over id.",
 		"local-write",
-		{ id: stringProp, name: stringProp, owner: stringProp, token: stringProp, project_root: stringProp, session_id: stringProp },
+		{ name: stringProp, id: stringProp, owner: stringProp, token: stringProp, project_root: stringProp, session_id: stringProp },
 		["owner", "token"],
 		(input) => ({
 			...input,
@@ -802,9 +804,9 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 	);
 	define(
 		"lease",
-		"Shows this Task's current lease, if any, identified by reusable taskName plus taskTitle rather than its backend UUID.",
+		"Shows this Task's current lease, if any. Prefer name over id. The result is identified by reusable taskName plus taskTitle rather than its backend UUID.",
 		"read",
-		{ id: stringProp, name: stringProp, project_root: stringProp },
+		{ name: stringProp, id: stringProp, project_root: stringProp },
 		[],
 		(input) => ({
 			...input,