@nghyane/arcane 0.1.8 → 0.1.11

package/src/tools/jtd-to-json-schema.ts

@@ -1,247 +0,0 @@
-/**
- * Convert JSON Type Definition (JTD) to JSON Schema.
- *
- * JTD (RFC 8927) is a simpler schema format. This converter allows users to
- * write schemas in JTD and have them converted to JSON Schema for model APIs.
- *
- * @see https://jsontypedef.com/
- * @see https://datatracker.ietf.org/doc/html/rfc8927
- */
-
-type JTDPrimitive =
-	| "boolean"
-	| "string"
-	| "timestamp"
-	| "float32"
-	| "float64"
-	| "int8"
-	| "uint8"
-	| "int16"
-	| "uint16"
-	| "int32"
-	| "uint32";
-
-interface JTDType {
-	type: JTDPrimitive;
-}
-
-interface JTDEnum {
-	enum: string[];
-}
-
-interface JTDElements {
-	elements: JTDSchema;
-}
-
-interface JTDValues {
-	values: JTDSchema;
-}
-
-interface JTDProperties {
-	properties?: Record<string, JTDSchema>;
-	optionalProperties?: Record<string, JTDSchema>;
-}
-
-interface JTDDiscriminator {
-	discriminator: string;
-	mapping: Record<string, JTDProperties>;
-}
-
-interface JTDRef {
-	ref: string;
-}
-
-interface JTDEmpty {}
-
-type JTDSchema = JTDType | JTDEnum | JTDElements | JTDValues | JTDProperties | JTDDiscriminator | JTDRef | JTDEmpty;
-
-const primitiveMap: Record<JTDPrimitive, string> = {
-	boolean: "boolean",
-	string: "string",
-	timestamp: "string", // ISO 8601
-	float32: "number",
-	float64: "number",
-	int8: "integer",
-	uint8: "integer",
-	int16: "integer",
-	uint16: "integer",
-	int32: "integer",
-	uint32: "integer",
-};
-
-function isJTDType(schema: unknown): schema is JTDType {
-	return typeof schema === "object" && schema !== null && "type" in schema;
-}
-
-function isJTDEnum(schema: unknown): schema is JTDEnum {
-	return typeof schema === "object" && schema !== null && "enum" in schema;
-}
-
-function isJTDElements(schema: unknown): schema is JTDElements {
-	return typeof schema === "object" && schema !== null && "elements" in schema;
-}
-
-function isJTDValues(schema: unknown): schema is JTDValues {
-	return typeof schema === "object" && schema !== null && "values" in schema;
-}
-
-function isJTDProperties(schema: unknown): schema is JTDProperties {
-	return typeof schema === "object" && schema !== null && ("properties" in schema || "optionalProperties" in schema);
-}
-
-function isJTDDiscriminator(schema: unknown): schema is JTDDiscriminator {
-	return typeof schema === "object" && schema !== null && "discriminator" in schema;
-}
-
-function isJTDRef(schema: unknown): schema is JTDRef {
-	return typeof schema === "object" && schema !== null && "ref" in schema;
-}
-
-function convertSchema(schema: unknown): unknown {
-	if (schema === null || typeof schema !== "object") {
-		return {};
-	}
-
-	// Type form: { type: "string" } → { type: "string" }
-	if (isJTDType(schema)) {
-		const jsonType = primitiveMap[schema.type as JTDPrimitive];
-		if (!jsonType) {
-			return { type: schema.type };
-		}
-		return { type: jsonType };
-	}
-
-	// Enum form: { enum: ["a", "b"] } → { enum: ["a", "b"] }
-	if (isJTDEnum(schema)) {
-		return { enum: schema.enum };
-	}
-
-	// Elements form: { elements: { type: "string" } } → { type: "array", items: ... }
-	if (isJTDElements(schema)) {
-		return {
-			type: "array",
-			items: convertSchema(schema.elements),
-		};
-	}
-
-	// Values form: { values: { type: "string" } } → { type: "object", additionalProperties: ... }
-	if (isJTDValues(schema)) {
-		return {
-			type: "object",
-			additionalProperties: convertSchema(schema.values),
-		};
-	}
-
-	// Properties form: { properties: {...}, optionalProperties: {...} }
-	if (isJTDProperties(schema)) {
-		const properties: Record<string, unknown> = {};
-		const required: string[] = [];
-
-		// Required properties
-		if (schema.properties) {
-			for (const [key, value] of Object.entries(schema.properties)) {
-				properties[key] = convertSchema(value);
-				required.push(key);
-			}
-		}
-
-		// Optional properties
-		if (schema.optionalProperties) {
-			for (const [key, value] of Object.entries(schema.optionalProperties)) {
-				properties[key] = convertSchema(value);
-			}
-		}
-
-		const result: Record<string, unknown> = {
-			type: "object",
-			properties,
-			additionalProperties: false,
-		};
-
-		if (required.length > 0) {
-			result.required = required;
-		}
-
-		return result;
-	}
-
-	// Discriminator form: { discriminator: "type", mapping: { ... } }
-	if (isJTDDiscriminator(schema)) {
-		const oneOf: unknown[] = [];
-
-		for (const [tag, props] of Object.entries(schema.mapping)) {
-			const converted = convertSchema(props) as Record<string, unknown>;
-			// Add the discriminator property
-			const properties = (converted.properties || {}) as Record<string, unknown>;
-			properties[schema.discriminator] = { const: tag };
-
-			const required = ((converted.required as string[]) || []).slice();
-			if (!required.includes(schema.discriminator)) {
-				required.push(schema.discriminator);
-			}
-
-			oneOf.push({
-				...converted,
-				properties,
-				required,
-			});
-		}
-
-		return { oneOf };
-	}
-
-	// Ref form: { ref: "MyType" } → { $ref: "#/$defs/MyType" }
-	if (isJTDRef(schema)) {
-		return { $ref: `#/$defs/${schema.ref}` };
-	}
-
-	// Empty form: {} → {} (accepts anything)
-	return {};
-}
-
-/**
- * Detect if a schema is JTD format (vs JSON Schema).
- *
- * JTD schemas use: type (primitives), properties, optionalProperties, elements, values, enum, discriminator, ref
- * JSON Schema uses: type: "object", type: "array", items, additionalProperties, etc.
- */
-export function isJTDSchema(schema: unknown): boolean {
-	if (schema === null || typeof schema !== "object") {
-		return false;
-	}
-
-	const obj = schema as Record<string, unknown>;
-
-	// JTD-specific keywords
-	if ("elements" in obj) return true;
-	if ("values" in obj) return true;
-	if ("optionalProperties" in obj) return true;
-	if ("discriminator" in obj) return true;
-	if ("ref" in obj) return true;
-
-	// JTD type primitives (JSON Schema doesn't have int32, float64, etc.)
-	if ("type" in obj) {
-		const jtdPrimitives = ["timestamp", "float32", "float64", "int8", "uint8", "int16", "uint16", "int32", "uint32"];
-		if (jtdPrimitives.includes(obj.type as string)) {
-			return true;
-		}
-	}
-
-	// JTD properties form without type: "object" (JSON Schema requires it)
-	if ("properties" in obj && !("type" in obj)) {
-		return true;
-	}
-
-	return false;
-}
-
-/**
- * Convert JTD schema to JSON Schema.
- * If already JSON Schema, returns as-is.
- */
-export function jtdToJsonSchema(schema: unknown): unknown {
-	if (!isJTDSchema(schema)) {
-		return schema;
-	}
-	return convertSchema(schema);
-}

package/src/tools/submit-result.ts

@@ -1,152 +0,0 @@
-/**
- * Submit result tool for structured subagent output.
- *
- * Subagents must call this tool to finish and return structured JSON output.
- */
-import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@nghyane/arcane-agent";
-import { StringEnum } from "@nghyane/arcane-ai";
-import type { Static, TObject } from "@sinclair/typebox";
-import { Type } from "@sinclair/typebox";
-import Ajv, { type ErrorObject, type ValidateFunction } from "ajv";
-import { subprocessToolRegistry } from "../task/subprocess-tool-registry";
-import type { ToolSession } from ".";
-import { jtdToJsonSchema } from "./jtd-to-json-schema";
-
-export interface SubmitResultDetails {
-	data: unknown;
-	status: "success" | "aborted";
-	error?: string;
-}
-
-const ajv = new Ajv({ allErrors: true, strict: false });
-
-function normalizeSchema(schema: unknown): { normalized?: unknown; error?: string } {
-	if (schema === undefined || schema === null) return {};
-	if (typeof schema === "string") {
-		try {
-			return { normalized: JSON.parse(schema) };
-		} catch (err) {
-			return { error: err instanceof Error ? err.message : String(err) };
-		}
-	}
-	return { normalized: schema };
-}
-
-function formatSchema(schema: unknown): string {
-	if (schema === undefined) return "No schema provided.";
-	if (typeof schema === "string") return schema;
-	try {
-		return JSON.stringify(schema, null, 2);
-	} catch {
-		return "[unserializable schema]";
-	}
-}
-
-function formatAjvErrors(errors: ErrorObject[] | null | undefined): string {
-	if (!errors || errors.length === 0) return "Unknown schema validation error.";
-	return errors
-		.map(err => {
-			const path = err.instancePath ? `${err.instancePath}: ` : "";
-			return `${path}${err.message ?? "invalid"}`;
-		})
-		.join("; ");
-}
-
-export class SubmitResultTool implements AgentTool<TObject, SubmitResultDetails> {
-	readonly name = "submit_result";
-	readonly label = "Submit Result";
-	readonly description =
-		"Finish the task with structured JSON output. Call exactly once at the end of the task.\n\n" +
-		"If you cannot complete the task, call with status='aborted' and an error message.";
-	readonly parameters: TObject;
-
-	readonly #validate?: ValidateFunction;
-	readonly #schemaError?: string;
-
-	constructor(session: ToolSession) {
-		const schemaResult = normalizeSchema(session.outputSchema);
-		// Convert JTD to JSON Schema if needed (auto-detected)
-		const normalizedSchema =
-			schemaResult.normalized !== undefined ? jtdToJsonSchema(schemaResult.normalized) : undefined;
-		let schemaError = schemaResult.error;
-
-		if (normalizedSchema !== undefined && !schemaError) {
-			try {
-				this.#validate = ajv.compile(normalizedSchema as any);
-			} catch (err) {
-				schemaError = err instanceof Error ? err.message : String(err);
-			}
-		}
-
-		this.#schemaError = schemaError;
-
-		const schemaHint = formatSchema(normalizedSchema ?? session.outputSchema);
-
-		// Use actual schema if provided, otherwise fall back to Type.Any
-		// Merge description into the JSON schema for better tool documentation
-		const dataSchema = normalizedSchema
-			? Type.Unsafe({
-					...(normalizedSchema as object),
-					description: `Structured output matching the schema:\n${schemaHint}`,
-				})
-			: Type.Any({ description: "Structured JSON output (no schema specified)" });
-
-		this.parameters = Type.Object({
-			data: Type.Optional(dataSchema),
-			status: Type.Optional(
-				StringEnum(["success", "aborted"], {
-					description: "Use 'aborted' if the task cannot be completed, defaults to 'success'",
-				}),
-			),
-			error: Type.Optional(Type.String({ description: "Error message when status is 'aborted'" })),
-		});
-	}
-
-	async execute(
-		_toolCallId: string,
-		params: Static<TObject>,
-		_signal?: AbortSignal,
-		_onUpdate?: AgentToolUpdateCallback<SubmitResultDetails>,
-		_context?: AgentToolContext,
-	): Promise<AgentToolResult<SubmitResultDetails>> {
-		const status = (params.status ?? "success") as "success" | "aborted";
-
-		// Skip validation when aborting - data is optional for aborts
-		if (status === "success") {
-			if (params.data === undefined || params.data === null) {
-				throw new Error("data is required when status is 'success' (got null/undefined)");
-			}
-			if (this.#schemaError) {
-				throw new Error(`Invalid output schema: ${this.#schemaError}`);
-			}
-			if (this.#validate && !this.#validate(params.data)) {
-				throw new Error(`Output does not match schema: ${formatAjvErrors(this.#validate.errors)}`);
-			}
-		}
-
-		const responseText =
-			status === "aborted" ? `Task aborted: ${params.error || "No reason provided"}` : "Result submitted.";
-
-		return {
-			content: [{ type: "text", text: responseText }],
-			details: { data: params.data, status, error: params.error as string | undefined },
-		};
-	}
-}
-
-// Register subprocess tool handler for extraction + termination.
-subprocessToolRegistry.register<SubmitResultDetails>("submit_result", {
-	extractData: event => {
-		const details = event.result?.details;
-		if (!details || typeof details !== "object") return undefined;
-		const record = details as Record<string, unknown>;
-		const status = record.status;
-		if (status !== "success" && status !== "aborted") return undefined;
-		return {
-			data: record.data,
-			status,
-			error: typeof record.error === "string" ? record.error : undefined,
-		};
-	},
-	shouldTerminate: event => !event.isError,
-});